oneshot_footprint.py 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778
  1. """What a finite one-shot session (``hermes chat -q`` / ``--oneshot``, ``hermes -z``) does NOT do.
  2. A one-shot run has no later session in its HERMES_HOME to learn for: the process answers one query and
  3. exits. The interactive self-improvement loop is pure overhead there, and a measured one — across 21
  4. one-shot benchmark trajectories the agent authored 7 new skills and patched a bundled one mid-task, 37 of
  5. ~215 tool calls were ``skill_view``/``skill_manage``, and skill text was 34% of every tool-result byte fed
  6. back into context. Two rules follow, both keyed on the same session marker the approval gate and the
  7. delegation dispatcher already read (``HERMES_SINGLE_QUERY_SESSION``), so interactive sessions are untouched
  8. (``skill_manage`` itself stays offered: a one-shot may still author skills):
  9. * the ## Skills prompt drops the "record it / patch it / offer to save" coaching and the "load process skills
  10. even for tasks you already know" push, keeping only "load a skill when it adds knowledge you lack";
  11. * delegation is capped per session (``delegation.oneshot_max_children``): subagents each re-pay a cold
  12. system prompt and re-explore the repo, and the observed spawns were mostly "independent review of my own
  13. work" rather than parallel work.
  14. Nobody answers or steers a one-shot either, so it also drops what only an interactive user can use:
  15. ``clarify`` (its toolset is disabled for the session), the mid-turn steering briefing in the system prompt,
  16. and ``delegate_task``'s live-control surface (children are joined inside the call, so ``action``
  17. list/steer/stop never has a running child to reach).
  18. """
  19. from __future__ import annotations
  20. from typing import Any
  21. # Toolsets a one-shot session never gets (``toolsets.session_disabled_toolsets(oneshot=True)``): the toolset is
  22. # the surface gate, so the tool list, the tool_search bridge and delegate children all lose them together.
  23. ONESHOT_DISABLED_TOOLSETS = ("clarify",)
  24. def is_single_query_session() -> bool:
  25. """The finite ``-q`` marker, read through the session env so gateway-bound sessions never see it.
  26. A gateway-owned ``chat -q`` / ``-z`` session never has that env (only the client process set it): its
  27. one-shot fact is the frozen launch policy's ``oneshot`` source, a property of the SESSION, not of one
  28. admission, so the cached agent's tools[] and system prompt stay byte-stable across its turns."""
  29. try:
  30. from gateway.session_policy import active_policy
  31. except ImportError: # install without the gateway package: no owner-bound session
  32. pass
  33. else:
  34. policy = active_policy()
  35. if policy is not None:
  36. return policy.source == "oneshot"
  37. try:
  38. from gateway.session_context import get_session_env
  39. except Exception:
  40. import os
  41. get_session_env = os.environ.get
  42. return str(get_session_env("HERMES_SINGLE_QUERY_SESSION", "") or "") == "1"
  43. ONESHOT_SKILLS_LOAD_GUIDANCE = (
  44. "## Skills\n"
  45. "Scan the skills below and load one with skill_view(name) only when it carries domain knowledge you lack "
  46. "for THIS task (an API, a tool's commands, a project's conventions). Do not load general process skills "
  47. "(testing, debugging, review methodology) for work you already know how to do.\n"
  48. )
  49. def agent_is_oneshot(agent: Any) -> bool:
  50. """:func:`is_single_query_session`, frozen on *agent* at its first tool build so a later MCP refresh or
  51. prompt build answers the same even outside the turn's policy scope (tools[] and the prompt stay byte-stable)."""
  52. cached = getattr(agent, "_oneshot_session", None)
  53. if not isinstance(cached, bool):
  54. cached = is_single_query_session()
  55. agent._oneshot_session = cached
  56. return cached
  57. def oneshot_tool_schemas(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
  58. """*tools* with ``delegate_task`` swapped for its one-shot variant (no live-control parameters)."""
  59. from tools.delegate_tool import oneshot_delegate_function
  60. return [
  61. {**tool, "function": oneshot_delegate_function(tool["function"])}
  62. if (tool.get("function") or {}).get("name") == "delegate_task" else tool
  63. for tool in tools
  64. ]