Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

142 KB
Raw Blame
"""Agent loop: the core processing engine."""

from __future__ import annotations

import asyncio
import json
import re
import time
import uuid
from collections.abc import Callable
from contextlib import AsyncExitStack, aclosing
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING, Any

from loguru import logger

from openviking.utils.media_limits import MAX_INLINE_TOOL_RESULT_MEDIA_BYTES
from vikingbot.agent.context import ContextBuilder
from vikingbot.agent.memory import MemoryStore
from vikingbot.agent.remote_skills import SkillRuntimeContext
from vikingbot.agent.skills import SkillsLoader
from vikingbot.agent.subagent import SubagentManager
from vikingbot.agent.tools import register_default_tools
from vikingbot.agent.tools.base import TOOL_RESULT_DIRECTORY, MultimodalToolResult
from vikingbot.agent.tools.registry import ToolExecutionResult, ToolRegistry
from vikingbot.bus.events import InboundMessage, OutboundEventType, OutboundMessage
from vikingbot.bus.queue import MessageBus
from vikingbot.config.schema import BotMode, Config, SessionKey
from vikingbot.heartbeat.service import HEARTBEAT_METADATA_KEY, is_heartbeat_noop_response
from vikingbot.hooks import HookContext
from vikingbot.hooks.manager import hook_manager
from vikingbot.integrations.langfuse import LangfuseClient
from vikingbot.observability.outcome import evaluate_response_outcome, should_update_outcome
from vikingbot.openviking_mount.session_state import (
    get_openviking_session_id,
    get_openviking_state,
    get_unsynced_messages,
    parse_local_index,
    reset_openviking_state,
)
from vikingbot.providers.base import LLMProvider
from vikingbot.sandbox import SandboxManager
from vikingbot.session.manager import Session, SessionManager
from vikingbot.utils.helpers import cal_str_tokens, ensure_non_empty_assistant_content
from vikingbot.utils.tracing import set_response_id, trace

if TYPE_CHECKING:
    from vikingbot.config.schema import ExecToolConfig
    from vikingbot.cron.service import CronService


def _is_tool_result_success(result: Any) -> bool:
    if result is None or isinstance(result, Exception):
        return False
    text = str(result).lstrip()
    return bool(text) and not text.startswith("Error:")


def _compact_msg_chars(messages: list[dict]) -> int:
    return sum(len(json.dumps(m, ensure_ascii=False, default=str)) for m in messages)


