session_worker_construct.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253
  1. """Agent-construction inputs the owner resolves for a managed worker (``construct_v1``).
  2. The in-process turn passes these to ``AIAgent`` from the owner's runner state; a fresh worker
  3. cannot reconstruct them (its config readers serve the frozen session snapshot, and a bypass
  4. worker must never reload the profile), so the owner resolves them per turn, mode-appropriately,
  5. and they ride the hydrated request beside ``turn_v1``. The child validates the closed shape.
  6. """
  7. import json
  8. from pathlib import Path
  9. KEYS = frozenset({'fallback_model', 'ephemeral_system_prompt', 'prefill_messages'})
  10. def construct_inputs(authority, policy, chat_id):
  11. """Owner side, per turn (off the owner loop: config reads)."""
  12. from gateway.session_authorities import owner_scope
  13. with owner_scope(authority):
  14. return {'fallback_model': _fallback_chain(authority, policy),
  15. 'ephemeral_system_prompt': _ephemeral_prompt(authority, policy, chat_id),
  16. 'prefill_messages': session_prefill(authority, policy, chat_id)}
  17. def _fallback_chain(authority, policy):
  18. """The chain ``_build_fresh_agent`` gives an in-process turn. Ordinary sessions keep the
  19. profile refresh semantics (re-read per turn, last-known-good per home); a config-only session
  20. takes its frozen explicit snapshot (never the profile); safe mode carries none."""
  21. if policy.safe_mode:
  22. return None
  23. if policy.ignore_user_config:
  24. from hermes_cli.fallback_config import get_fallback_chain
  25. return get_fallback_chain(policy.config(authority)) or None
  26. refresh = getattr(authority.runner, '_refresh_fallback_model', None)
  27. return refresh() if refresh is not None else None
  28. def _ephemeral_prompt(authority, policy, chat_id):
  29. """``TurnRunner``'s combined ephemeral prompt for a LOCAL turn (no platform context block):
  30. the gateway prompt (``agent.system_prompt`` / ``display.personality`` / channel override) plus
  31. the frozen ``-s`` skills blocks. API-time only, never part of the persisted system prefix.
  32. A bypass session never reads the profile: only its frozen launch additions apply."""
  33. configured = None
  34. resolve = getattr(authority.runner, '_get_system_prompt_for_channel', None)
  35. if not policy.ignore_user_config and resolve is not None:
  36. from gateway.config import Platform
  37. with policy.client_env_scope():
  38. configured = resolve(Platform.LOCAL, chat_id or '')
  39. return '\n\n'.join(p for p in (configured, policy.skills_prompt) if p) or None
  40. def session_routing(authority, policy):
  41. """The session's ``provider_routing``: its own profile's, as of its creation (main's CLI read it
  42. once at startup). Never the runner's daemon-start copy."""
  43. routing = policy.config(authority, secrets=False).get('provider_routing')
  44. return routing if isinstance(routing, dict) else {}
  45. def session_prefill(authority, policy, session_id):
  46. """The session's prefill examples, for the in-process turn and a managed worker alike: the
  47. snapshot ``stage_session_prefill`` took when the session was created (main's CLI read the file
  48. once at startup). A session this owner did not create (restored after a restart, a branch)
  49. reads it on first use and keeps that. A bypass session never loads it."""
  50. if policy.ignore_user_config:
  51. return None
  52. held = _held_prefill(authority)
  53. if session_id not in held:
  54. held.setdefault(session_id, (_read_prefill(authority, policy),))
  55. return held[session_id][0]
  56. class StagedReceipt(dict):
  57. """A creation receipt plus owner memory ``commit_local_session`` publishes only from the
  58. transaction that creates the session (never persisted: the receipt itself is the dict)."""
  59. on_create: '_PrefillPublication | None' = None
  60. # The request's own ``client_env`` (stage_local_session), for an overlapping create's retry check.
  61. client_request: 'dict | None' = None
  62. class _PrefillPublication:
  63. def __init__(self, authority, policy, session_id):
  64. # A box per attempt: ownership is identity, even when two attempts read the same contents.
  65. self.authority, self.policy, self.session_id, self.box = authority, policy, session_id, None
  66. def read(self):
  67. """This attempt's snapshot, read by its commit before the transaction (off the owner loop)."""
  68. self.box = (_read_prefill(self.authority, self.policy),)
  69. def publish(self):
  70. _held_prefill(self.authority)[self.session_id] = self.box
  71. def withdraw(self):
  72. held = _held_prefill(self.authority)
  73. if held.get(self.session_id) is self.box:
  74. held.pop(self.session_id, None)
  75. def stage_session_prefill(authority, policy, receipt):
  76. """Stage a new session's prefill snapshot: the ``prefill_messages_file`` of its config, relative
  77. to its own profile home, read by this attempt's commit (``commit_local_session``, which the async
  78. creates run in ``tracked_write``'s worker thread), never on the owner loop. The snapshot is held
  79. in the authority's memory only if this attempt's commit creates the session: an overlapping
  80. retry or conflicting create never replaces the winner's, and a refused or failed create leaves
  81. nothing. Never evicted by other sessions; ``release_session_prefill`` drops it with the session."""
  82. staged = StagedReceipt(receipt)
  83. if not policy.ignore_user_config:
  84. staged.on_create = _PrefillPublication(authority, policy, receipt['session_id'])
  85. return staged
  86. def release_session_prefill(authority, session_ids):
  87. held = getattr(authority, '_local_prefill', None) or {}
  88. for sid in session_ids:
  89. held.pop(str(sid), None)
  90. def _held_prefill(authority):
  91. held = getattr(authority, '_local_prefill', None)
  92. if held is None:
  93. held = authority._local_prefill = {}
  94. return held
  95. def _read_prefill(authority, policy):
  96. from hermes_cli.cli_config_load import _load_prefill_messages, _resolve_prefill_messages_file
  97. home = Path(str(authority.profile_id))
  98. if not home.is_absolute():
  99. from hermes_constants import get_hermes_home
  100. home = get_hermes_home()
  101. with policy.client_env_scope(): # HERMES_PREFILL_MESSAGES_FILE: a local session's client's
  102. path = _resolve_prefill_messages_file(policy.config(authority, secrets=False))
  103. return _load_prefill_messages(path, home) or None
  104. def construct_kwargs(frame):
  105. """Child side: the validated ``AIAgent`` keyword arguments; a frame without the object
  106. (older owner) constructs exactly as before."""
  107. inputs = json.loads(frame['policy'].get('request_json') or '{}').get('construct_v1')
  108. if inputs is None:
  109. return {}
  110. if (not isinstance(inputs, dict) or set(inputs) != KEYS
  111. or not _dict_list(inputs['fallback_model']) or not _dict_list(inputs['prefill_messages'])
  112. or not isinstance(inputs['ephemeral_system_prompt'], (str, type(None)))):
  113. raise ValueError('invalid_managed_worker_bootstrap')
  114. return dict(inputs)
  115. def _dict_list(value):
  116. return value is None or (isinstance(value, list) and all(isinstance(e, dict) for e in value))
  117. def route_runtime(policy, frozen, model, key, *, fallback=True):
  118. """``(runtime, fallback_entry)`` for a launch-policy route: the session's FROZEN config and launch
  119. credential, walking its own fallback chain on an AuthError unless ``fallback=False`` (a session
  120. control asking which route the session itself runs). The one resolver an in-process turn
  121. (``_resolve_policy_agent_runtime``) and a managed worker (``worker_route``) share."""
  122. from hermes_cli.runtime_provider import (
  123. frozen_runtime_config, resolve_runtime_provider, resolve_runtime_with_fallback,
  124. )
  125. from hermes_cli.runtime_provider_custom import _resolve_named_custom_runtime
  126. provider = (frozen.get('model') or {}).get('provider')
  127. launch_url = json.loads(policy.request_json).get('base_url')
  128. if launch_url:
  129. # The creation request is immutable identity, not the current selection: once a canonical
  130. # model mutation moved the route off the launch endpoint, the policy's selection wins.
  131. from hermes_cli.route_identity import normalize_route_base_url
  132. if normalize_route_base_url(launch_url) != normalize_route_base_url((frozen.get('model') or {}).get('base_url')):
  133. launch_url = None
  134. # Every rung reads the session's FROZEN config, never live config.yaml: a later
  135. # ``model.base_url`` edit must not carry this route's frozen credential to the new host
  136. # (R2-M2). The auth-store pool is not config, so refresh/rotation still applies.
  137. with frozen_runtime_config(frozen):
  138. runtime = _resolve_named_custom_runtime(requested_provider=provider,
  139. explicit_api_key=key, explicit_base_url=launch_url,
  140. target_model=model, config=frozen)
  141. if runtime is not None:
  142. return runtime, None
  143. # Only a bound launch key is explicit: the frozen ``model.api_key`` is config, which the
  144. # resolver already reads from the frozen scope, so a URL-matched credential pool still
  145. # serves (and rotates on) the frozen endpoint.
  146. # Same resolution-time walker the in-process one-shot used (#81209): an AuthError
  147. # from the frozen primary (expired token, Portal down, exhausted pool) tries the
  148. # route's own ``fallback_providers`` before the turn is refused. Only a launch URL is
  149. # explicit (classic one-shot parity): the frozen ``model.base_url`` is resolved by
  150. # the provider chain, which keeps the credential pool an explicit URL would drop.
  151. if not fallback:
  152. # Takes no config argument: it reads `frozen` only through the frozen_runtime_config scope above, so it must stay inside that `with`.
  153. return resolve_runtime_provider(requested=provider, target_model=model,
  154. explicit_base_url=launch_url, explicit_api_key=key), None
  155. return resolve_runtime_with_fallback(frozen, requested=provider,
  156. explicit_api_key=key, explicit_base_url=launch_url, target_model=model)
  157. def worker_route(policy, construct):
  158. """Child side: the ``api_key`` / ``base_url`` / ``api_mode`` overrides for the worker's agent, resolved
  159. as the in-process turn resolves its route (``route_runtime`` with the launch key, if one was bound),
  160. from this process's profile home (its HERMES_HOME and ``.env``). The frozen ``model.base_url`` alone
  161. is not the route: a per-model api_mode (opencode-go Responses models) and a resolved endpoint
  162. (Bedrock's regional URL) come only from resolution. A fallback entry's route belongs to another
  163. provider and model, so the primary never carries it; the agent's own fallback chain switches them
  164. together (#139155).
  165. A primary AuthError walks the chain the agent will actually get: the owner's per-turn
  166. ``construct_v1`` chain (an ordinary session's refreshed profile fallbacks) when it was sent,
  167. the frozen snapshot's otherwise (older owner)."""
  168. frozen, model = policy.effective()
  169. if 'fallback_model' in construct:
  170. frozen = {**frozen, 'fallback_providers': construct['fallback_model'] or [], 'fallback_model': None}
  171. runtime, fallback_entry = route_runtime(policy, frozen, model, construct['api_key'])
  172. if fallback_entry is not None:
  173. return {}
  174. api_mode = runtime.get('api_mode')
  175. # A built-in provider's chat_completions is the resolver's default unless model.api_mode set it: None
  176. # leaves the agent's model-aware upgrade (GPT-5 on OpenRouter to Responses). A custom route's mode
  177. # is its endpoint's own (providers.<name>/custom_providers[] or URL-detected), which the in-process
  178. # turn's ``custom`` provider never upgrades; the worker's ``custom:<name>`` would.
  179. if (api_mode == 'chat_completions' and runtime.get('provider') != 'custom'
  180. and not (frozen.get('model') or {}).get('api_mode')):
  181. api_mode = None
  182. return {'api_key': construct['api_key'] or runtime.get('api_key'), 'base_url': runtime.get('base_url'),
  183. 'api_mode': api_mode}
  184. def checkpoint_agent_kwargs(config):
  185. """``AIAgent`` checkpoint arguments from a config dict (every turn: the gateway's live config, a
  186. managed worker's frozen session snapshot). The gateway bypasses ``load_config()``, so defaults
  187. are here; legacy ``checkpoints: true`` works."""
  188. cp_cfg = config.get("checkpoints", {}) if isinstance(config, dict) else {}
  189. if isinstance(cp_cfg, bool):
  190. cp_cfg = {"enabled": cp_cfg}
  191. elif not isinstance(cp_cfg, dict):
  192. cp_cfg = {}
  193. from hermes_cli.config import DEFAULT_CONFIG
  194. defaults = DEFAULT_CONFIG["checkpoints"]
  195. return {
  196. "checkpoints_enabled": cp_cfg.get("enabled", defaults["enabled"]),
  197. "checkpoint_max_snapshots": cp_cfg.get("max_snapshots", defaults["max_snapshots"]),
  198. "checkpoint_max_total_size_mb": cp_cfg.get("max_total_size_mb", defaults["max_total_size_mb"]),
  199. "checkpoint_max_file_size_mb": cp_cfg.get("max_file_size_mb", defaults["max_file_size_mb"])}
  200. def routing_agent_kwargs(config, model, provider, base_url):
  201. """The provider-routing ``AIAgent`` arguments every in-process surface passes (the CLI's
  202. ``provider_routing`` / ``openrouter.min_coding_score`` / ``agent.service_tier``, a static fast
  203. tier's request overrides), from a managed worker's frozen session config."""
  204. from agent.fast_mode import STATIC_TIERS, parse_service_tier
  205. from hermes_cli.models import resolve_fast_mode_overrides
  206. pr = config.get('provider_routing') or {}
  207. score = (config.get('openrouter') or {}).get('min_coding_score')
  208. tier = parse_service_tier((config.get('agent') or {}).get('service_tier', ''))
  209. overrides = resolve_fast_mode_overrides(model, provider=provider, base_url=base_url, tier=tier) if tier in STATIC_TIERS else None
  210. return {'providers_allowed': pr.get('only'), 'providers_ignored': pr.get('ignore'), 'providers_order': pr.get('order'),
  211. 'provider_sort': pr.get('sort'), 'provider_require_parameters': pr.get('require_parameters', False),
  212. 'provider_data_collection': pr.get('data_collection'), 'service_tier': tier, 'request_overrides': overrides,
  213. 'openrouter_min_coding_score': score if isinstance(score, (int, float)) and 0 <= score <= 1 else None}