session_surface.py 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112
  1. """Per-turn client surface (floating HUD, live voice) carried through canonical admission.
  2. A surface is a fact about ONE turn, never about the session: the same session alternates
  3. between the app window, the HUD and a spoken delegation. It is committed with the admission
  4. row and reaches the model as a note on the user message (api_content sidecar), so the
  5. persisted user row stays the words the user typed and the frozen system prefix is untouched.
  6. """
  7. from contextlib import contextmanager
  8. from contextvars import ContextVar
  9. from hermes_state_runtime import RuntimeStoreError
  10. SURFACES = frozenset({'hud', 'voice-live'})
  11. _VOICE_CONTEXT_LIMIT = 6000
  12. _SUBMIT_FIELDS = ('surface', 'voice_context', 'interrupted', 'voice_turn')
  13. _surface_turn = ContextVar('surface_turn', default=None)
  14. def submit_surface_fields(params):
  15. """The raw per-turn surface fields of a ``prompt.submit`` request, forwarded to admission."""
  16. return {key: params[key] for key in _SUBMIT_FIELDS if key in params}
  17. def admit_surface(params):
  18. """Wire ``surface`` / ``voice_context`` / ``interrupted`` / ``voice_turn`` -> committed ``surface_v1``
  19. (``{}`` when absent). ``voice_turn`` marks a spoken voice-mode turn: it runs on ``auxiliary.voice_chat``."""
  20. surface, context, interrupted, voice_turn = (params.get(key) for key in _SUBMIT_FIELDS)
  21. if surface is not None and surface not in SURFACES:
  22. raise RuntimeStoreError('invalid_params')
  23. # The spoken transcript only makes sense for a live-voice delegation; anywhere else it is
  24. # a client smuggling model input past the persisted row.
  25. if context is not None and (surface != 'voice-live' or not isinstance(context, str)):
  26. raise RuntimeStoreError('invalid_params')
  27. if any(flag is not None and type(flag) is not bool for flag in (interrupted, voice_turn)):
  28. raise RuntimeStoreError('invalid_params')
  29. committed = {}
  30. if surface:
  31. committed['surface'] = surface
  32. if context:
  33. committed['voice_context'] = context[:_VOICE_CONTEXT_LIMIT]
  34. if interrupted:
  35. committed['interrupted'] = True
  36. if voice_turn:
  37. committed['voice_turn'] = True
  38. return {'surface_v1': committed} if committed else {}
  39. def restore_surface(committed):
  40. """A committed ``surface_v1`` arriving across a process boundary (managed worker), re-checked by
  41. the admission validator: only an object admission itself could have committed is accepted."""
  42. if (not isinstance(committed, dict) or not committed or set(committed) - set(_SUBMIT_FIELDS)
  43. or admit_surface(committed).get('surface_v1', {}) != committed):
  44. raise RuntimeStoreError('invalid_params')
  45. return committed
  46. def _hud_note(committed, valid_tool_names):
  47. from agent.prompt_builder import hud_surface_note
  48. return hud_surface_note(valid_tool_names)
  49. def _voice_live_note(committed, valid_tool_names):
  50. from tools.voice_live import voice_live_turn_note
  51. return voice_live_turn_note(committed.get('voice_context') or '')
  52. _SURFACE_NOTES = {'hud': _hud_note, 'voice-live': _voice_live_note}
  53. def surface_note(committed, valid_tool_names=None):
  54. """The model-bound note for a committed surface (``""`` for the plain app window): barge-in
  55. first, then the HUD read-the-window-below prior or the spoken-delegation contract."""
  56. notes = []
  57. if committed.get('interrupted'):
  58. from tools.tts_streaming import SPEECH_INTERRUPTED_NOTE
  59. notes.append(SPEECH_INTERRUPTED_NOTE)
  60. render = _SURFACE_NOTES.get(committed.get('surface'))
  61. if render is not None:
  62. notes.append(render(committed, valid_tool_names))
  63. return '\n\n'.join(note for note in notes if note)
  64. @contextmanager
  65. def surface_turn_scope(committed):
  66. token = _surface_turn.set(committed)
  67. try:
  68. yield
  69. finally:
  70. _surface_turn.reset(token)
  71. def surface_voice_turn():
  72. """Whether the executing admission is a spoken voice turn (``auxiliary.voice_chat`` route)."""
  73. return bool((_surface_turn.get() or {}).get('voice_turn'))
  74. def surface_turn_note(agent):
  75. """The executing admission's surface note, gated on the tools this agent actually has."""
  76. committed = _surface_turn.get()
  77. if not committed:
  78. return ''
  79. return surface_note(committed, getattr(agent, 'valid_tool_names', None))
  80. def arm_surface_turn(agent, notes=(), voice_turn=False):
  81. """Project the executing admission's surface onto the agent's one-turn inputs, the same way in
  82. process and in a managed worker: the ``auxiliary.voice_chat`` marker and the must-deliver notes
  83. that ride the current user message (never the system prompt). Assigned unconditionally so a
  84. reused agent never replays a stale note or route."""
  85. agent._voice_turn_pending = bool(voice_turn) or surface_voice_turn()
  86. agent._gateway_turn_context_notes = '\n\n'.join(
  87. note for note in (*notes, surface_turn_note(agent)) if note)