hermes-agent/agent/side_question.py

"""Context-aware side questions (``/btw``).

Answers a quick question ABOUT the current conversation without touching it (no
synthetic turns, no role-alternation risk, no prompt-cache invalidation). Two
paths, picked automatically:

* **Cache-parity fork (preferred).** With a live parent ``AIAgent``, a detached
  fork from :func:`agent.background_review.build_cache_parity_fork` replays the
  parent's snapshot verbatim against the warm prefix cache. Tool calls are denied
  at dispatch, persistence is detached, usage goes to the parent.
* **One-shot digest (fallback).** With no live parent (e.g. the gateway evicted
  the cached agent), a rendered transcript goes through :func:`agent.oneshot.run_oneshot`.

``auxiliary.side_question.provider`` / ``.model`` route the fork to another model
and replay a compact digest (cold cache on a different model).
"""

import logging
from typing import Any, Dict, List, Optional

from agent.background_review import _msg_text

logger = logging.getLogger(__name__)

# Free-form auxiliary task name (auxiliary.side_question.*), main-model-first.
SIDE_QUESTION_TASK = "side_question"

# Fork path: the model may waste an iteration on a (denied) tool call first.
_FORK_MAX_ITERATIONS = 3

# Fallback one-shot path: per-message and total character budgets.
_PER_MESSAGE_CHAR_CAP = 2000
_TRANSCRIPT_CHAR_BUDGET = 24000

_FORK_PROMPT = (
    "The user asked a quick SIDE question with /btw while the main work "
    "continues in the original session.\n"
    "Rules:\n"
    "- Answer ONLY the side question, using the conversation above as "
    "context. Do not continue, redo, or critique the main task.\n"
    "- Do NOT call any tools — they are disabled for this side question. "
    "Answer directly in text.\n"
    "- If the conversation does not contain enough information to answer, "
    "say so plainly instead of guessing.\n"
    "- Be concise and direct."
)

_ONESHOT_INSTRUCTIONS = (
    "You are the same AI assistant that is currently working inside the "
    "conversation transcribed below. The user has asked a quick SIDE question "
    "with /btw while the main work continues.\n"
    "Rules:\n"
    "- Answer ONLY the side question. Do not continue, redo, or critique the "
    "main task.\n"
    "- Use the transcript as your primary context; it is a snapshot and may "
    "not include the very latest activity.\n"
    "- If the transcript does not contain enough information to answer, say "
    "so plainly instead of guessing.\n"
    "- Be concise and direct."
)

_ROLE_LABELS = {"user": "USER", "assistant": "ASSISTANT", "tool": "TOOL RESULT"}


def trim_snapshot_for_fork(history: Optional[List[Dict[str, Any]]]) -> List[Dict[str, Any]]:
    """Drop trailing messages until the snapshot ends with a completed assistant text.

    A mid-turn snapshot can end on unresolved ``tool_calls``, a tool result, or
    the in-flight user message; appending the side question after any of those
    breaks role alternation on strict providers. Trimming only the TAIL keeps
    the warm prefix-cache property.
    """
    msgs = list(history or [])
    while msgs:
        last = msgs[-1]
        if isinstance(last, dict) and last.get("role") == "assistant" and not last.get("tool_calls"):
            break
        msgs.pop()
    return msgs


def render_history_for_side_question(
    history: Optional[List[Dict[str, Any]]],
    char_budget: int = _TRANSCRIPT_CHAR_BUDGET,
) -> str:
    """Render a snapshot as a plain-text transcript (fallback path only).

    Newest-biased fit to ``char_budget``. Tool calls are summarized by name, tool
    results included truncated (so "what did that output" stays answerable), the
    system prompt skipped.
    """
    lines: List[str] = []
    for msg in history or []:
        if not isinstance(msg, dict):
            continue
        role = msg.get("role")
        text = _msg_text(msg)
        if role == "assistant" and msg.get("tool_calls"):
            names = [(tc.get("function") or {}).get("name", "?") for tc in msg["tool_calls"] if isinstance(tc, dict)]
            lines.append(f"ASSISTANT [called tools: {', '.join(names)}]")
        label = _ROLE_LABELS.get(role)
        if label and text:
            lines.append(f"{label}: {text[:_PER_MESSAGE_CHAR_CAP]}")

    kept: List[str] = []
    used = 0
    for line in reversed(lines):
        cost = len(line) + 1
        if used + cost > char_budget and kept:
            break
        kept.append(line)
        used += cost
    kept.reverse()

    if not kept:
        return "(no prior conversation)"
    prefix = "[...older conversation omitted...]\n" if len(kept) < len(lines) else ""
    return prefix + "\n".join(kept)


