session_api_turn.py 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570
  1. """Trusted API preparation and observation of the canonical durable FIFO."""
  2. import asyncio
  3. from contextvars import ContextVar
  4. from contextlib import contextmanager
  5. from functools import partial
  6. import hmac
  7. import json
  8. import re
  9. import uuid
  10. from gateway.config import Platform
  11. from gateway.session_api import bind_api_steps, restore_api_session, run_steps, run_steps_off_loop
  12. from gateway.session_results import admission_result
  13. from hermes_state_runtime import RuntimeStoreError, admit_session_input, _json
  14. api_execution: ContextVar[dict | None] = ContextVar('api_execution', default=None)
  15. _SETTINGS_PREFIX = 'gateway.api.settings.v1.'
  16. # Request-owned sinks an API observer may register for its admission's execution.
  17. _OBSERVER_KEYS = ('stream_delta_callback', 'tool_start_callback', 'tool_complete_callback',
  18. 'reasoning_callback', 'status_callback', 'interim_assistant_callback')
  19. _TOOL_SINKS = {'tool_start_callback', 'tool_complete_callback'}
  20. _SETTING_KEYS = ('ephemeral_system_prompt', 'requested_model', 'requested_provider',
  21. 'model_options', 'route', 'session_model', 'confirmed_runtime_lock',
  22. 'requested_runtime', 'route_source', 'room_dispatch', 'room_execution_policy',
  23. 'session_history_delivery')
  24. _OWNER_SCOPE_RE = re.compile(r'[0-9a-f]{64}')
  25. class AdmissionQueued(RuntimeStoreError):
  26. """The owner retired while this API admission was still queued. Unlike a refused request, the
  27. input is committed: the row stays queued and the next owner runs it exactly once, so a client
  28. that resends it submits the work twice. ``str()`` is the message every API surface shows."""
  29. MESSAGE = 'Hermes is restarting. Your input is saved and will run once when it is back; do not resend it.'
  30. def __init__(self):
  31. super().__init__('admission_queued')
  32. self.args = (self.MESSAGE,)
  33. def api_settings(authority, ref):
  34. with authority.db._read_ctx() as conn:
  35. saved = conn.execute('SELECT value FROM state_meta WHERE key=?',
  36. (_SETTINGS_PREFIX + ref.session_id,)).fetchone()
  37. return json.loads(saved[0]) if saved else {}
  38. def check_api_turn(authority, ref, payload):
  39. live = authority.sessions[ref.session_id]
  40. if live.source.platform == Platform.API_SERVER:
  41. restore_api_session(authority, ref.session_id)
  42. adapter = authority.runner._adapter_for_source(live.source)
  43. if adapter is None or getattr(adapter, 'gateway_runner', None) is not authority.runner:
  44. raise RuntimeStoreError('runtime_draining')
  45. if 'api_turn_v1' in payload:
  46. data = payload['api_turn_v1']
  47. # 'browser_control' is accepted and ignored: admissions persisted while the removed
  48. # browser-extension control existed may carry it and must still recover.
  49. if (set(data) - {'history', 'settings', 'turn_author', 'media', 'run_owner_scope', 'browser_control',
  50. 'relay_metadata', 'resume_unanswered'}
  51. or data.get('resume_unanswered', True) is not True
  52. or not {'history', 'settings'} <= set(data)
  53. or not isinstance(data.get('relay_metadata', {}), dict)
  54. or (data['history'] is not None and not isinstance(data['history'], list))
  55. or ('run_owner_scope' in data and not _valid_owner_scope(data['run_owner_scope']))):
  56. raise RuntimeStoreError('invalid_params')
  57. if set(data['settings']) - set(_SETTING_KEYS):
  58. raise RuntimeStoreError('invalid_params')
  59. settings = payload.get('api_turn_v1', {}).get('settings') or api_settings(authority, ref)
  60. check_api_settings(adapter, settings)
  61. return adapter
  62. def _valid_owner_scope(value):
  63. return isinstance(value, str) and _OWNER_SCOPE_RE.fullmatch(value) is not None
  64. def api_session_vars():
  65. """Session-context fields an executing API admission binds beyond the shared source:
  66. #98619 history-delivery provenance. ``{}`` when no API admission is executing."""
  67. current = api_execution.get()
  68. if current is None:
  69. return {}
  70. return {'session_history_delivery': current['settings'].get('session_history_delivery') or ''}
  71. def check_api_settings(adapter, settings):
  72. dispatch = settings.get('room_dispatch')
  73. # A room policy is only ever issued with the dispatch it was verified for; a policy-only
  74. # blob (e.g. queued by an older build) would otherwise widen the operator's API config.
  75. if dispatch is None and settings.get('room_execution_policy') is not None:
  76. raise RuntimeStoreError('permission_denied')
  77. if dispatch is not None:
  78. from gateway.hosted_room_peer import HostedMemberDispatch, GatewayRoomCatalog
  79. from gateway.platforms.api_server_room_grants import _local_room_catalog
  80. from gateway import hosted_rooms
  81. bound = HostedMemberDispatch.from_mapping(dispatch)
  82. if bound.target_install_id != hosted_rooms.local_authority_gateway_id():
  83. raise RuntimeStoreError('permission_denied')
  84. _, catalog = _local_room_catalog(adapter, bound.target_profile, bound.target_install_id)
  85. current = GatewayRoomCatalog.from_mapping(catalog)
  86. if (current.catalog_digest != bound.capability_digest
  87. or current.execution_policy.as_mapping() != settings.get('room_execution_policy')):
  88. raise RuntimeStoreError('permission_denied')
  89. return adapter
  90. @contextmanager
  91. def api_policy_scope():
  92. current = api_execution.get()
  93. policy = current['settings'].get('room_execution_policy') if current else None
  94. token = None
  95. if policy is not None:
  96. from gateway.hosted_room_execution_policy import RoomExecutionPolicy, bind_room_execution_policy
  97. token = bind_room_execution_policy(RoomExecutionPolicy.from_mapping(policy))
  98. try:
  99. yield
  100. finally:
  101. if token is not None:
  102. from gateway.hosted_room_execution_policy import reset_room_execution_policy
  103. reset_room_execution_policy(token)
  104. def admit_api_turn(adapter, **kwargs):
  105. """Admit inline (sync callers and tests); the HTTP doors use ``admit_api_turn_async``."""
  106. return run_steps(admit_api_steps(adapter, **kwargs))
  107. async def admit_api_turn_async(adapter, steps=None, **kwargs):
  108. """``admit_api_turn`` (or *steps*, a generator ending in ``admit_api_steps``) with every SQLite
  109. write off the owner loop, in admission order."""
  110. from gateway.session_authorities import require_active_authority
  111. authority = require_active_authority(adapter.gateway_runner)
  112. return await run_steps_off_loop(authority, steps or admit_api_steps(adapter, **kwargs), orphaned=schedule_orphan)
  113. def schedule_orphan(admitted):
  114. """A caller cancelled while its admission committed never observes it: its drain runs anyway."""
  115. authority, ref, row = admitted[:3]
  116. if row['status'] == 'queued':
  117. authority._schedule(ref)
  118. def admit_api_steps(adapter, **kwargs):
  119. # ``/p/<profile>/`` middleware scoped this request; the routed home's authority admits it.
  120. from gateway.session_authorities import require_active_authority
  121. authority = require_active_authority(adapter.gateway_runner, lambda: adapter._ensure_session_db())
  122. sid = kwargs.get('session_id') or uuid.uuid4().hex
  123. declared_key = kwargs.get('gateway_session_key') if kwargs.get('bind_declared_conversation') else None
  124. if declared_key:
  125. from gateway.session_api import declared_api_session
  126. sid = declared_api_session(authority.db, declared_key) or sid
  127. # Every API door (chat header, runs session_id, /api/sessions/{id}/chat, Responses chain) may
  128. # name a compression continuation; the binding, FIFO and retry identity live on its root.
  129. sid = authority.logical_owner(sid)
  130. authority._require_admission_open()
  131. settings = {key: kwargs.get(key) for key in _SETTING_KEYS}
  132. # Route credentials remain in the server's configuration, never admission JSON.
  133. route = settings.get('route')
  134. if route and route.get('api_key'):
  135. alias = settings.get('requested_model')
  136. configured = adapter._model_routes.get(alias)
  137. if configured != route:
  138. raise RuntimeStoreError('permission_denied')
  139. settings['route'] = {k: v for k, v in route.items() if k != 'api_key'}
  140. payload = json.loads(_json({'text': kwargs['user_message'], 'api_turn_v1': {
  141. 'history': None if kwargs.get('history_from_session') else kwargs['conversation_history'], 'settings': settings}}))
  142. run_owner_scope = kwargs.get('run_owner_scope')
  143. if run_owner_scope is not None:
  144. if not _valid_owner_scope(run_owner_scope):
  145. raise RuntimeStoreError('invalid_params')
  146. # This opaque namespace is persisted in the same row/transaction as
  147. # admission. It is never a bearer credential or execution input.
  148. payload['api_turn_v1']['run_owner_scope'] = run_owner_scope
  149. # Refuse a foreign-surface target before committing any media for it (a refused
  150. # admission otherwise retains its image bytes under native-inputs/ forever).
  151. existing = authority.db.get_session(sid)
  152. if existing is not None and existing['source'] not in ('api_server', 'bot_room'):
  153. raise RuntimeStoreError('permission_denied')
  154. if kwargs.get('turn_author') is not None:
  155. from agent.turn_author import parse_turn_author
  156. author = parse_turn_author(kwargs['turn_author'])
  157. if author is None:
  158. raise RuntimeStoreError('invalid_params')
  159. payload['api_turn_v1']['turn_author'] = author
  160. if kwargs.get('resume_unanswered_turn'):
  161. # The session-chat door's one policy-gated re-run (#115325): its failed attempt left this text as
  162. # the transcript's unanswered tail, which the turn adopts instead of appending it again.
  163. payload['api_turn_v1']['resume_unanswered'] = True
  164. if kwargs.get('relay_metadata'):
  165. # The request's Relay metadata rides the admission to the turn it describes (main passed it
  166. # to ``run_conversation``); it is client JSON, so it is part of the exact-retry identity.
  167. payload['api_turn_v1']['relay_metadata'] = kwargs['relay_metadata']
  168. request_id = kwargs.get('request_id') or kwargs.get('active_run_id') or uuid.uuid4().hex
  169. if not isinstance(kwargs['user_message'], list):
  170. return (yield from _admit_api_payload(authority, adapter, sid, request_id, payload, settings, declared_key, kwargs))
  171. from gateway.session_api_media import commit_api_images
  172. from gateway.session_ingress_media import capture_lease, drop_capture_lease, release_unheld_media
  173. # Content-addressed bytes another admission may name are held from capture until this one
  174. # commits or is refused: a concurrent release would otherwise unlink them in between.
  175. with capture_lease():
  176. payload['api_turn_v1']['media'] = commit_api_images(kwargs['user_message'])
  177. # Retained bytes belong to an accepted admission. A refused request (or an exact retry of a
  178. # retired one, whose references were erased) owns nothing, so its bytes are collected unless
  179. # another admission holds them.
  180. release = partial(release_unheld_media, authority.db, payload['api_turn_v1']['media'])
  181. try:
  182. admitted = yield from _admit_api_payload(authority, adapter, sid, request_id, payload, settings, declared_key, kwargs)
  183. except Exception:
  184. drop_capture_lease()
  185. yield release
  186. raise
  187. yield release
  188. return admitted
  189. def _admit_api_payload(authority, adapter, sid, request_id, payload, settings, declared_key, kwargs):
  190. from hermes_state_terminal import retry_terminal_admission
  191. row = retry_terminal_admission(authority.db, epoch=authority.epoch, principal_id='api',
  192. session_id=sid, request_id=request_id, payload=payload)
  193. if row is not None:
  194. check_api_settings(adapter, settings)
  195. from gateway.session_contract import SessionRef
  196. return authority, SessionRef(authority.profile_id, sid), row
  197. ref = yield from bind_api_steps(authority, sid, hosted_dispatch=kwargs.get("room_dispatch"), declared_key=declared_key,
  198. caller_key=kwargs.get('gateway_session_key'), walked_from=kwargs.get('walked_from'))
  199. check_api_turn(authority, ref, payload)
  200. row = yield partial(admit_session_input, authority.db, epoch=authority.epoch, principal_id='api',
  201. session_id=sid, request_id=request_id, payload=payload,
  202. _authorize_write=authority._admission_gate(partial(
  203. _admit_target, sid, request_id, payload['api_turn_v1']['settings'],
  204. client_key=bool(kwargs.get('request_id')))))
  205. return authority, ref, row
  206. def _admit_target(session_id, request_id, settings, conn, *, client_key=True):
  207. """Inside the admission's own off-loop transaction: one target per request id, and the
  208. session's settings for its later payload-less (internal) turns, committed with the admitted
  209. turn rather than by the drain on the owner loop (N50)."""
  210. _one_target(session_id, request_id, conn, client_key=client_key)
  211. conn.execute('INSERT INTO state_meta(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value',
  212. (_SETTINGS_PREFIX + session_id, _json(settings)))
  213. def _one_target(session_id, request_id, conn, *, client_key=True):
  214. """One API request id (an Idempotency-Key) names one admission. The ledger keys identity by
  215. target too, so the same key aimed at another session would otherwise run the work again.
  216. A deleted session's admission is gone from the ledger but its tombstone still spends the key
  217. (a target that already holds the key replays before this guard runs). Only a client key can
  218. name a tombstone: a server-minted id (key-less turn, run id) is fresh, so it skips that scan."""
  219. if conn.execute("SELECT 1 FROM session_admissions WHERE principal_id='api' AND request_id=? "
  220. 'AND target_session_id!=? LIMIT 1', (request_id, session_id)).fetchone():
  221. raise RuntimeStoreError('admission_conflict')
  222. if not client_key:
  223. return
  224. from hermes_state_terminal import terminal_api_admissions
  225. if any(row['target_session_id'] != session_id for row in terminal_api_admissions(conn, request_id)):
  226. raise RuntimeStoreError('admission_conflict')
  227. def owns_api_run(adapter, run_id, owner_scope):
  228. """Match a caller scope against one canonical API admission, failing closed."""
  229. if not _valid_owner_scope(owner_scope):
  230. return False
  231. from gateway.platforms.api_server_authority_runs import run_admission
  232. try:
  233. owned = run_admission(adapter, run_id)
  234. except RuntimeStoreError:
  235. # Duplicate admissions for one run are an unanswered ownership question.
  236. return False
  237. if owned is None:
  238. return False
  239. try:
  240. stored = owned[1]['payload']['api_turn_v1']['run_owner_scope']
  241. except (KeyError, TypeError):
  242. return False
  243. return _valid_owner_scope(stored) and hmac.compare_digest(stored, owner_scope)
  244. def recover_api_turns(adapter):
  245. """Recover committed work only after the real API adapter is published. A parked profile's
  246. retained (retiring) authority is not served: its store is never read here."""
  247. from gateway.session_authorities import owner_scope, serving_authorities
  248. for authority in serving_authorities(adapter.gateway_runner):
  249. # Startup is unscoped (the launch profile's home): each profile's media root, config and
  250. # API bindings must pair with its own state.db, never the launch profile's.
  251. with owner_scope(authority):
  252. recover_authority_api_turns(adapter, authority)
  253. def recover_authority_api_turns(adapter, authority):
  254. from hermes_state_runtime import list_session_admissions
  255. from gateway.session_ingress_media import collect_unheld_api_images
  256. import logging
  257. collect_unheld_api_images(authority.db)
  258. from gateway.session_api_media import compact_settled_api_payloads
  259. compact_settled_api_payloads(authority.db)
  260. with authority.db._read_ctx() as conn:
  261. targets = [row[0] for row in conn.execute(
  262. "SELECT DISTINCT target_session_id FROM session_admissions WHERE principal_id='api' AND status='queued'")]
  263. for sid in targets:
  264. try:
  265. ref = restore_api_session(authority, sid)
  266. pending = list_session_admissions(authority.db, session_id=sid)
  267. if any(row['status'] == 'unknown' for row in pending):
  268. continue
  269. for row in pending:
  270. if row['status'] == 'queued':
  271. check_api_turn(authority, ref, row['payload'])
  272. authority._schedule(ref)
  273. except RuntimeStoreError as exc:
  274. logging.getLogger(__name__).warning('API session %s paused: %s', sid, exc.reason)
  275. async def run_api_turn(adapter, *, approval_notify_callback=None, approval_session_key=None, **kwargs):
  276. admitted = await admit_api_turn_async(adapter, **kwargs)
  277. if approval_notify_callback is None or not approval_session_key:
  278. return await observe_api_turn(admitted, **kwargs)
  279. # A streaming surface advertises its own run id (``chatcmpl-*`` / ``run_*``): bind it to this
  280. # exact admission so ``/v1/runs/{id}/approval`` answers the shared, generation-fenced prompt,
  281. # and hand that prompt to the stream's notifier in the event shape it already emits.
  282. aliases = adapter._run_admission_aliases
  283. aliases[approval_session_key] = admitted[2]['admission_id']
  284. def sink(event_type, prompt):
  285. if event_type == 'approval.request':
  286. choices = prompt.get('choices') or ()
  287. approval_notify_callback({
  288. **{k: v for k, v in prompt.items() if k not in ('kind', 'prompt_id', 'choices')},
  289. 'request_id': prompt['prompt_id'], 'allow_session': 'session' in choices,
  290. 'allow_permanent': 'always' in choices})
  291. try:
  292. with observe_api_controls(admitted, sink):
  293. return await observe_api_turn(admitted, **kwargs)
  294. finally:
  295. if aliases.get(approval_session_key) == admitted[2]['admission_id']:
  296. aliases.pop(approval_session_key)
  297. async def observe_api_turn(admitted, **kwargs):
  298. authority, ref, row = admitted
  299. from hermes_state_runtime import get_session_admission
  300. # The admission-time snapshot is stale once a drain already running ahead claims and settles
  301. # (or a stop cancels) the row; a waiter registered after that is never resolved. The current
  302. # row decides, read with no suspension before the waiter is registered.
  303. status = (get_session_admission(authority.db, admission_id=row['admission_id']) or row)['status']
  304. if status == 'unknown':
  305. raise RuntimeStoreError('unknown_execution')
  306. if status == 'terminal':
  307. result, usage = _settled_api_result(authority, row['admission_id'])
  308. callback = kwargs.get('stream_delta_callback')
  309. if callback:
  310. callback(result.get('final_response') or '')
  311. return result, usage
  312. waiter = authority.waiters.setdefault(row['admission_id'], asyncio.get_running_loop().create_future())
  313. observers = getattr(authority, 'api_observers', None)
  314. if observers is None:
  315. observers = authority.api_observers = {}
  316. observer = {key: kwargs[key] for key in _OBSERVER_KEYS if kwargs.get(key) is not None}
  317. if kwargs.get('tool_progress_callback') is not None and not observer.keys() & _TOOL_SINKS:
  318. # Progress-only (the session chat stream): the producer's own tool.started / tool.completed
  319. # events with its preview and failure verdict. Structured observers keep only theirs.
  320. observer['tool_progress_callback'] = kwargs['tool_progress_callback']
  321. registered = observers.setdefault(row['admission_id'], [])
  322. registered.append(observer)
  323. try:
  324. authority._publish_pending(ref)
  325. authority._schedule(ref)
  326. await asyncio.shield(waiter)
  327. except RuntimeStoreError as exc:
  328. # Retirement releases every observer with runtime_draining, the same reason a refused
  329. # request gets. This one's input is admitted: say so while the row is still queued.
  330. current = get_session_admission(authority.db, admission_id=row['admission_id']) or {}
  331. if exc.reason == 'runtime_draining' and current.get('status') == 'queued':
  332. raise AdmissionQueued() from exc
  333. raise
  334. finally:
  335. # Shielding keeps the canonical turn alive past a cancelled request; only this
  336. # request's observer leaves, and the entry itself goes once the last one is gone.
  337. registered.remove(observer)
  338. if not registered:
  339. observers.pop(row['admission_id'], None)
  340. return _settled_api_result(authority, row['admission_id'])
  341. def _settled_api_result(authority, admission_id):
  342. saved = admission_result(authority.db, admission_id)
  343. if saved is None:
  344. from hermes_state_runtime import get_session_admission
  345. current = get_session_admission(authority.db, admission_id=admission_id)
  346. if current['outcome'] == 'cancelled':
  347. return {'final_response': '', 'interrupted': True, 'completed': False}, {}
  348. raise RuntimeStoreError('unknown_execution')
  349. return saved['result'], saved['usage']
  350. _CONTROL_EVENTS = frozenset({'approval.request', 'approval.settled', 'clarify.request', 'clarify.settled'})
  351. @contextmanager
  352. def observe_api_controls(admitted, sink):
  353. """Project the same approval/clarify prompts WS viewers receive to ``sink(type, payload)``
  354. for the admission's lifetime; ``sink`` runs under the stream lock.
  355. An exact retry joins an admission whose prompt may already be pending: it was published
  356. before this observer existed, so it is replayed from the shared pending controls (the
  357. source ``GET /v1/runs/{id}`` reports). Subscribing and snapshotting in ONE stream-lock hold
  358. is the consistent cut: prompts are registered and answered under that lock, so each one is
  359. either in the snapshot or arrives live (never both), and one already answered is absent."""
  360. from hermes_state_runtime import get_session_admission
  361. authority, ref, row = admitted
  362. from gateway.session_retirement import restore_retired
  363. restore_retired(authority, ref.session_id) # idle between its bind and this admission's commit
  364. live = authority.sessions.get(ref.session_id)
  365. if live is None:
  366. # Deleted or pruned: only an exact retry of a settled (retired) receipt reaches here,
  367. # and a settled admission has no prompts left to project.
  368. yield
  369. return
  370. events = live.event_stream
  371. def observer(frame):
  372. params = frame['params']
  373. if params.get('admission_id') == row['admission_id'] and params.get('type') in _CONTROL_EVENTS:
  374. sink(params['type'], params.get('payload') or {})
  375. with events.lock:
  376. events.observers.add(observer)
  377. current = get_session_admission(authority.db, admission_id=row['admission_id']) or row
  378. if current['status'] == 'started':
  379. for prompt in live.controls.snapshot(ref.session_id, current['generation']):
  380. sink(prompt['kind'] + '.request', prompt)
  381. try:
  382. yield
  383. finally:
  384. with events.lock:
  385. events.observers.discard(observer)
  386. def prepare_api_execution(authority, ref, payload):
  387. adapter = check_api_turn(authority, ref, payload)
  388. data = payload.get('api_turn_v1')
  389. settings = data['settings'] if data else api_settings(authority, ref)
  390. content = payload['text']
  391. if data and isinstance(content, list):
  392. from gateway.session_api_media import restore_api_images
  393. content = restore_api_images(content, data.get('media') or [])
  394. return {'adapter': adapter, 'settings': settings, 'history': data['history'] if data else None,
  395. 'content': content, 'turn_author': data.get('turn_author') if data else None,
  396. 'relay_metadata': data.get('relay_metadata') if data else None,
  397. 'resume_unanswered': bool(data and data.get('resume_unanswered'))}
  398. def _api_observers(authority, session_id):
  399. execution = authority.sessions[session_id].event_stream.execution
  400. admission_id = execution.get('admission_id') if execution else None
  401. return tuple(getattr(authority, 'api_observers', {}).get(admission_id, ()))
  402. def _notify_observers(authority, session_id, key, *args, **kwargs):
  403. """Observer callbacks are request-owned sinks; one that raises (closed socket, torn-down
  404. loop) must not abort canonical execution or starve the other observers. Returns whether
  405. any observer accepted the event."""
  406. import logging
  407. accepted = False
  408. for observer in _api_observers(authority, session_id):
  409. callback = observer.get(key)
  410. if callback:
  411. try:
  412. callback(*args, **kwargs)
  413. accepted = True
  414. except Exception:
  415. logging.getLogger(__name__).warning('API observer %s failed for %s', key, session_id, exc_info=True)
  416. return accepted
  417. def wire_api_observers(agent, owner, want_interim):
  418. """Hand this admission's API observers (Chat/Responses SSE, runs) the agent's reasoning,
  419. status, commentary and tool progress callbacks, the ones the direct API path gave the agent
  420. itself. Each event is fenced to the exact running claim, so a settled worker's late callback is inert;
  421. the turn's own status/commentary sinks keep running after the observers."""
  422. authority, session_id, generation = owner
  423. def publish(key, *args, **kwargs):
  424. with authority.sessions[session_id].event_stream.lock:
  425. try:
  426. authority.check_approval_generation(session_id, generation)
  427. except RuntimeStoreError:
  428. return False
  429. return _notify_observers(authority, session_id, key, *args, **kwargs)
  430. status, interim = agent.status_callback, agent.interim_assistant_callback
  431. def status_callback(kind, message=None):
  432. publish('status_callback', kind, message)
  433. if status is not None:
  434. status(kind, message)
  435. def interim_assistant_callback(text, *, already_streamed=False):
  436. publish('interim_assistant_callback', text, already_streamed=already_streamed)
  437. if interim is not None:
  438. interim(text, already_streamed=already_streamed)
  439. progress = agent.tool_progress_callback
  440. def tool_progress_callback(event_type, *args, **kwargs):
  441. if event_type in ('tool.started', 'tool.completed'):
  442. publish_api_tool_progress(authority, session_id, generation, event_type, *args, **kwargs)
  443. if progress is not None:
  444. return progress(event_type, *args, **kwargs)
  445. agent.reasoning_callback = lambda text: publish('reasoning_callback', text)
  446. agent.status_callback = status_callback
  447. agent.tool_progress_callback = tool_progress_callback
  448. if want_interim:
  449. agent.interim_assistant_callback = interim_assistant_callback
  450. def publish_api_event(authority, session_id, event_type, payload):
  451. if event_type == 'message.delta' and payload['text'] is not None: # a None segment boundary is viewer-only
  452. return _notify_observers(authority, session_id, 'stream_delta_callback', payload['text'])
  453. return False
  454. def publish_api_tool_progress(authority, session_id, generation, *args, **kwargs):
  455. """A ``tool_progress_callback`` tool event as its producer emitted it, for the admission's
  456. progress-only observers; never inferred again from formatted or bounded result text."""
  457. with authority.sessions[session_id].event_stream.lock:
  458. try:
  459. authority.check_approval_generation(session_id, generation)
  460. except RuntimeStoreError:
  461. return
  462. _notify_observers(authority, session_id, 'tool_progress_callback', *args, **kwargs)
  463. def publish_api_tool_event(authority, session_id, generation, event_type, call_id, tool_name, args, result=None):
  464. """Real tool arguments/results for the admission's API observers (Responses streaming,
  465. runs SSE); never part of the shared viewer event stream."""
  466. live = authority.sessions[session_id]
  467. with live.event_stream.lock:
  468. try:
  469. authority.check_approval_generation(session_id, generation)
  470. except RuntimeStoreError:
  471. return
  472. if event_type == 'tool.start':
  473. _notify_observers(authority, session_id, 'tool_start_callback', call_id, tool_name, args or {})
  474. elif event_type == 'tool.complete':
  475. _notify_observers(authority, session_id, 'tool_complete_callback', call_id, tool_name, args or {}, result)
  476. def api_runtime_locked():
  477. """The executing API admission's settings when they carry a confirmed Browser model lock, else
  478. None. Main's ``_create_agent`` passes ``fallback_model=None`` under the lock and refuses a
  479. settled turn whose served runtime differs from it (``_turn_runtime_metadata``)."""
  480. current = api_execution.get()
  481. return current if current and current['settings'].get('confirmed_runtime_lock') else None
  482. def prepare_api_runtime(model, runtime_kwargs):
  483. current = api_execution.get()
  484. if current is None:
  485. return model, runtime_kwargs
  486. options = current['settings']
  487. route = options.get('route')
  488. configured = current['adapter']._model_routes.get(options.get('requested_model'))
  489. if configured and {k: v for k, v in configured.items() if k != 'api_key'} == route:
  490. route = configured
  491. model, _, _, _ = current['adapter']._select_agent_runtime(runtime_kwargs, model,
  492. requested_model=options.get('requested_model'), requested_provider=options.get('requested_provider'),
  493. route=route, session_model=options.get('session_model'),
  494. confirmed_runtime_lock=bool(options.get('confirmed_runtime_lock')),
  495. gateway_session_key=None, session_id=None)
  496. return model, runtime_kwargs