session_source.py 3.3 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061
  1. """Session source vocabulary: the ``source`` label a session row carries, and which sources have a
  2. person reading the turn as it runs. A leaf (its one import is the stdlib-only session context), so
  3. the ``run_agent`` facade and its siblings import it directly."""
  4. from __future__ import annotations
  5. from typing import Any, Optional
  6. from gateway.session_context import get_session_env
  7. # Sources that label the human conversation an interactive UI transport hosts. A finite ``hermes chat -q`` /
  8. # one-shot child spawned from such a session inherits HERMES_SESSION_SOURCE (the terminal tool bridges the
  9. # session env into child processes) but is NOT that conversation: labelling it ``tui``/``desktop`` lists it
  10. # in the TUI/WebUI pickers as a resumable chat and lets ``hermes -c`` in the TUI continue it (#112550).
  11. # Automation sources (tool, a2a, ...) are inherited on purpose; a Kanban worker's descendants drop its
  12. # gateway-only ``kanban`` label (delegation_context.scrub_kanban_env).
  13. UI_TRANSPORT_SOURCES = frozenset({"tui", "desktop"})
  14. # Finite non-interactive CLI runs (``hermes chat -q``/``--oneshot``, ``hermes -z``) get their own source so human
  15. # pickers hide them without title/cwd heuristics; ``hermes -c`` still treats them as CLI history.
  16. ONESHOT_SOURCE = "oneshot"
  17. CLI_FAMILY_SOURCES = frozenset({"cli", ONESHOT_SOURCE})
  18. # The owner's own local surfaces: the only sources that carry OpenAI Daybreak (agent.daybreak). It is the
  19. # approved account's own access (no third-party or downstream use); a plugin session tagged ``telegram`` is
  20. # someone else's chat even when a local backend builds its agent.
  21. DAYBREAK_SOURCES = UI_TRANSPORT_SOURCES | {"cli"}
  22. # A person reads the turn as it runs: not cron, batch, a messaging chat, or a one-shot run.
  23. ATTENDED_SOURCES = UI_TRANSPORT_SOURCES | {"cli", "acp"}
  24. def create_surface(source: str) -> str:
  25. """The ``session.create`` label for a session source: ``desktop`` is the Desktop's platform name for
  26. the ``gui`` surface (gateway.session_policy.SURFACES), which the create contract does not list."""
  27. return "gui" if source == "desktop" else source
  28. def session_source_for(platform: Optional[str]) -> str:
  29. source = str(get_session_env("HERMES_SESSION_SOURCE", "") or "").strip()
  30. single_query = get_session_env("HERMES_SINGLE_QUERY_SESSION", "") == "1"
  31. explicit = get_session_env("HERMES_SESSION_SOURCE_EXPLICIT", "") == "1"
  32. if single_query and not explicit and source in UI_TRANSPORT_SOURCES:
  33. source = ""
  34. if single_query and not source and (platform or "cli") == "cli":
  35. return ONESHOT_SOURCE
  36. return source or platform or "cli"
  37. def is_attended(agent: Any) -> bool:
  38. """A delegated child answers its parent, not a person, though its copied context still carries
  39. the parent's source; a library caller (no platform) has no one reading either."""
  40. platform = getattr(agent, "platform", None)
  41. if not platform or platform == "subagent":
  42. return False
  43. # A gateway-admitted ``hermes chat -q`` / ``-z`` turn carries its one-shot fact on the admission,
  44. # not in HERMES_SINGLE_QUERY_SESSION (the daemon never had that env).
  45. from gateway.session_finite import finite_turn_required
  46. if finite_turn_required() is True:
  47. return False
  48. return session_source_for(platform) in ATTENDED_SOURCES