def _side_question_task_config() -> Dict[str, Any]:
    """Return ``auxiliary.side_question`` from config (or ``{}``)."""
    try:
        from hermes_cli.config import load_config_readonly

        cfg = load_config_readonly()
    except Exception:
        return {}
    aux = cfg.get("auxiliary", {}) if isinstance(cfg.get("auxiliary"), dict) else {}
    task = aux.get(SIDE_QUESTION_TASK, {})
    return task if isinstance(task, dict) else {}


def _answer_via_fork(parent_agent: Any, question: str, history: Optional[List[Dict[str, Any]]]) -> str:
    """Answer via a cache-parity fork of ``parent_agent`` on the calling thread.

    The thread-scoped tool whitelist is emptied so any tool call is denied at
    dispatch: ``tools[]`` stays byte-identical for cache parity, but the side
    question can never mutate anything.
    """
    from agent.background_review import (
        _digest_history,
        _record_review_usage_to_parent,
        _snapshot_review_usage,
        build_cache_parity_fork,
    )
    from hermes_cli.plugins import clear_thread_tool_whitelist, set_thread_tool_whitelist

    fork, _rt, routed = build_cache_parity_fork(
        parent_agent, _side_question_task_config(),
        max_iterations=_FORK_MAX_ITERATIONS, write_origin="side_question",
    )
    try:
        set_thread_tool_whitelist(
            set(),
            deny_msg_fmt=(
                "Side question (/btw) denied tool call: {tool_name}. "
                "Tools are disabled here — answer directly from the "
                "conversation context."
            ),
        )
        snapshot = trim_snapshot_for_fork(history)
        result = fork.run_conversation(
            user_message=f"{_FORK_PROMPT}\n\nSide question: {question}",
            conversation_history=_digest_history(snapshot) if routed else snapshot,
        )
        answer = (result or {}).get("final_response", "") or ""
        if not answer and result and result.get("error"):
            raise RuntimeError(str(result["error"]))
        return answer.strip()
    finally:
        clear_thread_tool_whitelist()
        # Attribute the fork's usage to the parent session; teardown never raises.
        for step in (
            lambda: _record_review_usage_to_parent(parent_agent, _snapshot_review_usage(fork)),
            fork.shutdown_memory_provider,
            fork.close,
        ):
            try:
                step()
            except Exception:
                pass


def _answer_via_oneshot(question: str, history: Optional[List[Dict[str, Any]]], **run_kwargs: Any) -> str:
    """Fallback: answer from a rendered transcript digest in one aux call."""
    from agent.oneshot import run_oneshot

    user_input = (
        "Conversation transcript (snapshot):\n"
        "-----\n"
        f"{render_history_for_side_question(history)}\n"
        "-----\n\n"
        f"Side question: {question}"
    )
    return run_oneshot(
        instructions=_ONESHOT_INSTRUCTIONS, user_input=user_input, task=SIDE_QUESTION_TASK, **run_kwargs
    )


def answer_side_question(
    question: str,
    history: Optional[List[Dict[str, Any]]],
    *,
    parent_agent: Any = None,
    main_runtime: Optional[Dict[str, Any]] = None,
    max_tokens: int = 2048,
    temperature: Optional[float] = 0.3,
    timeout: float = 180.0,
) -> str:
    """Answer ``question`` against a snapshot of ``history``: cache-parity fork when
    ``parent_agent`` is live, else (or on empty answer / failure) the one-shot digest.
    Raises on failure — callers surface the error on their own UI."""
    question = (question or "").strip()
    if not question:
        raise ValueError("answer_side_question requires a non-empty question")

    if parent_agent is not None:
        try:
            answer = _answer_via_fork(parent_agent, question, history)
            if answer:
                return answer
            logger.warning("/btw fork returned an empty answer; falling back to one-shot")
        except Exception:
            logger.warning("/btw cache-parity fork failed; falling back to one-shot", exc_info=True)

    return _answer_via_oneshot(
        question, history,
        main_runtime=main_runtime, max_tokens=max_tokens, temperature=temperature, timeout=timeout,
    )