session_cli_turn.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227
  1. """Per-admission turn inputs the classic CLI sends with ``prompt.submit`` (CALLMAP W2).
  2. Main's HermesCLI calls ``AIAgent.run_conversation`` with an API-only message (voice prefix,
  3. model-switch / skills-reload notes) while persisting the clean text, names the turn's author for
  4. memory attribution, and runs ``/model --once`` and ``/moa`` as a one-turn runtime swap. Over the
  5. session authority those are facts about ONE admitted turn, committed with the admission row as
  6. ``cli_turn_v1`` so a retry or a queued drain runs exactly what was admitted, and bound for that
  7. admission's execution only, never for a later turn.
  8. """
  9. from contextlib import contextmanager
  10. from contextvars import ContextVar
  11. from hermes_state_runtime import RuntimeStoreError
  12. _SUBMIT_FIELDS = ('turn_author', 'api_text', 'model_override', 'clarify_batch')
  13. _API_TEXT_LIMIT = 1_000_000
  14. _cli_turn: ContextVar[tuple | None] = ContextVar('cli_turn', default=None)
  15. def submit_cli_turn_fields(params):
  16. """The raw per-turn CLI fields of a ``prompt.submit`` request, forwarded to admission."""
  17. return {key: params[key] for key in _SUBMIT_FIELDS if key in params}
  18. def admit_cli_turn(params):
  19. """Wire fields -> committed ``cli_turn_v1`` (``{}`` when absent); malformed values are refused."""
  20. committed = {}
  21. if params.get('turn_author') is not None:
  22. from agent.turn_author import parse_turn_author
  23. author = parse_turn_author(params['turn_author'])
  24. if author is None:
  25. raise RuntimeStoreError('invalid_params')
  26. committed['turn_author'] = author
  27. api_text = params.get('api_text')
  28. if api_text is not None:
  29. if not isinstance(api_text, str) or len(api_text) > _API_TEXT_LIMIT:
  30. raise RuntimeStoreError('invalid_params')
  31. if api_text:
  32. committed['api_text'] = api_text
  33. override = params.get('model_override')
  34. if override is not None:
  35. from hermes_constants import parse_reasoning_effort
  36. if (not isinstance(override, dict) or set(override) - {'model', 'provider', 'reasoning'}
  37. or not isinstance(override.get('model'), str) or not override['model'].strip()
  38. or not isinstance(override.get('provider', ''), str)
  39. or ('reasoning' in override and (not isinstance(override['reasoning'], str)
  40. or parse_reasoning_effort(override['reasoning']) is None))):
  41. raise RuntimeStoreError('invalid_params')
  42. # ``reasoning``: ``/model B --once --reasoning X`` runs X for this admission only; the session's
  43. # reasoning policy (and its ``session_pins``) is never written.
  44. committed['model_override'] = {'model': override['model'].strip(),
  45. **({'provider': override['provider']} if override.get('provider') else {}),
  46. **({'reasoning': override['reasoning']} if 'reasoning' in override else {})}
  47. batch = params.get('clarify_batch')
  48. if batch is not None and type(batch) is not bool:
  49. raise RuntimeStoreError('invalid_params')
  50. if batch:
  51. # The submitting viewer answers the clarify tool's whole batch in one ``clarify`` server
  52. # request (main's batch panel: classic CLI, Ink TUI). Viewers that never set it (an ACP
  53. # editor, a raw WebSocket client) answer per-question cards.
  54. committed['clarify_batch'] = True
  55. return {'cli_turn_v1': committed} if committed else {}
  56. @contextmanager
  57. def cli_turn_scope(admission_id, committed):
  58. token = _cli_turn.set((admission_id, committed) if committed else None)
  59. try:
  60. yield
  61. finally:
  62. _cli_turn.reset(token)
  63. def cli_turn(message_id):
  64. """The committed CLI turn fields of the admission whose event id is ``message_id``; ``{}`` for
  65. any other turn, so a follow-up drained on the same task never inherits them."""
  66. bound = _cli_turn.get()
  67. if bound is None or message_id is None or str(message_id) != bound[0]:
  68. return {}
  69. return bound[1]
  70. def rebind_api_text(message_id, text):
  71. """This admission's ``api_text`` with its ``@`` references expanded, for the rest of this execution
  72. (``session_context_refs.turn_references``). The committed row keeps what the CLI sent, so a retry
  73. expands it afresh rather than twice."""
  74. bound = _cli_turn.get()
  75. if bound is not None and message_id is not None and str(message_id) == bound[0]:
  76. _cli_turn.set((bound[0], {**bound[1], 'api_text': text}))
  77. def one_turn_runtime(override, model, runtime_kwargs, config):
  78. """``(model, runtime_kwargs)`` of a committed ``model_override`` for this one turn, resolved by the
  79. same ``switch_model`` pipeline ``/model`` uses against the session's current route. Nothing is
  80. written: the session's route, policy and cached agent are untouched, so the next turn runs its own
  81. route again (main's ``/model --once`` restore). Raises ``RuntimeError`` with the switch's own
  82. sentence when the target cannot be resolved; the caller fails the turn with it."""
  83. from hermes_cli.config import get_compatible_custom_providers
  84. from hermes_cli.model_switch import switch_model
  85. result = switch_model(
  86. raw_input=override['model'], current_provider=runtime_kwargs.get('provider') or '',
  87. current_model=model or '', current_base_url=runtime_kwargs.get('base_url') or '',
  88. current_api_key=runtime_kwargs.get('api_key') or '', is_global=False,
  89. explicit_provider=override.get('provider', ''), user_providers=(config or {}).get('providers'),
  90. custom_providers=get_compatible_custom_providers(config or {}))
  91. if not result.success:
  92. raise RuntimeError(result.error_message or f"model {override['model']!r} could not be resolved")
  93. runtime = dict(runtime_kwargs)
  94. current_provider = runtime_kwargs.get('provider') or ''
  95. same_provider = (result.target_provider or '').strip().lower() == current_provider.strip().lower()
  96. # Only a ``model_aliases`` entry with its own ``base_url`` routes away from the session, as switch_model
  97. # applied it to this result (``_apply_direct_alias_endpoint``); a built-in shortcut, an endpointless entry
  98. # or a process provider's declared id names a model like a plain pick.
  99. if same_provider and not result.alias_endpoint_applied:
  100. # A plain model pick on the session's provider: the explicit provider re-resolved that provider's
  101. # default endpoint and key, and the session already has both (a mirror, a proxy, a pool), so keep
  102. # them. The wire follows the target only where the provider picks it per model (a profile's
  103. # ``api_mode_for_model``, Nous Portal, OpenCode; ``_rederive_per_model_route``); otherwise ``result.api_mode`` describes the
  104. # default host, not this session's endpoint, and the session's wire stays.
  105. from hermes_cli.model_switch import model_derived_api_mode
  106. from hermes_cli.models import normalize_opencode_base_url, opencode_provider_family
  107. if model_derived_api_mode(result.target_provider, result.new_model) is not None and result.api_mode:
  108. runtime['api_mode'] = result.api_mode
  109. api_mode = runtime.get('api_mode') or None
  110. runtime['api_mode'] = api_mode
  111. if runtime.get('base_url') and opencode_provider_family(result.target_provider):
  112. runtime['base_url'] = normalize_opencode_base_url(result.target_provider, api_mode, runtime['base_url'])
  113. else:
  114. # A different provider, or an alias that names its own endpoint and key (``model_aliases``), does
  115. # not keep this session's pool, endpoint, or key: the route ``switch_model`` resolved runs whole.
  116. runtime.update(credential_pool=None, command=None, args=[],
  117. api_key=result.api_key, base_url=result.base_url, api_mode=result.api_mode or None,
  118. request_overrides=dict(result.request_overrides or {}),
  119. capabilities=dict(result.runtime_capabilities or {}))
  120. runtime.update(provider=result.target_provider, requested_provider=result.target_provider)
  121. return result.new_model, runtime
  122. # run_conversation keys main's HermesCLI reads that the gateway's own projection does not carry
  123. # (CALLMAP §3.3 step 4): the transform-preview original, the billing descriptor and the turn's
  124. # last reasoning / preview flags.
  125. _RESULT_PASSTHROUGH = ('pre_transform_response', 'billing_block', 'last_reasoning', 'response_previewed',
  126. 'response_transformed', 'turn_exit_reason')
  127. def classic_cli_turn(turn):
  128. """A local-viewer turn on a classic-CLI surface session (``cli`` / ``oneshot`` / ``tool``): the
  129. viewer is main's HermesCLI, which reads the run_conversation-shaped result itself."""
  130. from gateway.run_turn_progress import local_viewer_turn
  131. if not local_viewer_turn(turn):
  132. return False
  133. from gateway.session_policy import policy_for_source
  134. try:
  135. policy = policy_for_source(turn._runner, turn._ctx.source)
  136. except RuntimeStoreError: # a route whose frozen policy is not restored: not a CLI viewer turn
  137. return False
  138. return policy is not None and policy.platform == 'cli'
  139. def clarify_batch_turn(turn):
  140. """The clarify tool's batch goes to main's batch panel as one request: a local-viewer turn whose
  141. submitter declared it answers the whole set (``clarify_batch`` committed with its admission).
  142. Main's classic CLI, Ink TUI and Desktop all showed every question at once (TUI-18); a viewer that
  143. never asks (an ACP editor, a raw WebSocket client) keeps one ``clarify.request`` card per question."""
  144. from gateway.run_turn_progress import local_viewer_turn
  145. return local_viewer_turn(turn) and bool(
  146. cli_turn(getattr(turn._ctx, 'inbound_message_id', None)).get('clarify_batch'))
  147. def take_cli_result_fields(result, *, aux_before=None, session_db=None, session_id=None):
  148. """The receipt-only fields of a classic CLI turn, taken from the agent's raw result.
  149. ``pending_steer`` is REMOVED from ``result``: main's CLI queues a leftover /steer as its own
  150. next turn (``delivering leftover steer``), so the gateway must not also run it as a follow-up
  151. inside this admission. ``final_response`` is the agent's raw text: main renders its own
  152. ``chat_error_copy`` for an empty failed turn instead of the gateway's chat copy."""
  153. if not isinstance(result, dict):
  154. return {}
  155. fields = {key: result.get(key) for key in _RESULT_PASSTHROUGH if key in result}
  156. fields['final_response'] = result.get('final_response') or ''
  157. steer = result.pop('pending_steer', None)
  158. fields['pending_steer'] = steer or None
  159. if aux_before is not None:
  160. from hermes_cli.oneshot import _attach_auxiliary_usage
  161. holder = {'session_id': result.get('session_id') or session_id}
  162. _attach_auxiliary_usage(holder, session_db, aux_before, fallback_session_id=session_id)
  163. fields['auxiliary_usage'] = holder.get('auxiliary_usage') or {}
  164. return fields
  165. def one_turn_route(turn, policy, model, runtime_kwargs):
  166. """The executing admission's ``model_override`` applied to the resolved route (unchanged without one)."""
  167. override = cli_turn(turn._ctx.inbound_message_id).get('model_override')
  168. if not override:
  169. return model, runtime_kwargs
  170. from gateway.session_authorities import active_authority
  171. config = policy.config(active_authority(turn._runner)) if policy else turn._ctx.user_config
  172. return one_turn_runtime(override, model, runtime_kwargs, config)
  173. def one_turn_reasoning(turn, reasoning_config):
  174. """The executing admission's one-turn reasoning level (``model_override.reasoning``), else
  175. *reasoning_config* (the session's)."""
  176. override = cli_turn(turn._ctx.inbound_message_id).get('model_override') or {}
  177. if 'reasoning' not in override:
  178. return reasoning_config
  179. from hermes_constants import parse_reasoning_effort
  180. return parse_reasoning_effort(override['reasoning']) or reasoning_config
  181. def run_classic_cli_turn(turn, run):
  182. """``run()`` (the turn's run_conversation) for any turn; on a classic CLI turn the receipt-only
  183. fields are taken from its raw result and kept on ``turn`` for the committed receipt."""
  184. if not classic_cli_turn(turn):
  185. return run()
  186. from gateway.session_finite import finite_turn_required
  187. aux_before = cli_db = None
  188. if finite_turn_required() is True:
  189. # `chat -q --usage-file` / stream-json: this turn's auxiliary spend, as oneshot.py read it.
  190. from hermes_cli.oneshot import _auxiliary_usage
  191. runner_db = turn._runner._session_db
  192. cli_db = getattr(runner_db, "_db", runner_db)
  193. aux_before = _auxiliary_usage(cli_db, turn._ctx.session_id)
  194. result = run()
  195. turn._cli_result_fields = take_cli_result_fields(
  196. result, aux_before=aux_before, session_db=cli_db, session_id=turn._ctx.session_id)
  197. return result