side_question.py 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175
  1. """Context-aware side questions (``/btw``): answer a question ABOUT the conversation without
  2. touching it (no synthetic turns, no role-alternation risk, no prompt-cache invalidation).
  3. Preferred path: a detached cache-parity fork of the live parent ``AIAgent`` replays its
  4. snapshot verbatim against the warm prefix cache (tools denied at dispatch, persistence
  5. detached, usage attributed to the parent). Fallback (no live parent, e.g. gateway evicted
  6. the agent): a rendered transcript through :func:`agent.oneshot.run_oneshot`.
  7. ``auxiliary.side_question.provider``/``.model`` route the fork elsewhere with a compact digest.
  8. """
  9. import logging
  10. from typing import Any, Callable, Dict, List, Optional
  11. from agent.background_review import _msg_text
  12. logger = logging.getLogger(__name__)
  13. # Free-form auxiliary task name (auxiliary.side_question.*), main-model-first.
  14. SIDE_QUESTION_TASK = "side_question"
  15. # Fork path: the model may waste an iteration on a (denied) tool call first.
  16. _FORK_MAX_ITERATIONS = 3
  17. # Fallback one-shot path: per-message and total character budgets.
  18. _PER_MESSAGE_CHAR_CAP = 2000
  19. _TRANSCRIPT_CHAR_BUDGET = 24000
  20. _FORK_PROMPT = (
  21. "The user asked a quick SIDE question with /btw while the main work continues in the original "
  22. "session.\nRules:\n- Answer ONLY the side question, using the conversation above as context. Do not continue, "
  23. "redo, or critique the main task.\n- Do NOT call any tools — they are disabled for this side question. Answer "
  24. "directly in text.\n- If the conversation does not contain enough information to answer, say so plainly instead "
  25. "of guessing.\n- Be concise and direct."
  26. )
  27. _ONESHOT_INSTRUCTIONS = (
  28. "You are the same AI assistant that is currently working inside the conversation transcribed below. The user "
  29. "has asked a quick SIDE question with /btw while the main work continues.\nRules:\n- Answer ONLY the side "
  30. "question. Do not continue, redo, or critique the main task.\n- Use the transcript as your primary context; it "
  31. "is a snapshot and may not include the very latest activity.\n- If the transcript does not contain enough "
  32. "information to answer, say so plainly instead of guessing.\n- Be concise and direct."
  33. )
  34. _ROLE_LABELS = {"user": "USER", "assistant": "ASSISTANT", "tool": "TOOL RESULT"}
  35. def trim_snapshot_for_fork(history: Optional[list[dict[str, Any]]]) -> list[dict[str, Any]]:
  36. """Drop trailing messages until the snapshot ends with a completed assistant text.
  37. A mid-turn tail (unresolved ``tool_calls``, tool result, in-flight user message) breaks
  38. role alternation on strict providers; trimming only the TAIL keeps the warm prefix cache.
  39. """
  40. msgs = list(history or [])
  41. while msgs:
  42. last = msgs[-1]
  43. if isinstance(last, dict) and last.get("role") == "assistant" and not last.get("tool_calls"):
  44. break
  45. msgs.pop()
  46. return msgs
  47. def render_history_for_side_question(history: Optional[list[dict[str, Any]]], char_budget: int = _TRANSCRIPT_CHAR_BUDGET) -> str:
  48. """Plain-text transcript for the fallback path: newest-biased fit to ``char_budget``,
  49. tool calls summarized by name, tool results truncated, system prompt skipped."""
  50. lines: list[str] = []
  51. for msg in history or []:
  52. if not isinstance(msg, dict):
  53. continue
  54. role = msg.get("role")
  55. text = _msg_text(msg)
  56. if role == "assistant" and msg.get("tool_calls"):
  57. names = [(tc.get("function") or {}).get("name", "?") for tc in msg["tool_calls"] if isinstance(tc, dict)]
  58. lines.append(f"ASSISTANT [called tools: {', '.join(names)}]")
  59. label = _ROLE_LABELS.get(role)
  60. if label and text:
  61. lines.append(f"{label}: {text[:_PER_MESSAGE_CHAR_CAP]}")
  62. kept: list[str] = []
  63. used = 0
  64. for line in reversed(lines):
  65. if used + len(line) + 1 > char_budget and kept:
  66. break
  67. kept.append(line)
  68. used += len(line) + 1
  69. if not kept:
  70. return "(no prior conversation)"
  71. prefix = "[...older conversation omitted...]\n" if len(kept) < len(lines) else ""
  72. return prefix + "\n".join(reversed(kept))
  73. def _side_question_task_config() -> dict[str, Any]:
  74. """Return ``auxiliary.side_question`` from config (or ``{}``)."""
  75. try:
  76. from hermes_cli.config import load_config_readonly
  77. aux = load_config_readonly().get("auxiliary")
  78. except Exception:
  79. return {}
  80. task = aux.get(SIDE_QUESTION_TASK) if isinstance(aux, dict) else None
  81. return task if isinstance(task, dict) else {}
  82. def _answer_via_fork(parent_agent: Any, question: str, history: Optional[list[dict[str, Any]]],
  83. on_fork: Optional[Callable[[Any], None]] = None) -> str:
  84. """Answer via a cache-parity fork of ``parent_agent`` on the calling thread.
  85. An empty thread-scoped tool whitelist denies every tool call at dispatch: ``tools[]``
  86. stays byte-identical for cache parity, but the side question can never mutate anything.
  87. ``on_fork(fork)`` publishes the built fork so an owner can interrupt it, and
  88. ``on_fork(None)`` follows its teardown.
  89. """
  90. from agent.background_review import _digest_history, build_cache_parity_fork, release_cache_parity_fork
  91. from hermes_cli.plugins import clear_thread_tool_whitelist, set_thread_tool_whitelist
  92. fork, _rt, routed = build_cache_parity_fork(parent_agent, _side_question_task_config(),
  93. max_iterations=_FORK_MAX_ITERATIONS, write_origin="side_question")
  94. if on_fork is not None:
  95. on_fork(fork)
  96. try:
  97. set_thread_tool_whitelist(set(), deny_msg_fmt=(
  98. "Side question (/btw) denied tool call: {tool_name}. "
  99. "Tools are disabled here — answer directly from the conversation context."))
  100. snapshot = trim_snapshot_for_fork(history)
  101. result = fork.run_conversation(user_message=f"{_FORK_PROMPT}\n\nSide question: {question}",
  102. conversation_history=_digest_history(snapshot) if routed else snapshot)
  103. answer = (result or {}).get("final_response", "") or ""
  104. if not answer and result and result.get("error"):
  105. raise RuntimeError(str(result["error"]))
  106. return answer.strip()
  107. finally:
  108. clear_thread_tool_whitelist()
  109. release_cache_parity_fork(parent_agent, fork, task=SIDE_QUESTION_TASK)
  110. if on_fork is not None:
  111. on_fork(None)
  112. def _answer_via_oneshot(question: str, history: Optional[list[dict[str, Any]]], **run_kwargs: Any) -> str:
  113. """Fallback: answer from a rendered transcript digest in one aux call."""
  114. from agent.oneshot import run_oneshot
  115. user_input = (
  116. f"Conversation transcript (snapshot):\n-----\n{render_history_for_side_question(history)}\n-----\n\n"
  117. f"Side question: {question}"
  118. )
  119. return run_oneshot(instructions=_ONESHOT_INSTRUCTIONS, user_input=user_input, task=SIDE_QUESTION_TASK, **run_kwargs)
  120. def answer_side_question(
  121. question: str, history: Optional[list[dict[str, Any]]], *, parent_agent: Any = None,
  122. main_runtime: Optional[dict[str, Any]] = None, max_tokens: int = 2048, temperature: Optional[float] = 0.3,
  123. timeout: float = 180.0, on_fork: Optional[Callable[[Any], None]] = None,
  124. should_stop: Optional[Callable[[], bool]] = None,
  125. ) -> str:
  126. """Fork when ``parent_agent`` is live, else (or on empty answer / failure) the one-shot
  127. digest. Raises on failure — callers surface the error on their own UI.
  128. ``on_fork`` receives the fork once built (and ``None`` after its teardown) so the caller can
  129. interrupt it; ``should_stop()`` true after the fork skips the one-shot fallback."""
  130. question = (question or "").strip()
  131. if not question:
  132. raise ValueError("answer_side_question requires a non-empty question")
  133. if parent_agent is not None:
  134. try:
  135. answer = (_answer_via_fork(parent_agent, question, history, on_fork) if on_fork is not None
  136. else _answer_via_fork(parent_agent, question, history))
  137. if answer:
  138. return answer
  139. logger.warning("/btw fork returned an empty answer; falling back to one-shot")
  140. except Exception:
  141. logger.warning("/btw cache-parity fork failed; falling back to one-shot", exc_info=True)
  142. if should_stop is not None and should_stop():
  143. raise RuntimeError("side question stopped")
  144. return _answer_via_oneshot(question, history, main_runtime=main_runtime, max_tokens=max_tokens,
  145. temperature=temperature, timeout=timeout)