def _base64_data_url_bytes(url: str) -> int:
    if not url.startswith("data:"):
        return 0
    marker = ";base64,"
    marker_index = url.find(marker)
    if marker_index < 0:
        return 0
    encoded_length = len(url) - marker_index - len(marker)
    if encoded_length <= 0:
        return 0
    padding = 2 if url.endswith("==") else 1 if url.endswith("=") else 0
    return max(0, encoded_length * 3 // 4 - padding)


def _inline_media_bytes(messages: list[dict]) -> int:
    total = 0
    for message in messages:
        content = message.get("content")
        if not isinstance(content, list):
            continue
        for part in content:
            if not isinstance(part, dict) or part.get("type") not in {
                "image_url",
                "input_image",
            }:
                continue
            image_url = part.get("image_url")
            url = image_url.get("url") if isinstance(image_url, dict) else image_url
            if isinstance(url, str):
                total += _base64_data_url_bytes(url)
    return total


def _demote_historical_tool_media(
    messages: list[dict], *, history_end: int, bytes_needed: int
) -> int:
    candidates: list[tuple[dict, int]] = []
    reclaimable_bytes = 0
    for message in messages[:history_end]:
        if message.get("role") != "tool" or not isinstance(message.get("content"), list):
            continue
        media_bytes = _inline_media_bytes([message])
        if media_bytes <= 0:
            continue
        candidates.append((message, media_bytes))
        reclaimable_bytes += media_bytes
        if reclaimable_bytes >= bytes_needed:
            break

    if reclaimable_bytes < bytes_needed:
        return 0

    for message, _media_bytes in candidates:
        text_parts = [
            part["text"]
            for part in message["content"]
            if isinstance(part, dict)
            and part.get("type") in {"text", "input_text"}
            and isinstance(part.get("text"), str)
        ]
        text = "\n".join(text_parts)
        omission_note = (
            "Media content from this earlier tool result was omitted from subsequent "
            "requests to keep the inline media budget."
        )
        message["content"] = f"{text}\n\n{omission_note}" if text else omission_note
    return reclaimable_bytes


def _compact_render_message(message: dict) -> str:
    role = message.get("role")
    content = message.get("content")
    if isinstance(content, (list, dict)):
        text_parts: list[str] = []

        def _collect(value: Any) -> None:
            if isinstance(value, str):
                if value.strip():
                    text_parts.append(value)
            elif isinstance(value, list):
                for item in value:
                    _collect(item)
            elif isinstance(value, dict):
                for key in ("text", "content"):
                    if key in value:
                        _collect(value[key])

        _collect(content)
        content = "\n".join(text_parts)

    body = str(content or "").strip()
    if role == "assistant":
        lines: list[str] = []
        if body:
            lines.append(body)
        for tool_call in message.get("tool_calls") or []:
            function = tool_call.get("function") or {}
            name = function.get("name") or "?"
            args = str(function.get("arguments") or "")
            lines.append(f"[tool_call] {name}({args})")
        if message.get("reasoning_content"):
            lines.append(f"[reasoning] {str(message.get('reasoning_content'))[:2_000]}")
        body = "\n".join(lines) or "(assistant)"
        label = "assistant"
    elif role == "tool":
        label = f"tool result: {message.get('name') or message.get('tool_name') or '?'}"
    else:
        label = str(role or "message")
    if len(body) > 6_000:
        body = body[:6_000] + "\n...<truncated>"
    return f"[{label}]\n{body}"


def _compact_split_into_blocks(messages: list[dict]) -> list[list[dict]]:
    blocks: list[list[dict]] = []
    i, n = 0, len(messages)
    while i < n:
        message = messages[i]
        if message.get("role") == "assistant" and message.get("tool_calls"):
            j = i + 1
            while j < n and messages[j].get("role") == "tool":
                j += 1
            blocks.append(messages[i:j])
            i = j
        else:
            blocks.append([messages[i]])
            i += 1
    return blocks


def _compact_render_transcript(messages: list[dict]) -> str:
    text = "\n\n".join(_compact_render_message(m) for m in messages)
    if len(text) > 256_000:
        text = "[... older transcript omitted ...]\n\n" + text[-256_000:]
    return text


def _compact_split_chunks(text: str) -> list[str]:
    if len(text) <= 32_000:
        return [text]
    return [text[i : i + 32_000] for i in range(0, len(text), 32_000)]


def _compact_strip_note_header(content: str) -> str:
    text = str(content or "").strip()
    if text.startswith("[Context compaction]"):
        text = text[len("[Context compaction]") :].strip()
    if text.startswith("Findings so far:"):
        text = text[len("Findings so far:") :].strip()
    return text.strip()


def _compact_build_note(previous_summary: str, new_summary: str) -> str:
    """Join complete compaction summaries without dropping saved facts or unfinished work."""
    previous = (previous_summary or "").strip()
    new = (new_summary or "").strip()
    parts = ["[Context compaction]"]
    if previous:
        parts.append(previous)
    if new:
        parts.append(f"## Progress since last compaction\n{new}" if previous else new)
    if not previous and not new:
        parts.append(
            "Earlier turns were compacted to fit the context window; earlier tool "
            "results are no longer quoted verbatim."
        )
    return "\n\n".join(parts)


@dataclass(slots=True)
class _PlainTextContext:
    """Context passed to an `on_plain_text` callback when the model emits plain text."""

    messages: list[dict]
    session_key: SessionKey
    text: str
    reasoning_content: str | None
    iteration: int
    tools: ToolRegistry
    sandbox_manager: SandboxManager | None
    sender_id: str | None
    memory_peer_ids: list[str] | None
    memory_owner_user_ids: list[str] | None
    openviking_connection: dict[str, Any] | None


@dataclass(slots=True)
class _PlainTextDelivered:
    """Signal that the text was delivered externally; continue the loop with new state."""

    messages: list[dict]
    tools_used: list[dict]
    user_terminates: bool = False


@dataclass(slots=True)
class _PlainTextFinal:
    """Signal that the text should be treated as the final reply; exit the loop."""

    content: str | None = None


@dataclass(slots=True)
class _PreparedSteer:
    """Preprocessed same-session input to merge into an active agent loop."""

    msg: InboundMessage
    prompt_messages: list[dict[str, Any]]
    newly_recalled_exp_uris: list[str]
    newly_recalled_exp_content: str
    auto_memory_tool: dict[str, Any] | None = None


@dataclass(slots=True)
class _AcceptedSteer:
    """A steer accepted by the active turn and its in-flight preprocessing."""

    msg: InboundMessage
    task: asyncio.Task[_PreparedSteer]


@dataclass(slots=True)
class _AssistantBoundary:
    """A plain-text reply emitted before later steer input continued the turn."""

    content: str
    reasoning_content: str | None = None


@dataclass(slots=True)
class _ActiveTurn:
    """The single turn currently running in the serial AgentLoop."""

    session_key: SessionKey
    task: asyncio.Task
    interruptible: bool = True
    interrupted: bool = False
    accepting_steer: bool = True
    accepted_steers: list[_AcceptedSteer] = field(default_factory=list)
    history_items: list[_PreparedSteer | _AssistantBoundary] = field(default_factory=list)


class AgentIterationLimitExceeded(RuntimeError):
    """A structured task used every available AgentLoop iteration without submitting."""

    def __init__(self, max_iterations: int, *, usage: dict[str, Any] | None = None):
        self.max_iterations = max_iterations
        self.usage = usage or {}
        super().__init__(
            f"Agent reached its {max_iterations}-iteration limit without submitting a valid bundle"
        )


def render_budget_reminder(
    remaining: int,
    thresholds: tuple[int, int, int] = (15, 8, 3),
) -> str | None:
    """Return a submission reminder within descending heads-up, warning and critical thresholds."""
    heads_up, warn, critical = thresholds
    remaining = max(0, remaining)
    if remaining <= critical:
        return (
            f"还剩 {remaining} 轮。收集子任务结果,检查并调用 submit_wiki_bundle;不再开启新任务。"
        )
    elif remaining <= warn:
        return (
            f"还剩 {remaining} 轮。必须开始提交:把当前最好结果通过 submit_wiki_bundle "
            "提交,不要追求完美。"
        )
    elif remaining <= heads_up:
        return (
            f"还剩 {remaining} 轮。请停止对已读文件的全量重扫,开始把已有发现收敛成最终产物,"
            "并准备调用 submit_wiki_bundle。"
        )
    return None


class AgentLoop:
    """
    The agent loop is the core processing engine.

    It:
    1. Receives messages from the bus
    2. Builds context with history, memory, skills
    3. Calls the LLM
    4. Executes tool calls
    5. Sends responses back
    """

    def __init__(
        self,
        bus: MessageBus,
        provider: LLMProvider,
        workspace: Path,
        model: str | None = None,
        temperature: float = 0.7,
        max_iterations: int = 50,
        memory_window: int = 50,
        brave_api_key: str | None = None,
        exa_api_key: str | None = None,
        gen_image_model: str | None = None,
        exec_config: "ExecToolConfig | None" = None,
        cron_service: "CronService | None" = None,
        session_manager: SessionManager | None = None,
        sandbox_manager: SandboxManager | None = None,
        config: Config = None,
        eval: bool = False,
        mcp_servers: dict | None = None,
    ):
        """
        Initialize the AgentLoop with all required dependencies and configuration.

        Args:
            bus: MessageBus instance for publishing and subscribing to messages.
            provider: LLMProvider instance for making LLM calls.
            workspace: Path to the workspace directory for file operations.
            model: Optional model identifier. If not provided, uses the provider's default.
            temperature: Sampling temperature for LLM requests (default: 0.7).
            max_iterations: Maximum number of tool execution iterations per message (default: 50).
            memory_window: Maximum number of messages to keep in session memory (default: 50).
            brave_api_key: Optional API key for Brave search integration.
            exa_api_key: Optional API key for Exa search integration.
            gen_image_model: Optional model identifier for image generation (default: openai/doubao-seedream-4-5-251128).
            exec_config: Optional configuration for the exec tool (command execution).
            cron_service: Optional CronService for scheduled task management.
            session_manager: Optional SessionManager for session persistence. If not provided, a new one is created.
            sandbox_manager: Optional SandboxManager for sandboxed operations.
            config: Optional Config object with full configuration. Used if other parameters are not provided.

        Note:
            The AgentLoop creates its own ContextBuilder, SessionManager (if not provided),
            ToolRegistry, and SubagentManager during initialization.

        Example:
            >>> loop = AgentLoop(
            ...     bus=message_bus,
            ...     provider=llm_provider,
            ...     workspace=Path("/path/to/workspace"),
            ...     model="gpt-4",
            ...     max_iterations=30,
            ... )
        """
        from vikingbot.config.schema import ExecToolConfig  # noqa: F811

        self.bus = bus
        self.provider = provider
        self.workspace = workspace
        self.model = model or provider.get_default_model()
        self.temperature = temperature
        self.max_iterations = max_iterations
        self.memory_window = memory_window
        self.brave_api_key = brave_api_key
        self.exa_api_key = exa_api_key
        self.gen_image_model = gen_image_model or "openai/doubao-seedream-4-5-251128"
        self.exec_config = exec_config or ExecToolConfig()
        self.cron_service = cron_service
        self.sandbox_manager = sandbox_manager
        self.config = config

        self.context = ContextBuilder(
            workspace,
            sandbox_manager=sandbox_manager,
            enable_subagents=self._subagents_enabled(),
            config=self.config,
        )

        self._register_builtin_hooks()
        self.sessions = session_manager or SessionManager(
            self.config.bot_data_path, sandbox_manager=sandbox_manager
        )
        self.tools = ToolRegistry(config=self.config)
        self._eval = eval
        self.subagents = SubagentManager(
            provider=provider,
            workspace=workspace,
            bus=bus,
            config=self.config,
            model=self.model,
            temperature=self.temperature,
            sandbox_manager=sandbox_manager,
        )

        self._running = False
        self._mcp_servers = mcp_servers or {}
        self._mcp_stack: AsyncExitStack | None = None
        self._mcp_connected = False
        self._mcp_connecting = False
        self._ov_clients: dict[str, Any] = {}
        self._active_turn: _ActiveTurn | None = None
        self._queued_interrupt_counts: dict[SessionKey, int] = {}
        self._register_default_tools()

    async def _connect_mcp(self) -> None:
        """Connect to configured MCP servers (one-time, lazy, retryable on failure).

        Ported from HKUDS/nanobot v0.1.5.
        """
        if self._mcp_connected or self._mcp_connecting or not self._mcp_servers:
            return
        self._mcp_connecting = True
        try:
            from vikingbot.agent.tools.mcp import connect_mcp_servers

            self._mcp_stack = AsyncExitStack()
            await self._mcp_stack.__aenter__()
            await connect_mcp_servers(self._mcp_servers, self.tools, self._mcp_stack)
            self._mcp_connected = True
        except Exception as e:
            logger.error(f"Failed to connect MCP servers (will retry next message): {e}")
            if self._mcp_stack:
                try:
                    await self._mcp_stack.aclose()
                except Exception:
                    pass
                self._mcp_stack = None
        finally:
            self._mcp_connecting = False

    async def close_mcp(self) -> None:
        """Close MCP server connections. Ported from HKUDS/nanobot v0.1.5."""
        if self._mcp_stack:
            try:
                await self._mcp_stack.aclose()
            except Exception:
                pass  # MCP SDK cancel scope cleanup is noisy but harmless
            self._mcp_stack = None
        self._mcp_connected = False

    async def _publish_auto_memory_context(
        self,
        session_key: SessionKey,
        query: str,
        result: str,
        *,
        publish_events: bool = True,
    ) -> dict[str, Any]:
        """Expose automatic OpenViking memory lookup using the existing tool event stream."""
        args_str = json.dumps({"query": query}, ensure_ascii=False)
        if publish_events:
            await self.bus.publish_outbound(
                OutboundMessage(
                    session_key=session_key,
                    content=f"auto_memory_search({args_str})",
                    event_type=OutboundEventType.TOOL_CALL,
                )
            )
            await self.bus.publish_outbound(
                OutboundMessage(
                    session_key=session_key,
                    content=result,
                    event_type=OutboundEventType.TOOL_RESULT,
                )
            )
        return {
            "tool_name": "auto_memory_search",
            "args": args_str,
            "result": result,
            "duration": 0,
            "execute_success": True,
            "input_token": cal_str_tokens(query, text_type="mixed"),
            "output_token": cal_str_tokens(result, text_type="mixed"),
            "auto": True,
        }

    async def _chat_with_stream_events(
        self,
        messages: list[dict[str, Any]],
        tools: list[dict[str, Any]],
        session_key: SessionKey,
        publish_events: bool,
        *,
        agent_id: str = "main",
        iteration: int | None = None,
    ) -> tuple[Any, bool, bool]:
        """Forward provider events and log caller-observed timing for one model call.

        Agent ID and iteration identify concurrent loops without changing their sessions.
        Return the response and content/reasoning-stream flags; publish_events controls
        forwarding deltas to the bus independently of timing logs.
        Millisecond offsets include provider capacity waits and retries. The first event
        can be a buffered final response, so it is not necessarily a first-token time.
        Missing delta timings are null. Errors and cancellation propagate after logging;
        request bodies, reasoning text and tool arguments are excluded from timing logs.
        """
        streamed_content = False
        streamed_reasoning = False
        response = None
        log_context = {
            "call_id": uuid.uuid4().hex,
            "session_id": session_key.safe_name(),
            "agent_id": agent_id,
            "iteration": iteration,
            "model": self.model,
            "message_count": len(messages),
            "input_chars": _compact_msg_chars(messages),
        }
        first_events: dict[str, Any] = {
            "first_event_ms": None,
            "first_event_type": None,
            "first_reasoning_ms": None,
            "first_content_ms": None,
        }
        status, error_type = "ok", None
        fallback = False
        logger.info("[LLM_START] {}", json.dumps(log_context, ensure_ascii=False))
        started = time.perf_counter()
        try:
            async with aclosing(
                self.provider.chat_stream(
                    messages=messages,
                    tools=tools,
                    model=self.model,
                    temperature=self.temperature,
                    session_id=session_key.safe_name(),
                )
            ) as stream:
                async for event in stream:
                    elapsed_ms = round((time.perf_counter() - started) * 1000, 1)
                    if first_events["first_event_ms"] is None and (
                        event.type == "response" or event.content
                    ):
                        first_events.update(first_event_ms=elapsed_ms, first_event_type=event.type)
                    if event.type == "content_delta":
                        if event.content:
                            if first_events["first_content_ms"] is None:
                                first_events["first_content_ms"] = elapsed_ms
                            streamed_content = True
                            if publish_events:
                                await self.bus.publish_outbound(
                                    OutboundMessage(
                                        session_key=session_key,
                                        content=event.content,
                                        event_type=OutboundEventType.CONTENT_DELTA,
                                    )
                                )
                    elif event.type == "reasoning_delta":
                        if event.content:
                            if first_events["first_reasoning_ms"] is None:
                                first_events["first_reasoning_ms"] = elapsed_ms
                            streamed_reasoning = True
                            if publish_events:
                                await self.bus.publish_outbound(
                                    OutboundMessage(
                                        session_key=session_key,
                                        content=event.content,
                                        event_type=OutboundEventType.REASONING_DELTA,
                                    )
                                )
                    elif event.type == "response":
                        response = event.response

            if response is None:
                fallback = True
                response = await self.provider.chat(
                    messages=messages,
                    tools=tools,
                    model=self.model,
                    temperature=self.temperature,
                    session_id=session_key.safe_name(),
                )
            if response.finish_reason == "error":
                status = "error"
            return response, streamed_content, streamed_reasoning
        except asyncio.CancelledError:
            status, error_type = "cancelled", "CancelledError"
            raise
        except Exception as exc:
            status, error_type = "error", type(exc).__name__
            raise
        finally:
            logger.info(
                "[LLM_END] {}",
                json.dumps(
                    {
                        **log_context,
                        **first_events,
                        "duration_ms": round((time.perf_counter() - started) * 1000, 1),
                        "status": status,
                        "error_type": error_type,
                        "fallback": fallback,
                        "finish_reason": response.finish_reason if response is not None else None,
                        "usage": response.usage if response is not None else {},
                        "tool_names": (
                            [call.name for call in response.tool_calls]
                            if response is not None
                            else []
                        ),
                    },
                    ensure_ascii=False,
                ),
            )

    def _register_builtin_hooks(self):
        """Register built-in hooks."""
        hook_manager.register_path(self.config.hooks)

    def _register_default_tools(self) -> None:
        """Register default set of tools."""
        register_default_tools(
            registry=self.tools,
            config=self.config,
            send_callback=self.bus.publish_outbound,
            subagent_manager=self.subagents,
            cron_service=self.cron_service,
            include_spawn_tool=self._subagents_enabled(),
            include_viking_tools=self.config.ov_server.is_available(),
        )

    def _subagents_enabled(self) -> bool:
        agents_config = getattr(self.config, "agents", None)
        return bool(getattr(agents_config, "subagent_enabled", True))

    def _ov_session_context_enabled(self) -> bool:
        agents_config = getattr(self.config, "agents", None)
        return bool(
            self.config.ov_server.is_available()
            and agents_config
            and getattr(agents_config, "session_context_enabled", False)
        )

    def _get_ov_workspace_id(self, session_key: SessionKey) -> str:
        if self.sandbox_manager:
            return self.sandbox_manager.to_workspace_id(session_key)
        return "shared"

    async def _get_ov_client(
        self,
        session_key: SessionKey,
        openviking_connection: dict[str, Any] | None = None,
        actor_peer_id: str | None = None,
    ):
        workspace_id = self._get_ov_workspace_id(session_key)
        if openviking_connection or actor_peer_id:
            from vikingbot.openviking_mount.ov_server import VikingClient

            return await VikingClient.create(
                workspace_id,
                connection=openviking_connection,
                actor_peer_id=actor_peer_id,
                config=self.config,
            )

        client = self._ov_clients.get(workspace_id)
        if client is None:
            from vikingbot.openviking_mount.ov_server import VikingClient

            client = await VikingClient.create(workspace_id, config=self.config)
            self._ov_clients[workspace_id] = client
        return client

    def _format_history_messages(
        self,
        session: Session,
        messages: list[dict[str, Any]],
        provider_name: str | None = None,
    ) -> list[dict[str, Any]]:
        if not messages:
            return []
        temp_session = Session(key=session.key, messages=list(messages), metadata=session.metadata)
        return temp_session.get_history(max_messages=len(messages), provider_name=provider_name)

    @staticmethod
    def _flatten_ov_message_text(message: dict[str, Any]) -> str:
        content = message.get("content")
        if isinstance(content, str) and content.strip():
            return content.strip()

        text_parts: list[str] = []
        for part in message.get("parts") or []:
            if not isinstance(part, dict):
                continue
            for key in ("text", "abstract", "tool_output"):
                value = part.get(key)
                if isinstance(value, str) and value.strip():
                    text_parts.append(value.strip())
        return "\n".join(text_parts).strip()

    def _build_ov_history_messages(
        self,
        session: Session,
        context_payload: dict[str, Any],
        provider_name: str | None = None,
    ) -> list[dict[str, Any]]:
        raw_messages: list[dict[str, Any]] = []
        overview = str(context_payload.get("latest_archive_overview") or "").strip()
        if overview:
            raw_messages.append(
                {
                    "role": "assistant",
                    "content": ensure_non_empty_assistant_content(
                        f"[Earlier conversation summary]\n{overview}"
                    ),
                }
            )

        for message in context_payload.get("messages") or []:
            if not isinstance(message, dict):
                continue
            role = str(message.get("role") or "").strip().lower()
            if role not in {"user", "assistant"}:
                continue
            text = self._flatten_ov_message_text(message)
            if not text:
                continue
            raw_messages.append(
                {
                    "role": role,
                    "content": (
                        ensure_non_empty_assistant_content(text) if role == "assistant" else text
                    ),
                }
            )

        return self._format_history_messages(
            session,
            raw_messages,
            provider_name=provider_name,
        )

    @staticmethod
    def _history_message_tokens(message: dict[str, Any]) -> int:
        """Estimate prompt tokens for one formatted history message."""
        content = message.get("content", "")
        if not isinstance(content, str):
            content = json.dumps(content, ensure_ascii=False, default=str)
        # Reserve a small amount for the role and provider message framing.
        return cal_str_tokens(content, text_type="mixed") + 4

    @classmethod
    def _truncate_history_message(
        cls,
        message: dict[str, Any],
        token_budget: int,
    ) -> dict[str, Any] | None:
        """Return a prompt-only copy of a message clipped to ``token_budget``."""
        if token_budget <= 4:
            return None

        content = message.get("content", "")
        if not isinstance(content, str) or not content:
            return None

        content_budget = token_budget - 4
        marker = "\n[History truncated to fit session context token budget]"

        def fits(value: str) -> bool:
            return cal_str_tokens(value, text_type="mixed") <= content_budget

        low = 0
        high = len(content)
        best = ""
        while low <= high:
            mid = (low + high) // 2
            candidate = content[:mid] + (marker if mid < len(content) else "")
            if fits(candidate):
                best = candidate
                low = mid + 1
            else:
                high = mid - 1

        # Very small budgets may not fit the marker. Preserve as much raw text
        # as possible while still honoring the hard limit.
        if not best:
            # Empty content is not a valid candidate and breaks the monotonic
            # assumption of this binary search: "" is rejected while a
            # one-character prefix may fit.
            low = 1
            high = len(content)
            while low <= high:
                mid = (low + high) // 2
                candidate = content[:mid]
                if candidate and fits(candidate):
                    best = candidate
                    low = mid + 1
                else:
                    high = mid - 1

        if not best:
            return None

        clipped = dict(message)
        clipped["content"] = best
        # Reasoning is not part of OV session messages. Drop any provider-only
        # reasoning field from a clipped local fallback message so it cannot
        # silently exceed the session-history budget.
        clipped.pop("reasoning_content", None)
        return clipped

    @classmethod
    def _trim_history_to_token_budget(
        cls,
        messages: list[dict[str, Any]],
        token_budget: int,
    ) -> list[dict[str, Any]]:
        """Fit history to a hard budget without dropping the latest User anchor."""
        if token_budget <= 0 or not messages:
            return []

        total_tokens = sum(cls._history_message_tokens(message) for message in messages)
        if total_tokens <= token_budget:
            return messages

        latest_anchor_index = next(
            (
                index
                for index in range(len(messages) - 1, -1, -1)
                if messages[index].get("role") == "user"
            ),
            None,
        )
        if latest_anchor_index is None:
            # Legacy assistant-only history has no Turn boundary to preserve.
            remaining = token_budget
            retained_reversed: list[dict[str, Any]] = []
            for message in reversed(messages):
                message_tokens = cls._history_message_tokens(message)
                if message_tokens <= remaining:
                    retained_reversed.append(message)
                    remaining -= message_tokens
                    continue

                clipped = cls._truncate_history_message(message, remaining)
                if clipped is not None:
                    retained_reversed.append(clipped)
                break
            return list(reversed(retained_reversed))

        final_index = next(
            (
                index
                for index in range(len(messages) - 1, latest_anchor_index, -1)
                if messages[index].get("role") == "assistant"
            ),
            None,
        )

        selected: dict[int, dict[str, Any]] = {}
        used_tokens = 0

        def _select_message(
            index: int,
            *,
            allow_truncate: bool,
            max_budget: int | None = None,
        ) -> tuple[bool, bool]:
            nonlocal used_tokens
            remaining = max(0, token_budget - used_tokens)
            if max_budget is not None:
                remaining = min(remaining, max(0, int(max_budget)))

            message = messages[index]
            message_tokens = cls._history_message_tokens(message)
            chosen = message
            truncated = False
            if message_tokens > remaining:
                if not allow_truncate or remaining <= 0:
                    return False, False
                clipped = cls._truncate_history_message(message, remaining)
                if clipped is None:
                    return False, False
                chosen = clipped
                truncated = True

            selected[index] = chosen
            used_tokens += cls._history_message_tokens(chosen)
            return True, truncated

        def _minimum_message_budget(index: int) -> int | None:
            message = messages[index]
            message_tokens = cls._history_message_tokens(message)
            if message_tokens == 0:
                return 0

            low = 1
            high = min(message_tokens, token_budget)
            minimum: int | None = None
            while low <= high:
                candidate = (low + high) // 2
                if cls._truncate_history_message(message, candidate) is not None:
                    minimum = candidate
                    high = candidate - 1
                else:
                    low = candidate + 1
            return minimum

        # OpenViking already returns Turn-aware context, but VikingBot applies a
        # second budget with a different estimator after adding the local tail.
        # Jointly reserve room for the latest User anchor and final Assistant so
        # this final boundary cannot turn the prompt back into a half Turn.
        final_reserve = 0
        if final_index is not None:
            anchor_minimum = _minimum_message_budget(latest_anchor_index)
            final_minimum = _minimum_message_budget(final_index)
            if (
                anchor_minimum is not None
                and final_minimum is not None
                and anchor_minimum + final_minimum <= token_budget
            ):
                final_reserve = min(
                    cls._history_message_tokens(messages[final_index]),
                    max(final_minimum, token_budget // 2),
                    token_budget - anchor_minimum,
                )

        _select_message(
            latest_anchor_index,
            allow_truncate=True,
            max_budget=token_budget - final_reserve,
        )
        if final_index is not None:
            _select_message(final_index, allow_truncate=True)

        # Prefer the newest remaining Steps in the latest Turn. At most one Step
        # is clipped; older material is useful only while this suffix remains
        # lossless.
        latest_turn_end = final_index if final_index is not None else len(messages)
        for index in range(latest_turn_end - 1, latest_anchor_index, -1):
            kept, truncated = _select_message(index, allow_truncate=True)
            if not kept or truncated:
                break

        # Add older Turns only as complete units so the final prompt never starts
        # from the assistant half of an earlier Turn. An assistant-only prefix
        # such as the archive overview is treated as one conservative unit.
        older_turns: list[list[int]] = []
        current_turn: list[int] = []
        for index in range(latest_anchor_index):
            if messages[index].get("role") == "user" and current_turn:
                older_turns.append(current_turn)
                current_turn = []
            current_turn.append(index)
        if current_turn:
            older_turns.append(current_turn)

        remaining = token_budget
        remaining -= used_tokens
        for turn_indexes in reversed(older_turns):
            turn_tokens = sum(
                cls._history_message_tokens(messages[index]) for index in turn_indexes
            )
            if turn_tokens > remaining:
                break
            for index in turn_indexes:
                selected[index] = messages[index]
            used_tokens += turn_tokens
            remaining -= turn_tokens

        return [selected[index] for index in sorted(selected)]

    async def _build_prompt_history(
        self,
        session: Session,
        provider_name: str | None = None,
        openviking_connection: dict[str, Any] | None = None,
        actor_peer_id: str | None = None,
    ) -> list[dict[str, Any]]:
        if get_openviking_state(session).get("working_memory_confirmed") is False:
            # A rejected WM request must not replace local history with an OV tail.
            return session.get_history(
                max_messages=len(session.messages), provider_name=provider_name
            )
        if not self._ov_session_context_enabled():
            return session.get_history(provider_name=provider_name)

        agents_config = getattr(self.config, "agents", None)
        token_budget = int(getattr(agents_config, "session_context_token_budget", 12000) or 12000)
        session_id = get_openviking_session_id(session)
        request_client = None

        try:
            client = await self._get_ov_client(
                session.key,
                openviking_connection=openviking_connection,
                actor_peer_id=actor_peer_id,
            )
            if openviking_connection or actor_peer_id:
                request_client = client
            context_payload = await client.get_session_context(
                session_id=session_id,
                token_budget=token_budget,
            )
            ov_history = self._build_ov_history_messages(
                session,
                context_payload,
                provider_name=provider_name,
            )
            unsynced_messages = get_unsynced_messages(session)
            if not ov_history and len(unsynced_messages) < len(session.messages):
                logger.warning(
                    f"OpenViking returned no session context for {session_id}; "
                    "falling back to complete local session history."
                )
                unsynced_messages = session.messages
            local_tail = self._format_history_messages(
                session,
                unsynced_messages,
                provider_name=provider_name,
            )
            combined_history = ov_history + local_tail
            trimmed_history = self._trim_history_to_token_budget(
                combined_history,
                token_budget,
            )
            if len(trimmed_history) != len(combined_history) or any(
                before.get("content") != after.get("content")
                for before, after in zip(
                    combined_history[-len(trimmed_history) :],
                    trimmed_history,
                    strict=False,
                )
            ):
                logger.info(
                    f"Trimmed OpenViking session history for {session_id} to "
                    f"token_budget={token_budget}: messages={len(combined_history)}"
                    f"->{len(trimmed_history)}"
                )
            return trimmed_history
        except Exception as e:
            logger.warning(
                f"Failed to load OpenViking session context for {session_id}: {e}. "
                "Falling back to local session history."
            )
            return session.get_history(provider_name=provider_name)
        finally:
            if request_client is not None:
                await request_client.close()

    async def _submit_openviking_session(
        self,
        session: Session,
        *,
        force_commit: bool = False,
        keep_recent_turn_count: int | None = None,
        commit_message_threshold: int | None = None,
        openviking_connection: dict[str, Any] | None = None,
    ) -> bool:
        if not self._ov_session_context_enabled():
            return False

        state = get_openviking_state(session)
        state.pop("last_commit_performed", None)
        kwargs: dict[str, Any] = {
            "session": session,
            "force_commit": force_commit,
        }
        if keep_recent_turn_count is not None:
            kwargs["keep_recent_turn_count"] = keep_recent_turn_count
        if commit_message_threshold is not None:
            kwargs["commit_message_threshold"] = commit_message_threshold
        if openviking_connection:
            kwargs["openviking_connection"] = openviking_connection

        await hook_manager.execute_hooks(
            context=HookContext(
                event_type="message.compact",
                session_id=get_openviking_session_id(session),
                workspace_id=self._get_ov_workspace_id(session.key),
                session_key=session.key,
                config=self.config,
                openviking_connection=openviking_connection,
            ),
            **kwargs,
        )
        await self.sessions.save(session)
        return get_openviking_state(session).get("last_sync_status") == "success"

    async def _submit_openviking_session_and_clear_if_committed(
        self,
        session: Session,
        *,
        force_commit: bool = False,
        keep_recent_turn_count: int | None = None,
        commit_message_threshold: int | None = None,
        openviking_connection: dict[str, Any] | None = None,
    ) -> bool:
        success = await self._submit_openviking_session(
            session,
            force_commit=force_commit,
            keep_recent_turn_count=keep_recent_turn_count,
            commit_message_threshold=commit_message_threshold,
            openviking_connection=openviking_connection,
        )
        if not success:
            return False
        if not get_openviking_state(session).get("last_commit_performed"):
            return True

        session.clear()
        reset_openviking_state(session, rotate_session_id=False)
        state = get_openviking_state(session)
        state["last_sync_status"] = "success"
        await self.sessions.save(session)
        return True

    async def _maybe_commit_openviking_before_turn(
        self,
        session: Session,
        msg: InboundMessage,
    ) -> None:
        if not self._ov_session_context_enabled():
            return

        agents_config = getattr(self.config, "agents", None)
        if agents_config is None:
            return

        state = get_openviking_state(session)
        pending_tokens = int(state.get("last_pending_tokens", 0) or 0)
        commit_token_threshold = int(getattr(agents_config, "commit_token_threshold", 6000) or 6000)
        incoming_tokens = cal_str_tokens(msg.content or "")
        last_commit_local_index = parse_local_index(state.get("last_commit_local_index", -1))
        messages_since_commit = len(session.messages) - last_commit_local_index - 1
        incoming_messages_count = 1
        should_commit = bool(
            pending_tokens >= commit_token_threshold
            or pending_tokens + incoming_tokens >= commit_token_threshold
            or messages_since_commit + incoming_messages_count >= self.memory_window
        )
        if not should_commit:
            return

        await self._submit_openviking_session_and_clear_if_committed(
            session,
            force_commit=True,
            keep_recent_turn_count=int(
                getattr(agents_config, "commit_keep_recent_turn_count", 3) or 0
            ),
            commit_message_threshold=self.memory_window,
            openviking_connection=getattr(msg, "openviking_connection", None),
        )

    async def _commit_openviking_session(
        self,
        session: Session,
        *,
        keep_recent_turn_count: int = 0,
        clear_local_session: bool = False,
        rotate_session_id: bool = False,
        openviking_connection: dict[str, Any] | None = None,
    ) -> bool:
        success = await self._submit_openviking_session(
            session,
            force_commit=True,
            keep_recent_turn_count=keep_recent_turn_count,
            openviking_connection=openviking_connection,
        )
        if not success:
            return False
        if clear_local_session:
            session.clear()
            reset_openviking_state(session, rotate_session_id=rotate_session_id)
            state = get_openviking_state(session)
            state["last_sync_status"] = "success"
            await self.sessions.save(session)
        return True

    async def run(self) -> None:
        """Run the agent loop, processing messages from the bus."""
        self._running = True
        await self._connect_mcp()
        logger.info("Agent loop started")

        while self._running:
            try:
                # Wait for next message
                msg = await self.bus.consume_inbound()

                # Process it
                try:
                    queued_interrupts = self._queued_interrupt_counts.get(msg.session_key, 0)
                    if queued_interrupts > 0:
                        if queued_interrupts == 1:
                            self._queued_interrupt_counts.pop(msg.session_key, None)
                        else:
                            self._queued_interrupt_counts[msg.session_key] = queued_interrupts - 1
                        response = await self._complete_interrupted_message(msg)
                    else:
                        response = await self._process_message_as_active_turn(msg)
                    if response:
                        await self.bus.publish_outbound(response)
                except asyncio.CancelledError:
                    raise
                except Exception as e:
                    logger.exception(f"Error processing message: {e}")
                    # Send error response
                    await self.bus.publish_outbound(
                        OutboundMessage(
                            session_key=msg.session_key,
                            content=f"Sorry, I encountered an error: {str(e)}",
                            metadata=msg.metadata,
                        )
                    )
            except asyncio.TimeoutError:
                continue

    async def interrupt(self, session_key: SessionKey) -> bool:
        """Interrupt the active or already queued turn for a session."""
        active = self._active_turn
        if (
            active
            and active.session_key == session_key
            and active.interruptible
            and not active.task.done()
        ):
            pending_count = self.bus.count_pending_inbound_session(session_key)
            if pending_count:
                self._queued_interrupt_counts[session_key] = pending_count
            active.interrupted = True
            active.task.cancel()
            return True
        pending_count = self.bus.count_pending_inbound_session(session_key)
        queued_interrupts = self._queued_interrupt_counts.get(session_key, 0)
        if queued_interrupts < pending_count:
            self._queued_interrupt_counts[session_key] = pending_count
            return True
        return False

    def steer(self, msg: InboundMessage) -> bool:
        """Attach same-session input directly to the active turn."""
        active = self._active_turn
        if (
            active is None
            or active.session_key != msg.session_key
            or not active.accepting_steer
            or active.interrupted
            or active.task.done()
            or not msg.need_reply
            or msg.content.strip().startswith("/")
        ):
            return False
        active.accepted_steers.append(
            _AcceptedSteer(
                msg=msg,
                task=asyncio.create_task(self._prepare_steer_message(msg)),
            )
        )
        return True

    async def _process_message_as_active_turn(self, msg: InboundMessage) -> OutboundMessage | None:
        active: _ActiveTurn

        async def run_active_message() -> OutboundMessage | None:
            return await self._process_message(msg, active_turn=active)

        task = asyncio.create_task(run_active_message())
        is_agent_turn = bool(
            msg.need_reply
            and msg.session_key.type != "system"
            and self.config.mode != BotMode.DEBUG
            and not msg.content.strip().startswith("/")
        )
        active = _ActiveTurn(
            msg.session_key,
            task,
            interruptible=is_agent_turn,
            accepting_steer=is_agent_turn,
        )
        self._active_turn = active
        try:
            response = await task
            if active.accepted_steers:
                raise RuntimeError("Active turn completed with unconsumed steer input")
            return response
        except asyncio.CancelledError:
            if active.interrupted:
                logger.info(f"Interrupted message from {msg.session_key}")
                return await self._complete_interrupted_message(msg)
            raise
        except Exception:
            if self._active_turn is active and (active.history_items or active.accepted_steers):
                await self._complete_interrupted_message(msg)
            raise
        finally:
            if self._active_turn is active:
                # Clear the active pointer before cleanup so later interrupt calls
                # cannot cancel this turn while its local teardown is finishing.
                self._active_turn = None

    async def _prepare_steer_message(self, msg: InboundMessage) -> _PreparedSteer:
        try:
            session_key = msg.session_key
            session = self.sessions.get_or_create(
                session_key,
                skip_heartbeat=session_key.type == "cli",
            )
            ov_tools_enable = self._get_ov_tools_enable(session_key)
            openviking_connection = (
                msg.openviking_connection if isinstance(msg.openviking_connection, dict) else None
            )
            actor_peer_id = msg.actor_peer_id or msg.sender_id
            memory_peer_ids = self._metadata_memory_peer_ids(msg.metadata)
            memory_owner_user_ids = self._metadata_memory_owner_user_ids(msg.metadata)
            channel_config = self._get_channel_config(session_key)
            profile_user_list = []
            if channel_config and ov_tools_enable:
                profile_user_list = getattr(channel_config, "profile_user_list", [])
                if not memory_peer_ids:
                    memory_peer_ids = self._channel_memory_peer_ids(channel_config)
                if not memory_owner_user_ids:
                    memory_owner_user_ids = self._channel_memory_owner_user_ids(channel_config)

            message_workspace = (
                self.sandbox_manager.get_workspace_path(session_key)
                if self.sandbox_manager
                else self.workspace
            )
            message_context = ContextBuilder(
                message_workspace,
                sandbox_manager=self.sandbox_manager,
                sender_id=msg.sender_id,
                actor_peer_id=actor_peer_id,
                sender_name=msg.sender_name,
                is_group_chat=msg.metadata.get("chat_type") == "group",
                eval=self._eval,
                openviking_connection=openviking_connection,
                enable_subagents=self._subagents_enabled(),
                config=self.config,
            )
            exp_exclude_uris = session.metadata.get("recalled_exp_uris", [])
            if not isinstance(exp_exclude_uris, list):
                exp_exclude_uris = []
            prepared_messages = await message_context.build_messages(
                history=[],
                current_message=msg.content,
                media=msg.media if msg.media else None,
                session_key=msg.session_key,
                ov_tools_enable=ov_tools_enable,
                profile_user_list=profile_user_list,
                memory_peer_ids=memory_peer_ids,
                memory_owner_user_ids=memory_owner_user_ids,
                exp_exclude_uris=exp_exclude_uris,
                include_system=False,
            )
            auto_memory_tool = None
            if ov_tools_enable and message_context.latest_relevant_memories:
                auto_memory_tool = await self._publish_auto_memory_context(
                    session_key=session_key,
                    query=msg.content,
                    result=message_context.latest_relevant_memories,
                    publish_events=False,
                )
            return _PreparedSteer(
                msg=msg,
                prompt_messages=prepared_messages,
                newly_recalled_exp_uris=list(message_context.latest_recalled_exp_uris),
                newly_recalled_exp_content=message_context.latest_recalled_exp_content,
                auto_memory_tool=auto_memory_tool,
            )
        except Exception:
            logger.exception("Failed to prepare steer context; using raw input")
        return _PreparedSteer(
            msg=msg,
            prompt_messages=[
                {
                    "role": "user",
                    "content": self.context._build_user_content(msg.content, msg.media),
                }
            ],
            newly_recalled_exp_uris=[],
            newly_recalled_exp_content="",
        )

    async def _take_accepted_steers(
        self,
        active: _ActiveTurn | None,
    ) -> list[_PreparedSteer]:
        if active is None:
            return []
        prepared: list[_PreparedSteer] = []
        prepared_count = 0
        # Keep ownership on the active turn until every observed batch is ready,
        # so interrupt can still persist all accepted raw inputs at any await.
        while prepared_count < len(active.accepted_steers):
            accepted = active.accepted_steers[prepared_count:]
            batch = await asyncio.gather(*(steer.task for steer in accepted))
            prepared.extend(batch)
            prepared_count += len(accepted)
        del active.accepted_steers[:prepared_count]
        return prepared

    @staticmethod
    def _append_active_turn_history(
        session: Session,
        items: list[_PreparedSteer | _AssistantBoundary],
    ) -> None:
        for item in items:
            if isinstance(item, _AssistantBoundary):
                session.add_message(
                    "assistant",
                    item.content,
                    reasoning_content=item.reasoning_content,
                )
            else:
                if item.newly_recalled_exp_content:
                    session.add_message(
                        "user",
                        "[Experience Reminder]\n"
                        f"## Relevant Agent Experience\n{item.newly_recalled_exp_content}",
                        exp_uris=item.newly_recalled_exp_uris,
                        experience_reminder=True,
                    )
                if item.newly_recalled_exp_uris:
                    recalled_uris = session.metadata.setdefault("recalled_exp_uris", [])
                    for uri in item.newly_recalled_exp_uris:
                        if uri not in recalled_uris:
                            recalled_uris.append(uri)
                session.add_message(
                    "user",
                    item.msg.content,
                    sender_id=item.msg.sender_id,
                )

    def stop(self) -> None:
        """Stop the agent loop."""
        self._running = False
        logger.info("Agent loop stopping")

    async def _complete_interrupted_message(self, msg: InboundMessage) -> OutboundMessage:
        session_key = msg.session_key
        skip_heartbeat = session_key.type == "cli"
        session = self.sessions.get_or_create(session_key, skip_heartbeat=skip_heartbeat)
        session.add_message("user", msg.content, sender_id=msg.sender_id)
        active = self._active_turn
        accepted_steers: list[_AcceptedSteer] = []
        if active is not None and active.session_key == session_key:
            accepted_steers = active.accepted_steers
            consumed = (
                item.msg for item in active.history_items if isinstance(item, _PreparedSteer)
            )
            pending = (steer.msg for steer in accepted_steers)
            for steer_msg in (*consumed, *pending):
                session.add_message(
                    "user",
                    steer_msg.content,
                    sender_id=steer_msg.sender_id,
                )
        await self.sessions.save(session)
        for steer in accepted_steers:
            steer.task.cancel()
        await asyncio.gather(
            *(steer.task for steer in accepted_steers),
            return_exceptions=True,
        )
        accepted_steers.clear()
        return OutboundMessage(
            session_key=msg.session_key,
            content="",
            event_type=OutboundEventType.INTERRUPT,
            metadata={**(msg.metadata or {}), "reason": "interrupted"},
        )

    async def _compact_tool_loop(
        self,
        messages: list[dict],
        session_key: SessionKey,
        *,
        budget_chars: int | None = None,
    ) -> list[dict]:
        """Compress older tool turns to fit the context window.

        Keeps system messages and the original task, folds older turns into a
        structured summary note (the previous note is reused verbatim, only the
        region since it is summarized), and retains the most recent complete turns.
        Summaries remain complete; ``budget_chars`` limits retained recent turns,
        with cuts only between turns. Fixed instructions, summaries and the newest
        turn can exceed that budget. Summarization failure is handled best effort.
        """
        budget = budget_chars or 240_000

        i = 0
        while i < len(messages) and messages[i].get("role") == "system":
            i += 1
        system_msgs = messages[:i]
        task_msg = messages[i] if i < len(messages) and messages[i].get("role") == "user" else None
        rest = messages[i + 1 :] if task_msg is not None else messages[i:]

        blocks = _compact_split_into_blocks(rest)
        if len(blocks) <= 3:
            return messages
        to_compact_blocks = blocks[:-3]
        window_blocks = blocks[-3:]

        flat = [m for block in to_compact_blocks for m in block]
        previous_summary = ""
        marker_idx: int | None = None
        for idx, message in enumerate(flat):
            content = str(message.get("content") or "")
            if content.strip().startswith("[Context compaction]"):
                marker_idx = idx
                previous_summary = _compact_strip_note_header(content)
        to_summarize = flat[marker_idx + 1 :] if marker_idx is not None else flat

        new_summary = ""
        if to_summarize:
            system_text = str(system_msgs[0].get("content") or "") if system_msgs else ""
            task_text = str(task_msg.get("content") or "") if task_msg else ""
            chunks = _compact_split_chunks(_compact_render_transcript(to_summarize))
            try:
                if len(chunks) == 1:
                    new_summary = await self._summarize_compact_chunk(
                        session_key, chunks[0], system_text=system_text, task_text=task_text
                    )
                else:
                    summaries = await asyncio.gather(
                        *(
                            self._summarize_compact_chunk(
                                session_key,
                                chunk,
                                system_text=system_text if idx == 0 else "",
                                task_text=task_text,
                            )
                            for idx, chunk in enumerate(chunks)
                        )
                    )
                    new_summary = await self._merge_compact_summaries(
                        session_key,
                        [s for s in summaries if s],
                        system_text=system_text,
                        task_text=task_text,
                    )
            except Exception as exc:
                logger.warning("Tool-loop compaction summarization failed: {}", exc)
                new_summary = ""

        note_msg = {"role": "user", "content": _compact_build_note(previous_summary, new_summary)}

        fixed_chars = _compact_msg_chars(system_msgs) + _compact_msg_chars([note_msg])
        if task_msg is not None:
            fixed_chars += _compact_msg_chars([task_msg])
        remaining = max(0, budget - fixed_chars)
        keep_blocks: list[list[dict]] = []
        kept_chars = 0
        for block in reversed(window_blocks):
            if block[0].get("role") == "tool":
                continue
            size = _compact_msg_chars(block)
            if keep_blocks and kept_chars + size > remaining:
                break
            keep_blocks.append(block)
            kept_chars += size
        keep_blocks.reverse()

        out: list[dict] = list(system_msgs)
        if task_msg is not None:
            out.append(task_msg)
        out.append(note_msg)
        for block in keep_blocks:
            out.extend(block)
        return out

    async def _summarize_compact_chunk(
        self,
        session_key: SessionKey,
        chunk_text: str,
        *,
        system_text: str = "",
        task_text: str = "",
    ) -> str:
        user_content = f"Original task:\n{task_text[:20_000]}\n\nTranscript segment:\n{chunk_text}"
        if system_text:
            user_content = (
                "Original system instructions (preserve any hard constraints verbatim):\n"
                f"{system_text[:40_000]}\n\n{user_content}"
            )
        return await self._chat_compact_summary(
            session_key,
            [
                {
                    "role": "system",
                    "content": (
                        "You are a context-compaction summarizer for a long-running tool-use "
                        "agent. Produce a dense, factual summary that preserves everything "
                        "needed to continue the task without re-reading the transcript, using "
                        "exactly these headings:\n## Current goal\n## Key facts & progress\n"
                        "## Saved files & coverage\n## Decisions\n## Constraints\n## Next steps / open questions\n"
                        "Record saved draft paths, covered sources/ranges and unwritten gaps; "
                        "distinguish successful writes from plans or failed writes. Continue from saved files. "
                        "Be precise about names, paths, tools, and numbers. Do not invent anything."
                    ),
                },
                {"role": "user", "content": user_content},
            ],
        )

    async def _merge_compact_summaries(
        self,
        session_key: SessionKey,
        segment_summaries: list[str],
        *,
        system_text: str = "",
        task_text: str = "",
    ) -> str:
        if not segment_summaries:
            return ""
        joined = "\n\n".join(
            f"## Segment {idx}\n{text}" for idx, text in enumerate(segment_summaries, start=1)
        )
        user_content = f"Original task:\n{task_text[:20_000]}\n\nSegment summaries:\n{joined}"
        if system_text:
            user_content = (
                "Original system instructions (preserve any hard constraints verbatim):\n"
                f"{system_text[:40_000]}\n\n{user_content}"
            )
        return await self._chat_compact_summary(
            session_key,
            [
                {
                    "role": "system",
                    "content": (
                        "You are the final assembly step of a context-compaction pipeline. "
                        "Merge the segment summaries below into ONE note with exactly these "
                        "headings:\n## Current goal\n## Key facts & progress\n## Saved files & coverage\n## Decisions\n"
                        "## Constraints\n## Next steps / open questions\n"
                        "Keep saved draft paths, coverage and unwritten gaps, including failed writes. "
                        "Preserve ALL distinct facts across segments; drop only duplicates. "
                        "Keep names, paths, tools, numbers. Carry over hard constraints from "
                        "the system instructions verbatim."
                    ),
                },
                {"role": "user", "content": user_content},
            ],
        )

    async def _chat_compact_summary(self, session_key: SessionKey, messages: list[dict]) -> str:
        for attempt in range(1, 4):
            try:
                response = await self.provider.chat(
                    messages=messages,
                    tools=[],
                    model=self.model,
                    temperature=0.0,
                    session_id=session_key.safe_name(),
                )
                summary = (response.content or "").strip()
                if summary:
                    return summary
                logger.warning("Tool-loop compaction summary attempt {}/3 was empty", attempt)
            except Exception as exc:
                logger.warning("Tool-loop compaction summary attempt {}/3 failed: {}", attempt, exc)
        return ""

    async def _preview_tool_result(
        self,
        result: Any,
        session_key: SessionKey,
        *,
        preserve_complete: bool = False,
    ) -> Any:
        """Save text exceeding 8,000 characters and return a bounded head/tail preview.

        Non-text results pass through. Saving failures are explicit in the preview;
        original tool outcomes still determine success and stop conditions.
        """
        if preserve_complete or not isinstance(result, str) or len(result) <= 8_000:
            return result
        path = f"{TOOL_RESULT_DIRECTORY}/{uuid.uuid4().hex}.txt"
        try:
            sandbox = await self.sandbox_manager.get_sandbox(session_key)
            await sandbox.write_file_bytes(path, result.encode("utf-8"))
            notice = (
                f"Full output ({len(result)} characters) saved at task-relative path {path}. "
                "Use read_file with offset/limit or a script to inspect selected sections; "
                "do not print the complete file. This file is not a deliverable."
            )
        except Exception as exc:
            notice = (
                f"Full output ({len(result)} characters) could NOT be saved: "
                f"{type(exc).__name__}. Only this preview is available; "
                "retrieve smaller sections from the original source if needed."
            )
        return f"{result[:4_000]}\n\n[Output truncated. {notice}]\n\n{result[-2_000:]}"

    async def _run_agent_loop(
        self,
        messages: list[dict],
        session_key: SessionKey,
        publish_events: bool = True,
        sender_id: str | None = None,
        actor_peer_id: str | None = None,
        ov_tools_enable: bool = True,
        memory_peer_ids: list[str] | None = None,
        memory_owner_user_ids: list[str] | None = None,
        disabled_tools: list[str] | None = None,
        openviking_connection: dict[str, Any] | None = None,
        stop_tool_names: list[str] | None = None,
        on_plain_text: Any | None = None,
        channel_metadata: dict[str, Any] | None = None,
        captured_turns: list[dict[str, Any]] | None = None,
        tool_registry: ToolRegistry | None = None,
        openviking_tool_names: list[str] | set[str] | None = None,
        allow_final_fallback: bool = True,
        inject_write_experience: bool = True,
        context_compact_budget: int | None = None,
        pre_compact_prompt: str | None = None,
        status_note_provider: Any | None = None,
        should_stop: Callable[[], bool] | None = None,
        skill_runtime: Any | None = None,
        active_turn: _ActiveTurn | None = None,
        agent_id: str = "main",
        max_iterations: int | None = None,
    ) -> tuple[str | None, str | None, list[dict], dict[str, int], int]:
        """
        Run the core agent loop: call LLM, execute tools, repeat until done.

        Args:
            messages: Initial message list
            session_key: Session key for tool execution context
            publish_events: Whether to publish ITERATION/REASONING/TOOL_CALL events to the bus
            sender_id: Sender identity forwarded to the tool execution context
            actor_peer_id: Authenticated OpenViking peer identity for tools
            ov_tools_enable: Whether to enable OpenViking tools for this session
            memory_peer_ids: List of peer IDs for memory retrieval
            memory_owner_user_ids: List of explicit OpenViking user IDs for
                trusted-mode owner-user memory lookup
            disabled_tools: Tool names to hide from the model for this request
            openviking_connection: Request-scoped OpenViking identity for tools
            stop_tool_names: Tool names that terminate the loop immediately after execution
            on_plain_text: Optional async callback invoked when the model returns a non-empty
                plain-text reply (no tool calls). It receives (messages, text, iteration) and
                must return a PlainTextRouteResult to either deliver the text and continue the
                loop (e.g. forward it to a user simulator) or treat it as the final reply. When
                None, plain text is treated as the final assistant reply (default chatbot
                semantics).
            channel_metadata: Channel-specific metadata for tools that publish outbound messages
            captured_turns: Optional mutable list populated with each intermediate assistant
                turn and the tool calls/results produced by that same model response. Reasoning
                content is intentionally excluded.
            tool_registry: Optional request-scoped registry used for tool definitions and
                execution. Defaults to the agent's shared tool registry.
            openviking_tool_names: Optional collection of tool names allowed to receive the
                request-scoped OpenViking connection. None preserves the legacy behavior of
                forwarding the connection to all tools; an empty collection forwards it to none.
            allow_final_fallback: Whether to make a final tool-free LLM call after the
                tool-use iteration limit is reached.
            inject_write_experience: Whether to retrieve and inject relevant agent experience
                before executing configured write tools.
            pre_compact_prompt: Optional one-turn save instruction at 85% of the character
                budget. Uses existing tools and iteration budget; a successful stop tool
                ends the loop before compaction. Already oversized contexts compact
                immediately; saving is best effort.
            status_note_provider: Optional async callback ``(iteration) -> str | None``.
                When set, its result is appended to the model-facing messages right before
                every model call. Compile emits a reminder at each configured iteration
                threshold; ordinary chat leaves it ``None``.
            should_stop: Optional synchronous callback checked before each iteration.
                Returning true ends the loop without an extra model call.
            agent_id: Diagnostic identity for model and tool logs; Compile children use
                their child task ID while sharing the parent's session and workspace.
            max_iterations: Positive budget for this invocation, or None to use the
                instance default. Concurrent children do not change each other's budgets.

        Returns:
            tuple of (final_content, final_reasoning_content, tools_used, token_usage, iteration)
        """
        iteration_limit = self.max_iterations if max_iterations is None else max_iterations
        if max_iterations is not None and max_iterations < 1:
            raise ValueError("max_iterations must be positive")
        iteration = 0
        active_tools = tool_registry or self.tools
        scoped_openviking_tools = (
            set(openviking_tool_names) if openviking_tool_names is not None else None
        )
        final_content = None
        final_reasoning_content = None
        tools_used: list[dict] = []
        token_usage = {
            "prompt_tokens": 0,
            "completion_tokens": 0,
            "total_tokens": 0,
            "cache_read_input_tokens": 0,
        }
        write_exp_injected = False
        stop_tools = set(stop_tool_names or [])
        compact_pending = False
        compact_threshold_chars = (context_compact_budget or 0) * 0.85
        compact_trigger_chars = compact_threshold_chars
        steer_memory_events: list[_PreparedSteer] = []

        def accumulate_token_usage(response: Any) -> None:
            if not response.usage:
                return
            cur_token = response.usage
            token_usage["prompt_tokens"] += cur_token.get("prompt_tokens", 0)
            token_usage["completion_tokens"] += cur_token.get("completion_tokens", 0)
            token_usage["total_tokens"] += cur_token.get("total_tokens", 0)
            token_usage["cache_read_input_tokens"] += cur_token.get("cache_read_input_tokens", 0)

        while iteration < iteration_limit:
            if should_stop is not None and should_stop():
                break
            iteration += 1

            if active_turn is not None and iteration >= iteration_limit:
                active_turn.accepting_steer = False
            accepted_steers = await self._take_accepted_steers(active_turn)
            for steer in accepted_steers:
                messages.extend(steer.prompt_messages)
            if accepted_steers:
                active_turn.history_items.extend(accepted_steers)
            steer_memory_events.extend(accepted_steers)

            if context_compact_budget is not None:
                current_chars = _compact_msg_chars(messages)
                if compact_pending or current_chars > context_compact_budget:
                    messages = await self._compact_tool_loop(
                        messages, session_key, budget_chars=context_compact_budget
                    )
                    compact_pending = False
                    # Fixed task content can exceed the save threshold; wait for new content.
                    compact_trigger_chars = max(
                        compact_threshold_chars, _compact_msg_chars(messages)
                    )
                elif (
                    pre_compact_prompt
                    and 1 < iteration < iteration_limit
                    and current_chars > compact_trigger_chars
                ):
                    messages.append({"role": "user", "content": pre_compact_prompt})
                    compact_pending = True

            if publish_events:
                await self.bus.publish_outbound(
                    OutboundMessage(
                        session_key=session_key,
                        content=f"Iteration {iteration}/{iteration_limit}",
                        event_type=OutboundEventType.ITERATION,
                    )
                )
                for steer in steer_memory_events:
                    if steer.auto_memory_tool:
                        await self._publish_auto_memory_context(
                            session_key=session_key,
                            query=steer.msg.content,
                            result=steer.auto_memory_tool["result"],
                        )
            steer_memory_events.clear()

            if status_note_provider is not None:
                note = await status_note_provider(iteration)
                if note:
                    messages.append({"role": "user", "content": note})

            tool_definitions = active_tools.get_definitions(
                ov_tools_enable=ov_tools_enable,
                disabled_tools=disabled_tools,
                skill_runtime=skill_runtime,
            )
            visible_tool_names = {
                str(definition.get("function", {}).get("name") or "")
                for definition in tool_definitions
                if isinstance(definition, dict)
            }
            response, _streamed_content, streamed_reasoning = await self._chat_with_stream_events(
                messages=messages,
                tools=tool_definitions,
                session_key=session_key,
                publish_events=publish_events,
                agent_id=agent_id,
                iteration=iteration,
            )
            accumulate_token_usage(response)

            if publish_events and response.reasoning_content and not streamed_reasoning:
                await self.bus.publish_outbound(
                    OutboundMessage(
                        session_key=session_key,
                        content=response.reasoning_content,
                        event_type=OutboundEventType.REASONING,
                    )
                )

            if response.has_tool_calls:
                # Inject experience memory before write-related tool calls (once per session)
                if inject_write_experience and not write_exp_injected:
                    _ov_cfg = self.config.ov_server
                    _write_tools = set(_ov_cfg.exp_write_tools)
                    if any(tc.name in _write_tools for tc in response.tool_calls):
                        write_exp_injected = True
                        try:
                            # Build query from last 3 user messages
                            _user_msgs = [
                                m["content"]
                                for m in messages
                                if m.get("role") == "user" and isinstance(m.get("content"), str)
                            ]
                            _query = "\n".join(_user_msgs[-3:])
                            workspace_id = (
                                self.sandbox_manager.to_workspace_id(session_key)
                                if self.sandbox_manager
                                else "shared"
                            )
                            _exp = await self.context.memory.get_viking_experience_context(
                                query=_query,
                                workspace_id=workspace_id,
                                openviking_connection=openviking_connection,
                            )
                            logger.info(
                                f"[WRITE_EXP]: write tool detected, exp_found={bool(_exp)}, query={_query[:50]}"
                            )
                            if _exp:
                                messages.append(
                                    {
                                        "role": "user",
                                        "content": f"## Relevant Agent Experience\n{_exp}",
                                    }
                                )
                                continue
                        except Exception as _e:
                            logger.warning(f"[WRITE_EXP]: failed to load experience: {_e}")

                final_reasoning_content = response.reasoning_content
                args_list = [tc.arguments for tc in response.tool_calls]
                tool_call_dicts = [
                    {
                        "id": tc.id,
                        "type": "function",
                        "function": {
                            "name": tc.name,
                            # Unicode escapes inflate the history's character budget.
                            "arguments": json.dumps(args, ensure_ascii=False),
                        },
                    }
                    for tc, args in zip(response.tool_calls, args_list, strict=False)
                ]
                messages = self.context.add_assistant_message(
                    messages,
                    response.content,
                    tool_call_dicts,
                    reasoning_content=response.reasoning_content,
                )

                # Stage 2: activate Skills first, then execute remaining tools.
                async def execute_single_tool(
                    idx: int, tool_call, allowed_names=visible_tool_names
                ):
                    """Execute a single tool and track execution time."""
                    tool_execute_start_time = time.perf_counter()
                    if tool_call.name not in allowed_names:
                        result = f"Error: Tool '{tool_call.name}' is not available in this turn"
                        return (
                            idx,
                            tool_call,
                            ToolExecutionResult(
                                result=result,
                                effective_params=dict(tool_call.arguments),
                            ),
                            0.0,
                        )
                    tool_connection = (
                        openviking_connection
                        if scoped_openviking_tools is None
                        or tool_call.name in scoped_openviking_tools
                        else None
                    )
                    execute_kwargs = {
                        "session_key": session_key,
                        "sandbox_manager": self.sandbox_manager,
                        "sender_id": sender_id,
                        "actor_peer_id": actor_peer_id or sender_id,
                        "memory_peer_ids": memory_peer_ids,
                        "memory_owner_user_ids": memory_owner_user_ids,
                        "openviking_connection": tool_connection,
                        "channel_metadata": channel_metadata,
                    }
                    if hasattr(active_tools, "execute_detailed"):
                        outcome = await active_tools.execute_detailed(
                            tool_call.name,
                            tool_call.arguments,
                            **execute_kwargs,
                            skill_runtime=skill_runtime,
                        )
                    else:
                        # Keep compatibility with embedders/tests that provide a
                        # minimal registry implementing only the legacy API.
                        result = await active_tools.execute(
                            tool_call.name, tool_call.arguments, **execute_kwargs
                        )
                        outcome = ToolExecutionResult(
                            result=result,
                            effective_params=dict(tool_call.arguments),
                        )
                    tool_execute_duration = (time.perf_counter() - tool_execute_start_time) * 1000
                    return idx, tool_call, outcome, tool_execute_duration

                for tool_call in response.tool_calls:
                    args_str = json.dumps(tool_call.arguments, ensure_ascii=False)
                    logger.info(
                        "[TOOL_CALL]: {}({}) session={} agent={} iteration={} call_id={}",
                        tool_call.name,
                        args_str[:200],
                        session_key.safe_name(),
                        agent_id,
                        iteration,
                        tool_call.id,
                    )
                    if publish_events:
                        await self.bus.publish_outbound(
                            OutboundMessage(
                                session_key=session_key,
                                content=f"{tool_call.name}({args_str})",
                                event_type=OutboundEventType.TOOL_CALL,
                            )
                        )

                indexed_calls = list(enumerate(response.tool_calls))
                activation_calls = []
                regular_calls = []
                for indexed_call in indexed_calls:
                    _index, candidate_call = indexed_call
                    if skill_runtime is not None and skill_runtime.is_activation_call(
                        candidate_call.name, candidate_call.arguments
                    ):
                        activation_calls.append(indexed_call)
                    else:
                        regular_calls.append(indexed_call)

                # Complete Skill activation first. Calls emitted from the pre-activation
                # schema are never executed under the newly activated policy; the model
                # retries them on the next iteration with refreshed tool definitions.
                activation_results = await asyncio.gather(
                    *(execute_single_tool(index, call) for index, call in activation_calls)
                )
                activation_failed = any(
                    not _is_tool_result_success(item[2].result)
                    or not skill_runtime.activation_succeeded(item[1].arguments)
                    for item in activation_results
                )
                if activation_failed:
                    regular_results = [
                        (
                            index,
                            call,
                            ToolExecutionResult(
                                result=(
                                    "Error: SKILL_ACTIVATION_FAILED: execution was blocked "
                                    "because a Skill definition in this tool batch could not "
                                    "be activated"
                                ),
                                effective_params=dict(call.arguments),
                            ),
                            0.0,
                        )
                        for index, call in regular_calls
                    ]
                elif activation_calls:
                    regular_results = [
                        (
                            index,
                            call,
                            ToolExecutionResult(
                                result=(
                                    "Error: SKILL_CONTEXT_UPDATED: one or more remote Skills "
                                    "were activated; retry this tool call using the refreshed "
                                    "tool definitions"
                                ),
                                effective_params=dict(call.arguments),
                            ),
                            0.0,
                        )
                        for index, call in regular_calls
                    ]
                else:
                    regular_results = await asyncio.gather(
                        *(execute_single_tool(index, call) for index, call in regular_calls)
                    )
                results = sorted([*activation_results, *regular_results], key=lambda item: item[0])

                # Stage 3: Process results sequentially in original order
                turn_tools: list[dict[str, Any]] = []
                history_end = len(messages)
                request_media_bytes = _inline_media_bytes(messages)
                for _idx, tool_call, outcome, tool_execute_duration in results:
                    result = outcome.result
                    result_text = str(result)
                    model_result = await self._preview_tool_result(
                        result,
                        session_key,
                        preserve_complete=getattr(outcome, "preserve_complete_result", False),
                    )
                    recorded_result = (
                        result_text if isinstance(result, MultimodalToolResult) else model_result
                    )
                    args_str = json.dumps(tool_call.arguments, ensure_ascii=False)
                    logger.info(
                        "[TOOL_END] {}",
                        json.dumps(
                            {
                                "session_id": session_key.safe_name(),
                                "agent_id": agent_id,
                                "iteration": iteration,
                                "tool_call_id": tool_call.id,
                                "tool_name": tool_call.name,
                                "duration_ms": round(tool_execute_duration, 1),
                                "success": _is_tool_result_success(result),
                            },
                            ensure_ascii=False,
                        ),
                    )
                    logger.info(f"[RESULT]: {result_text[:200]}")

                    if publish_events:
                        await self.bus.publish_outbound(
                            OutboundMessage(
                                session_key=session_key,
                                content=str(model_result),
                                event_type=OutboundEventType.TOOL_RESULT,
                            )
                        )
                    if isinstance(result, MultimodalToolResult):
                        result_media_bytes = _inline_media_bytes([{"content": result.content}])
                        if not self.provider.supports_tool_result_media(self.model):
                            model_result = (
                                f"{result_text}\n\nMedia content was omitted because the configured "
                                "model provider does not support media in tool results."
                            )
                        else:
                            overflow = (
                                request_media_bytes
                                + result_media_bytes
                                - MAX_INLINE_TOOL_RESULT_MEDIA_BYTES
                            )
                            if overflow > 0:
                                reclaimed = _demote_historical_tool_media(
                                    messages,
                                    history_end=history_end,
                                    bytes_needed=overflow,
                                )
                                request_media_bytes -= reclaimed
                            if (
                                request_media_bytes + result_media_bytes
                                > MAX_INLINE_TOOL_RESULT_MEDIA_BYTES
                            ):
                                model_result = (
                                    f"{result_text}\n\nMedia content was omitted because adding it would "
                                    "make this model request exceed the inline media "
                                    f"limit of {MAX_INLINE_TOOL_RESULT_MEDIA_BYTES} bytes."
                                )
                            else:
                                request_media_bytes += result_media_bytes
                    messages = self.context.add_tool_result(
                        messages, tool_call.id, tool_call.name, model_result
                    )

                    tool_used_dict = {
                        "tool_call_id": tool_call.id,
                        "tool_name": tool_call.name,
                        "args": args_str,
                        "resolved_args": outcome.effective_params,
                        "result": recorded_result,
                        "duration": tool_execute_duration,
                        "execute_success": _is_tool_result_success(result),
                        "input_token": tool_call.tokens,
                        "output_token": cal_str_tokens(result_text, text_type="mixed"),
                    }
                    if outcome.skill_uris:
                        tool_used_dict["skill_uri"] = outcome.skill_uris[0]
                        tool_used_dict["skill_uris"] = list(outcome.skill_uris)
                    tools_used.append(tool_used_dict)
                    turn_tools.append(tool_used_dict)

                if captured_turns is not None:
                    captured_turns.append(
                        {
                            "role": "assistant",
                            "content": response.content or "",
                            "tool_calls": turn_tools,
                            "timestamp": datetime.now().isoformat(),
                        }
                    )

                if any(
                    tool_call.name in stop_tools and _is_tool_result_success(_outcome.result)
                    for _idx, tool_call, _outcome, _duration in results
                ):
                    final_content = ""
                    break

            else:
                text = (response.content or "").strip()
                routed = False
                if text and on_plain_text is not None:
                    try:
                        route = await on_plain_text(
                            _PlainTextContext(
                                messages=messages,
                                session_key=session_key,
                                text=text,
                                reasoning_content=response.reasoning_content,
                                iteration=iteration,
                                tools=active_tools,
                                sandbox_manager=self.sandbox_manager,
                                sender_id=sender_id,
                                memory_peer_ids=memory_peer_ids,
                                memory_owner_user_ids=memory_owner_user_ids,
                                openviking_connection=openviking_connection,
                            )
                        )
                    except Exception as exc:
                        logger.warning(
                            "[PLAIN_TEXT_HOOK]: hook raised; treating as final answer: %s", exc
                        )
                        route = None
                    if isinstance(route, _PlainTextDelivered):
                        messages = route.messages
                        tools_used.extend(route.tools_used)
                        if captured_turns is not None:
                            captured_turns.append(
                                {
                                    "role": "assistant",
                                    "content": text,
                                    "tool_calls": list(route.tools_used),
                                    "timestamp": datetime.now().isoformat(),
                                }
                            )
                        if route.user_terminates:
                            final_content = ""
                            break
                        messages.append(
                            {
                                "role": "user",
                                "content": "Reflect on the results and decide next steps.",
                            }
                        )
                        routed = True
                        continue
                    if isinstance(route, _PlainTextFinal):
                        final_content = route.content if route.content is not None else text
                        final_reasoning_content = response.reasoning_content
                        break
                    # Unknown / None result: fall through to default final-answer handling.
                if not text and on_plain_text is not None:
                    # Structured tasks treat an empty model response as a
                    # transient hiccup, not a final answer: nudge and continue.
                    messages.append(
                        {
                            "role": "user",
                            "content": (
                                "Your response was empty. Continue the task and call the "
                                "designated final submission tool with the complete bundle."
                            ),
                        }
                    )
                    continue
                final_steers = await self._take_accepted_steers(active_turn)
                if final_steers:
                    messages = self.context.add_assistant_message(
                        messages,
                        response.content,
                        [],
                        reasoning_content=response.reasoning_content,
                    )
                    active_turn.history_items.append(
                        _AssistantBoundary(
                            content=response.content or "",
                            reasoning_content=response.reasoning_content,
                        )
                    )
                    active_turn.history_items.extend(final_steers)
                    for steer in final_steers:
                        messages.extend(steer.prompt_messages)
                    steer_memory_events.extend(final_steers)
                    continue
                if active_turn is not None:
                    # No await separates this close from the empty queue check,
                    # so a successful steer cannot slip past the final checkpoint.
                    active_turn.accepting_steer = False
                final_content = response.content
                final_reasoning_content = response.reasoning_content
                if routed:
                    continue
                break

        if final_content == "" and tools_used and tools_used[-1].get("tool_name") in stop_tools:
            pass
        elif final_content is None or (
            isinstance(final_content, str) and not final_content.strip()
        ):
            if iteration >= iteration_limit and allow_final_fallback:
                messages.append(
                    {
                        "role": "user",
                        "content": (
                            "Tool-use iteration limit reached. Do not call any more tools. "
                            "Answer the user's original request directly using only the "
                            "conversation, tool calls, and tool results already available above. "
                            "If the gathered information is incomplete, explain the best-known "
                            "answer and clearly note what remains uncertain."
                        ),
                    }
                )
                (
                    response,
                    _streamed_content,
                    streamed_reasoning,
                ) = await self._chat_with_stream_events(
                    messages=messages,
                    tools=[],
                    session_key=session_key,
                    publish_events=publish_events,
                    agent_id=agent_id,
                    iteration=iteration + 1,
                )
                accumulate_token_usage(response)
                final_content = response.content
                final_reasoning_content = response.reasoning_content

                if publish_events and response.reasoning_content and not streamed_reasoning:
                    await self.bus.publish_outbound(
                        OutboundMessage(
                            session_key=session_key,
                            content=response.reasoning_content,
                            event_type=OutboundEventType.REASONING,
                        )
                    )

        if final_content is None or (isinstance(final_content, str) and not final_content.strip()):
            if iteration >= iteration_limit:
                final_content = (
                    "I reached the tool-use limit before completing every step, and the "
                    "available tool results are not enough for a reliable final answer."
                )
            else:
                final_content = "I've completed processing but have no response to give."

        return final_content, final_reasoning_content, tools_used, token_usage, iteration

    async def run_structured_task(
        self,
        *,
        system_prompt: str,
        user_prompt: str,
        session_key: SessionKey,
        tool_registry: ToolRegistry,
        openviking_tool_names: list[str] | set[str],
        stop_tool_names: list[str],
        openviking_connection: dict[str, Any] | None,
        context_compact_budget: int | None = None,
        pre_compact_prompt: str | None = None,
        budget_reminder_thresholds: tuple[int, int, int] | None = None,
    ) -> tuple[Any, list[dict], dict[str, int], int]:
        """Run a tool-terminated structured task through the existing agent loop.

        ``budget_reminder_thresholds`` optionally adds an iteration countdown before
        model calls near the execution limit. ``pre_compact_prompt`` enables a bounded
        save turn before context compaction, using the task's existing file tools.
        """

        max_iterations = getattr(self, "max_iterations", 0)

        async def status_note_provider(iteration: int) -> str | None:
            remaining = max(0, max_iterations - iteration)
            if budget_reminder_thresholds and remaining in budget_reminder_thresholds:
                return render_budget_reminder(remaining, budget_reminder_thresholds)
            return None

        async def require_submission(context: _PlainTextContext) -> _PlainTextDelivered:
            messages = self.context.add_assistant_message(context.messages, context.text, [])
            messages.append(
                {
                    "role": "user",
                    "content": (
                        "Your response was not submitted. Continue the task and call "
                        "submit_wiki_bundle once the complete final output is ready."
                    ),
                }
            )
            return _PlainTextDelivered(messages=messages, tools_used=[])

        messages = [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_prompt},
        ]
        _content, _reasoning, tools_used, token_usage, iteration = await self._run_agent_loop(
            messages=messages,
            session_key=session_key,
            publish_events=False,
            ov_tools_enable=True,
            openviking_connection=openviking_connection,
            stop_tool_names=stop_tool_names,
            on_plain_text=require_submission,
            tool_registry=tool_registry,
            openviking_tool_names=openviking_tool_names,
            allow_final_fallback=False,
            inject_write_experience=False,
            context_compact_budget=context_compact_budget,
            pre_compact_prompt=pre_compact_prompt,
            status_note_provider=status_note_provider,
        )
        submit_tool = tool_registry.get("submit_wiki_bundle")
        bundle = getattr(submit_tool, "bundle", None)
        if bundle is None:
            if iteration >= self.max_iterations:
                raise AgentIterationLimitExceeded(self.max_iterations, usage=token_usage)
            raise ValueError("AGENT_OUTPUT_INVALID: Agent did not submit a valid Wiki bundle")
        return bundle, tools_used, token_usage, iteration

    @trace(
        name="process_message",
        extract_session_id=lambda msg: msg.session_key.safe_name(),
        extract_user_id=lambda msg: msg.sender_id,
    )
    async def _process_message(
        self,
        msg: InboundMessage,
        active_turn: _ActiveTurn | None = None,
    ) -> OutboundMessage | None:
        """
        Process a single inbound message.

        Args:
            msg: The inbound message to process.
            session_key: Override session key (used by process_direct).

        Returns:
            The response message, or None if no response needed.
        """
        # Handle system messages (subagent announces)
        # The chat_id contains the original "channel:chat_id" to route back to
        start_time = time.time()
        long_running_notified = False

        # 监控处理时长,每50秒发送处理中提示事件
        async def check_long_running():
            nonlocal long_running_notified
            tick_count = 0
            # 最多发送7次提示
            max_ticks = 7

            while not long_running_notified and tick_count < max_ticks:
                await asyncio.sleep(60)
                if long_running_notified:
                    break
                if msg.metadata:
                    message_id = msg.metadata.get("message_id")
                    if message_id:
                        try:
                            # 发送处理中tick事件,对应channel会自行处理展示逻辑
                            await self.bus.publish_outbound(
                                OutboundMessage(
                                    session_key=msg.session_key,
                                    content="",
                                    metadata={
                                        "action": "processing_tick",
                                        "tick_count": tick_count,
                                        "message_id": message_id,
                                    },
                                )
                            )
                            tick_count += 1
                        except Exception as e:
                            logger.debug(f"Failed to send processing tick: {e}")

        monitor_task = asyncio.create_task(check_long_running())
        skill_runtime: SkillRuntimeContext | None = None

        try:
            if msg.session_key.type == "system":
                return await self._process_system_message(msg)

            preview = msg.content[:80] + "..." if len(msg.content) > 80 else msg.content
            logger.info(f"Processing message from {msg.session_key}:{msg.sender_id}: {preview}")

            session_key = msg.session_key
            # For CLI/direct sessions, skip heartbeat by default
            skip_heartbeat = session_key.type == "cli"
            session = self.sessions.get_or_create(session_key, skip_heartbeat=skip_heartbeat)

            ov_tools_enable = self._get_ov_tools_enable(session_key)
            disabled_tools = msg.metadata.get("disabled_tools", []) if msg.metadata else []
            if not isinstance(disabled_tools, list):
                disabled_tools = []
            if msg.metadata.get("studio_managed"):
                from vikingbot.studio.policy import disabled_group_tools

                disabled_tools = list(
                    set(disabled_tools) | set(disabled_group_tools(self.tools.tool_names))
                )
            openviking_connection = getattr(msg, "openviking_connection", None)
            if not isinstance(openviking_connection, dict):
                openviking_connection = None
            msg.openviking_connection = openviking_connection
            actor_peer_id = getattr(msg, "actor_peer_id", None) or msg.sender_id
            msg.actor_peer_id = actor_peer_id
            profile_user_list = []
            memory_peer_ids = self._metadata_memory_peer_ids(msg.metadata)
            memory_owner_user_ids = self._metadata_memory_owner_user_ids(msg.metadata)
            channel_config = self._get_channel_config(session_key)

            if channel_config and ov_tools_enable:
                profile_user_list = getattr(channel_config, "profile_user_list", [])
                if not memory_peer_ids:
                    memory_peer_ids = self._channel_memory_peer_ids(channel_config)
                if not memory_owner_user_ids:
                    memory_owner_user_ids = self._channel_memory_owner_user_ids(channel_config)

            # Handle slash commands
            is_group_chat = msg.metadata.get("chat_type") == "group" if msg.metadata else False
            if is_group_chat:
                cmd = msg.content
                cmd = re.sub(r"^\[[^\]]+\]:\s*", "", cmd)
                cmd = cmd.replace(f"@{msg.sender_id}", "").strip().lower()
            else:
                cmd = msg.content.strip().lower()
            if cmd == "/new":
                # Clone session for async consolidation, then immediately clear original
                if not self._check_cmd_auth(msg):
                    return OutboundMessage(
                        session_key=msg.session_key,
                        content="🐈 Sorry, you are not authorized to use this command.",
                        metadata=msg.metadata,
                    )
                session.clear()
                if self._ov_session_context_enabled():
                    reset_openviking_state(session, rotate_session_id=True)
                await self.sessions.save(session)
                return OutboundMessage(
                    session_key=msg.session_key,
                    content="🐈 New session started. Session history droped.",
                    metadata=msg.metadata,
                )
            elif cmd == "/compact":
                # Clone session for async consolidation, then immediately clear original
                if not self._check_cmd_auth(msg):
                    return OutboundMessage(
                        session_key=msg.session_key,
                        content="🐈 Sorry, you are not authorized to use this command.",
                        metadata=msg.metadata,
                    )
                if self._ov_session_context_enabled():
                    committed = await self._commit_openviking_session(
                        session,
                        keep_recent_turn_count=0,
                        clear_local_session=True,
                        openviking_connection=openviking_connection,
                    )
                    if not committed:
                        return OutboundMessage(
                            session_key=msg.session_key,
                            content="🐈 Memory consolidation failed. Session history was kept.",
                            metadata=msg.metadata,
                        )
                else:
                    session_clone = session.clone()
                    session.clear()
                    await self.sessions.save(session)
                    # Run consolidation in background
                    await self._safe_consolidate_memory(
                        session_clone,
                        archive_all=True,
                        openviking_connection=openviking_connection,
                    )
                return OutboundMessage(
                    session_key=msg.session_key,
                    content="🐈 New session started. Memory consolidated.",
                    metadata=msg.metadata,
                )
            if cmd == "/remember":
                if not self._check_cmd_auth(msg):
                    return OutboundMessage(
                        session_key=msg.session_key,
                        content="🐈 Sorry, you are not authorized to use this command.",
                        metadata=msg.metadata,
                    )
                if self._ov_session_context_enabled():
                    remembered = await self._commit_openviking_session(
                        session,
                        keep_recent_turn_count=self.config.agents.commit_keep_recent_turn_count,
                        openviking_connection=openviking_connection,
                    )
                    if not remembered:
                        return OutboundMessage(
                            session_key=msg.session_key,
                            content="Failed to submit this conversation to memory storage.",
                            metadata=msg.metadata,
                        )
                elif ov_tools_enable:
                    session_clone = session.clone()
                    await self._consolidate_viking_memory(
                        session_clone,
                        openviking_connection=openviking_connection,
                    )
                return OutboundMessage(
                    session_key=msg.session_key,
                    content="This conversation has been submitted to memory storage.",
                    metadata=msg.metadata,
                )
            if cmd == "/help":
                return OutboundMessage(
                    session_key=msg.session_key,
                    content="🐈 vikingbot commands:\n/new — Start a new conversation\n/remember — Submit current session to memories and start new session\n/help — Show available commands",
                    metadata=msg.metadata,
                )

            # Debug mode handling
            if self.config.mode == BotMode.DEBUG:
                # In debug mode, only record message to session, no processing or reply
                await self._evaluate_previous_response_outcome(session, msg)
                session.add_message("user", msg.content, sender_id=msg.sender_id)
                await self.sessions.save(session)
                return None

            if not msg.need_reply:
                await self._evaluate_previous_response_outcome(session, msg)
                session.add_message("user", msg.content, sender_id=msg.sender_id)
                await self.sessions.save(session)
                return OutboundMessage(
                    session_key=msg.session_key,
                    content="",
                    metadata=msg.metadata,
                    event_type=OutboundEventType.NO_REPLY,
                )

            await self._evaluate_previous_response_outcome(session, msg)

            # Consolidate memory before processing if session is too large
            if self._ov_session_context_enabled() and not self._eval:
                await self._maybe_commit_openviking_before_turn(session, msg)
            elif len(session.messages) > self.memory_window and not self._eval:
                # Clone session for async consolidation, then immediately trim original
                session_clone = session.clone()
                keep_count = min(10, max(2, self.memory_window // 2))
                session.messages = session.messages[-keep_count:] if keep_count else []
                await self.sessions.save(session)
                # Run consolidation in background
                await self._safe_consolidate_memory(
                    session_clone,
                    archive_all=False,
                    openviking_connection=openviking_connection,
                )

            if self.sandbox_manager:
                message_workspace = self.sandbox_manager.get_workspace_path(session_key)
            else:
                message_workspace = self.workspace

            skill_runtime = self._create_skill_runtime(
                session_key=session_key,
                workspace=message_workspace,
                ov_tools_enable=ov_tools_enable,
                disabled_tools=disabled_tools,
                openviking_connection=openviking_connection,
                actor_peer_id=actor_peer_id,
            )
            remote_skills_summary = ""
            if skill_runtime is not None:
                await skill_runtime.discover(msg.content)
                remote_skills_summary = skill_runtime.build_discovery_summary()

            from vikingbot.agent.context import ContextBuilder

            message_context = ContextBuilder(
                message_workspace,
                sandbox_manager=self.sandbox_manager,
                sender_id=msg.sender_id,
                actor_peer_id=actor_peer_id,
                sender_name=msg.sender_name,
                is_group_chat=is_group_chat,
                eval=self._eval,
                openviking_connection=openviking_connection,
                remote_skills_summary=remote_skills_summary,
                enable_subagents=self._subagents_enabled(),
                config=self.config,
            )

            # Build initial messages (use OpenViking session context when enabled)
            provider_name = self.config.get_provider_name(self.model) if self.config else None
            history = await self._build_prompt_history(
                session,
                provider_name=provider_name,
                openviking_connection=openviking_connection,
                actor_peer_id=actor_peer_id,
            )

            # Experience recall deduplication: URIs already recalled in this session
            # are stored in session.metadata and survive restarts (persisted to JSONL).
            exp_exclude_uris = session.metadata.get("recalled_exp_uris", [])
            if not isinstance(exp_exclude_uris, list):
                exp_exclude_uris = []

            messages = await message_context.build_messages(
                history=history,
                current_message=msg.content,
                media=msg.media if msg.media else None,
                session_key=msg.session_key,
                ov_tools_enable=ov_tools_enable,
                profile_user_list=profile_user_list,
                memory_peer_ids=memory_peer_ids,
                memory_owner_user_ids=memory_owner_user_ids,
                exp_exclude_uris=exp_exclude_uris,
            )
            relevant_memories = message_context.latest_relevant_memories
            auto_memory_tool = None
            if ov_tools_enable and relevant_memories:
                auto_memory_tool = await self._publish_auto_memory_context(
                    session_key=session_key,
                    query=msg.content,
                    result=relevant_memories,
                )

            # Track newly recalled experience URIs for deduplication
            newly_recalled_exp_uris = getattr(message_context, "latest_recalled_exp_uris", [])
            newly_recalled_exp_content = getattr(message_context, "latest_recalled_exp_content", "")

            # Run agent loop within a stable response identity for tracing/tool spans.
            response_id = uuid.uuid4().hex
            agent_turns: list[dict[str, Any]] = []
            with set_response_id(response_id):
                (
                    final_content,
                    final_reasoning_content,
                    tools_used,
                    token_usage,
                    iteration,
                ) = await self._run_agent_loop(
                    messages=messages,
                    session_key=session_key,
                    publish_events=True,
                    sender_id=msg.sender_id,
                    actor_peer_id=actor_peer_id,
                    ov_tools_enable=ov_tools_enable,
                    memory_peer_ids=memory_peer_ids,
                    memory_owner_user_ids=memory_owner_user_ids,
                    disabled_tools=disabled_tools,
                    openviking_connection=openviking_connection,
                    channel_metadata=msg.metadata,
                    captured_turns=agent_turns,
                    skill_runtime=skill_runtime,
                    active_turn=active_turn,
                )

            if auto_memory_tool:
                tools_used = [auto_memory_tool, *(tools_used or [])]
            active_turn_history = list(active_turn.history_items) if active_turn is not None else []
            for item in active_turn_history:
                if isinstance(item, _PreparedSteer) and item.auto_memory_tool:
                    tools_used.append(item.auto_memory_tool)

            # Log response preview
            preview = final_content[:300] + "..." if len(final_content) > 300 else final_content
            logger.info(f"Response to {msg.session_key}: {preview}")

            response_completed = self._build_response_completed_payload(
                msg=msg,
                response_id=response_id,
                final_content=final_content,
                final_reasoning_content=final_reasoning_content,
                token_usage=token_usage,
                time_cost_seconds=time.time() - start_time,
                iteration=iteration,
                tools_used=tools_used,
            )

            if active_turn is not None:
                # Detach before persistence so a later interrupt cannot cancel final session writes.
                self._active_turn = None

            is_heartbeat = bool(msg.metadata.get(HEARTBEAT_METADATA_KEY))
            if not (is_heartbeat and is_heartbeat_noop_response(final_content)):
                if newly_recalled_exp_uris:
                    recalled_uris = session.metadata.setdefault("recalled_exp_uris", [])
                    for uri in newly_recalled_exp_uris:
                        if uri not in recalled_uris:
                            recalled_uris.append(uri)
                # Write experience reminder into session history so it persists
                # across turns and survives bot restarts (in JSONL).
                if newly_recalled_exp_content:
                    session.add_message(
                        "user",
                        f"[Experience Reminder]\n## Relevant Agent Experience\n{newly_recalled_exp_content}",
                        exp_uris=newly_recalled_exp_uris,
                        experience_reminder=True,
                    )
                session.add_message("user", msg.content, sender_id=msg.sender_id)
                self._append_active_turn_history(session, active_turn_history)
                session.add_message(
                    "assistant",
                    final_content,
                    response_id=response_id,
                    tools_used=tools_used if tools_used else None,
                    token_usage=token_usage,
                    sender_id=msg.sender_id,
                    reasoning_content=final_reasoning_content,
                    agent_turns=agent_turns if agent_turns else None,
                )
                session.metadata.setdefault("response_facts", {})[response_id] = response_completed
                await self.sessions.save(session)
                if self._ov_session_context_enabled() and not self._eval:
                    await self._submit_openviking_session_and_clear_if_committed(
                        session,
                        commit_message_threshold=self.memory_window,
                        openviking_connection=openviking_connection,
                    )
            LangfuseClient.get_instance().update_generation_metadata(
                response_id, response_completed
            )
            response_metadata = dict(msg.metadata or {})
            if relevant_memories is not None:
                response_metadata["relevant_memories"] = relevant_memories
            await self.bus.publish_outbound(
                OutboundMessage(
                    session_key=msg.session_key,
                    content="",
                    event_type=OutboundEventType.RESPONSE_COMPLETED,
                    response_id=response_id,
                    metadata={"response_completed": response_completed},
                )
            )
            return OutboundMessage(
                session_key=msg.session_key,
                content=final_content,
                metadata=response_metadata,
                response_id=response_id,
                token_usage=token_usage,
                time_cost=response_completed["time_cost_ms"] / 1000,
                iteration=response_completed["iteration_count"],
                tools_used_names=response_completed["tools_used_names"],
            )
        finally:
            if skill_runtime is not None:
                try:
                    await skill_runtime.close()
                except Exception as exc:
                    logger.warning("Failed to close remote Skill runtime: {}", exc)
            long_running_notified = True
            monitor_task.cancel()
            try:
                await monitor_task
            except asyncio.CancelledError:
                pass

    @staticmethod
    def _build_response_completed_payload(
        msg: InboundMessage,
        response_id: str,
        final_content: str,
        final_reasoning_content: str | None,
        token_usage: dict[str, Any],
        time_cost_seconds: float,
        iteration: int,
        tools_used: list[dict[str, Any]] | None,
    ) -> dict[str, Any]:
        """Build a stable response fact shared by analytics sinks."""
        prompt_tokens = int(token_usage.get("prompt_tokens", 0) or 0)
        completion_tokens = int(token_usage.get("completion_tokens", 0) or 0)
        total_tokens = int(token_usage.get("total_tokens", prompt_tokens + completion_tokens) or 0)
        tools_used_names = [
            str(tool_name)
            for tool in (tools_used or [])
            if (tool_name := tool.get("tool_name")) is not None
        ]
        return {
            "response_id": response_id,
            "session_id": msg.session_key.safe_name(),
            "user_id": msg.sender_id,
            "channel": msg.session_key.channel_key(),
            "session_type": msg.session_key.type,
            "time_cost_ms": round(time_cost_seconds * 1000),
            "prompt_tokens": prompt_tokens,
            "completion_tokens": completion_tokens,
            "total_tokens": total_tokens,
            "iteration_count": iteration,
            "tool_count": len(tools_used_names),
            "tools_used_names": tools_used_names,
            "response_length": len(final_content),
            "created_at": datetime.now().isoformat(),
            "has_reasoning": bool(final_reasoning_content),
        }

    async def _evaluate_previous_response_outcome(
        self, session: Session, msg: InboundMessage
    ) -> None:
        """Evaluate the latest assistant response before appending a new user turn."""
        if msg.metadata.get(HEARTBEAT_METADATA_KEY):
            return

        last_response = None
        for message in reversed(session.messages):
            if message.get("role") == "assistant" and message.get("response_id"):
                last_response = message
                break
            if message.get("role") == "user":
                break

        if last_response is None:
            return

        response_id = last_response["response_id"]
        evaluation = evaluate_response_outcome(
            session.messages
            + [{"role": "user", "content": msg.content, "timestamp": msg.timestamp.isoformat()}],
            response_id,
            feedback_events=session.metadata.get("feedback_events", []),
            now=msg.timestamp,
        )
        if evaluation is None:
            return

        outcomes = session.metadata.setdefault("response_outcomes", {})
        previous = outcomes.get(response_id)
        if not should_update_outcome(previous, evaluation):
            return

        outcome_payload = evaluation.to_dict()
        outcomes[response_id] = outcome_payload
        LangfuseClient.get_instance().update_response_outcome(
            response_id,
            outcome_payload["outcome_label"],
            outcome_payload,
        )
        await self.bus.publish_outbound(
            OutboundMessage(
                session_key=msg.session_key,
                content="",
                event_type=OutboundEventType.RESPONSE_OUTCOME_EVALUATED,
                response_id=response_id,
                metadata={"response_outcome_evaluated": outcome_payload},
            )
        )

    def _get_channel_config(self, session_key: SessionKey):
        """Get channel config for a session key.

        Args:
            session_key: Session key to get channel config for

        Returns:
            Channel config object if found, None otherwise
        """
        return self.config.channels_config.get_channel_by_key(session_key.channel_key())

    @staticmethod
    def _normalize_id_list(value: Any) -> list[str]:
        if value is None:
            return []
        if isinstance(value, str):
            value = [value]
        if not isinstance(value, list):
            return []
        normalized: list[str] = []
        for item in value:
            item_str = str(item).strip()
            if item_str and item_str not in normalized:
                normalized.append(item_str)
        return normalized

    def _metadata_memory_peer_ids(self, metadata: dict[str, Any] | None) -> list[str]:
        if not isinstance(metadata, dict):
            return []
        return self._normalize_id_list(metadata.get("memory_peers"))

    def _metadata_memory_owner_user_ids(self, metadata: dict[str, Any] | None) -> list[str]:
        if not isinstance(metadata, dict):
            return []
        return self._normalize_id_list(metadata.get("memory_users"))

    def _channel_memory_peer_ids(self, channel_config: Any) -> list[str]:
        return self._normalize_id_list(getattr(channel_config, "memory_peer", None))

    def _channel_memory_owner_user_ids(self, channel_config: Any) -> list[str]:
        return self._normalize_id_list(getattr(channel_config, "memory_user", None))

    def _get_ov_tools_enable(self, session_key: SessionKey) -> bool:
        """Get ov_tools_enable setting from channel config.

        Args:
            session_key: Session key to get channel config for

        Returns:
            True if ov tools should be enabled, False otherwise
        """
        if not self.config.ov_server.is_available():
            return False
        channel_config = self._get_channel_config(session_key)
        return getattr(channel_config, "ov_tools_enable", True) if channel_config else True

    def _create_skill_runtime(
        self,
        *,
        session_key: SessionKey,
        workspace: Path,
        ov_tools_enable: bool,
        disabled_tools: list[str] | None,
        openviking_connection: dict[str, Any] | None,
        actor_peer_id: str | None,
    ) -> SkillRuntimeContext | None:
        if (
            self.config is None
            or not ov_tools_enable
            or not self.config.ov_server.is_available()
            or not self.tools.has("openviking_multi_read")
            or "openviking_multi_read" in set(disabled_tools or ())
        ):
            return None
        local_skills = SkillsLoader(workspace).list_skills(filter_unavailable=False)
        workspace_id = (
            self.sandbox_manager.to_workspace_id(session_key)
            if self.sandbox_manager
            else session_key.safe_name()
        )
        return SkillRuntimeContext(
            config=self.config,
            session_key=session_key,
            sandbox_manager=self.sandbox_manager,
            workspace_id=workspace_id,
            openviking_connection=openviking_connection,
            actor_peer_id=actor_peer_id,
            local_skill_names=(skill["name"] for skill in local_skills),
        )

    async def _process_system_message(self, msg: InboundMessage) -> OutboundMessage | None:
        """
        Process a system message (e.g., subagent announce).

        The chat_id field contains "original_channel:original_chat_id" to route
        the response back to the correct destination.
        """
        logger.info(f"Processing system message from {msg.sender_id}")

        session = self.sessions.get_or_create(msg.session_key)

        # Get channel config
        ov_tools_enable = self._get_ov_tools_enable(msg.session_key)
        profile_user_list = []
        channel_config = self._get_channel_config(msg.session_key)
        if channel_config and ov_tools_enable:
            profile_user_list = getattr(channel_config, "profile_user_list", [])

        # Build messages with the announce content
        provider_name = self.config.get_provider_name(self.model) if self.config else None
        actor_peer_id = getattr(msg, "actor_peer_id", None) or msg.sender_id
        history = await self._build_prompt_history(
            session,
            provider_name=provider_name,
            openviking_connection=msg.openviking_connection,
            actor_peer_id=actor_peer_id,
        )
        from vikingbot.agent.context import ContextBuilder

        message_workspace = (
            self.sandbox_manager.get_workspace_path(msg.session_key)
            if self.sandbox_manager
            else self.workspace
        )
        message_context = ContextBuilder(
            message_workspace,
            sandbox_manager=self.sandbox_manager,
            sender_id=msg.sender_id,
            actor_peer_id=actor_peer_id,
            openviking_connection=msg.openviking_connection,
            enable_subagents=self._subagents_enabled(),
            config=self.config,
        )
        messages = await message_context.build_messages(
            history=history,
            current_message=msg.content,
            session_key=msg.session_key,
            ov_tools_enable=ov_tools_enable,
            profile_user_list=profile_user_list,
        )

        # Run agent loop (no events published)
        agent_turns: list[dict[str, Any]] = []
        (
            final_content,
            final_reasoning_content,
            tools_used,
            token_usage,
            iteration,
        ) = await self._run_agent_loop(
            messages=messages,
            session_key=msg.session_key,
            publish_events=False,
            sender_id=msg.sender_id,
            actor_peer_id=actor_peer_id,
            ov_tools_enable=ov_tools_enable,
            memory_peer_ids=None,
            openviking_connection=msg.openviking_connection,
            channel_metadata=msg.metadata,
            captured_turns=agent_turns,
        )

        if final_content is None or (isinstance(final_content, str) and not final_content.strip()):
            final_content = "Background task completed."

        # Save to session (mark as system message in history)
        session.add_message("user", f"[System: {msg.sender_id}] {msg.content}")
        session.add_message(
            "assistant",
            final_content,
            tools_used=tools_used if tools_used else None,
            reasoning_content=final_reasoning_content,
            agent_turns=agent_turns if agent_turns else None,
        )
        await self.sessions.save(session)

        return OutboundMessage(
            session_key=msg.session_key,
            content=final_content,
            metadata=dict(msg.metadata or {}),
        )

    async def _consolidate_memory(
        self,
        session,
        archive_all: bool = False,
        openviking_connection: dict[str, Any] | None = None,
    ) -> None:
        """Consolidate old messages into MEMORY.md + HISTORY.md. Works on a cloned session."""
        try:
            if not session.messages:
                return

            # use openviking tools to extract memory
            config = self.config
            if config.mode == BotMode.READONLY:
                if not config.channels_config or not config.channels_config.get_all_channels():
                    return
                allow_from = [config.ov_server.admin_user_id]
                for channel_config in config.channels_config.get_all_channels():
                    if channel_config and channel_config.type.value == session.key.type:
                        if hasattr(channel_config, "allow_from"):
                            allow_from.extend(channel_config.allow_from)
                messages = [msg for msg in session.messages if msg.get("sender_id") in allow_from]
                session.messages = messages
            if self.config.ov_server.is_available():
                await self._consolidate_viking_memory(
                    session,
                    openviking_connection=openviking_connection,
                )

            if self.sandbox_manager:
                memory_workspace = self.sandbox_manager.get_workspace_path(session.key)
            else:
                memory_workspace = self.workspace

            memory = MemoryStore(memory_workspace, config=self.config)
            if archive_all:
                old_messages = session.messages
                keep_count = 0
            else:
                keep_count = min(10, max(2, self.memory_window // 2))
                old_messages = session.messages[:-keep_count]
            if not old_messages:
                return
            logger.info(
                f"Memory consolidation started: {len(session.messages)} messages, archiving {len(old_messages)}, keeping {keep_count}"
            )

            # Format messages for LLM (include tool names when available)
            lines = []
            for m in old_messages:
                if not m.get("content"):
                    continue
                tools_used = m.get("tools_used", [])
                if tools_used and isinstance(tools_used, list):
                    tool_names = [
                        tc.get("tool_name", "unknown") for tc in tools_used if isinstance(tc, dict)
                    ]
                    tools_str = f" [tools: {', '.join(tool_names)}]" if tool_names else ""
                else:
                    tools_str = ""
                lines.append(
                    f"[{m.get('timestamp', '?')[:16]}] {m['role'].upper()}{tools_str}: {m['content']}"
                )
            conversation = "\n".join(lines)
            current_memory = memory.read_long_term()

            prompt = f"""You are a memory consolidation agent. Process this conversation and return a JSON object with exactly two keys:

1. "history_entry": A paragraph (2-5 sentences) summarizing the key events/decisions/topics. Start with a timestamp like [YYYY-MM-DD HH:MM]. Include enough detail to be useful when found by grep search later.

2. "memory_update": The updated long-term memory content. Add any new facts: user location, preferences, personal info, habits, project context, technical decisions, tools/services used. If nothing new, return the existing content unchanged.

## Current Long-term Memory
{current_memory or "(empty)"}

## Conversation to Process
{conversation}

Respond with ONLY valid JSON, no markdown fences."""

            response = await self.provider.chat(
                messages=[
                    {
                        "role": "system",
                        "content": "You are a memory consolidation agent. Respond only with valid JSON.",
                    },
                    {"role": "user", "content": prompt},
                ],
                model=self.model,
                temperature=self.temperature,
                session_id=session.key.safe_name(),
            )
            text = (response.content or "").strip()
            if text.startswith("```"):
                text = text.split("\n", 1)[-1].rsplit("```", 1)[0].strip()
            result = json.loads(text)

            if entry := result.get("history_entry"):
                memory.append_history(entry)
            if update := result.get("memory_update"):
                if self.config.use_local_memory and update != current_memory:
                    memory.write_long_term(update)

            # Session trimming and saving is handled by the caller before calling _consolidate_memory
            # This method works on a cloned session, so no need to save it
            logger.info("Memory consolidation done")
        except Exception as e:
            logger.exception(f"Memory consolidation failed: {e}")

    async def _consolidate_viking_memory(
        self,
        session,
        openviking_connection: dict[str, Any] | None = None,
    ) -> None:
        """Consolidate old messages into MEMORY.md + HISTORY.md. Works on a cloned session."""
        try:
            if not session.messages:
                logger.info(
                    f"No messages to commit openviking for session {session.key.safe_name()} (allow_from filter applied)"
                )
                return

            # use openviking tools to extract memory
            await hook_manager.execute_hooks(
                context=HookContext(
                    event_type="message.compact",
                    session_id=session.key.safe_name(),
                    workspace_id=self._get_ov_workspace_id(session.key),
                    session_key=session.key,
                    config=self.config,
                    openviking_connection=openviking_connection,
                ),
                session=session,
                openviking_connection=openviking_connection,
            )
        except Exception as e:
            logger.exception(f"Memory consolidation failed: {e}")

    async def _safe_consolidate_memory(
        self,
        session,
        archive_all: bool = False,
        openviking_connection: dict[str, Any] | None = None,
    ) -> None:
        """Safe wrapper for _consolidate_memory that ensures all exceptions are caught."""
        try:
            await self._consolidate_memory(
                session,
                archive_all,
                openviking_connection=openviking_connection,
            )
        except Exception as e:
            logger.exception(f"Background memory consolidation task failed: {e}")

    def _check_cmd_auth(self, msg: InboundMessage) -> bool:
        """Check if the session key is authorized for command execution.

        Returns:
            True if authorized, False otherwise.
        Args:
            session_key: Session key to check.
        """
        if self.config.mode == BotMode.NORMAL:
            return True
        allow_from = []
        if self.config.ov_server and self.config.ov_server.admin_user_id:
            allow_from.append(self.config.ov_server.admin_user_id)
        channel_config = self._get_channel_config(msg.session_key)
        if channel_config:
            allow_cmd = getattr(channel_config, "allow_cmd_from", [])
            if allow_cmd:
                allow_from.extend(allow_cmd)

        # If channel not found or sender not in allow_from list, ignore message
        if msg.sender_id not in allow_from:
            logger.debug(
                f"Sender {msg.sender_id} not allowed in channel {msg.session_key.channel_key()}"
            )
            return False
        return True

    async def process_direct(
        self,
        content: str,
        session_key: SessionKey = SessionKey(type="cli", channel_id="default", chat_id="direct"),
        metadata: dict[str, object] | None = None,
    ) -> str:
        """
        Process a message directly (for CLI or cron usage).

        Args:
            content: The message content.
            session_key: Session identifier (overrides channel:chat_id for session lookup).

        Returns:
            The agent's response.
        """
        await self._connect_mcp()
        msg = InboundMessage(
            session_key=session_key,
            sender_id="user",
            content=content,
            metadata=metadata or {},
        )

        response = await self._process_message(msg)
        return response.content if response else ""