session_queued_controls.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240
  1. """Steer and Edit of a still-queued admission: ``prompt.steer_queued`` / ``prompt.replace_queued``.
  2. Both consume the queued row inside one owner write transaction, so it can never also run as its own
  3. queued turn, and a retry replays the recorded outcome. There is no reorder verb: one FIFO per session.
  4. A steer is a TRANSFER to the running claim, not an outcome: the row goes queued -> terminal
  5. ``steering`` bound to the claim's generation, and settles with that claim (``steered`` once the claim
  6. completes with the text delivered, ``interrupted`` otherwise; queued again in its own FIFO place when
  7. the text never reached the claim's agent). The fence is ``authority.steer_transfers``, changed only
  8. under the session's ``event_stream.lock`` (the lock the drain clears ``executing`` under): no storage
  9. write ever waits under that lock, which loop-side receipts, attaches and publication take.
  10. """
  11. import asyncio
  12. from dataclasses import asdict
  13. from functools import partial
  14. from hermes_state_runtime import (
  15. STEERING, RuntimeStoreError, check_replaced_input, find_session_admission, get_session_admission,
  16. replacement_binding, retire_replaced_input, revert_steer_input, steer_replayed, steer_session_input,
  17. )
  18. # A steer carries plain text and its presentation only. Attachments, finite runs, classic-CLI turns,
  19. # native envelopes and automation rows are whole turns: neither verb may drop what they carry.
  20. _TEXT_ONLY = frozenset({'text', 'surface_v1', 'display_v1', 'local_operator_v1'})
  21. # Sessions launched from an interactive local surface (classic CLI, TUI, Desktop, ACP editor): their
  22. # plain-text rows are prompt.submit input, whose observers settle a ``steered``/``cancelled`` row.
  23. # ``desktop`` is the label a Desktop chat migrated from main keeps (hermes_state_local_migration).
  24. # cron, kanban, a2a and hosted-room (bot_room) producers read a saved result for every outcome they
  25. # do not name, so a transfer or replacement would strand them: never offered, refused by name.
  26. _INTERACTIVE_SOURCES = frozenset({'cli', 'tui', 'gui', 'desktop', 'acp'})
  27. def handlers(connection):
  28. return {'prompt.steer_queued': partial(steer_queued, connection),
  29. 'prompt.replace_queued': partial(replace_queued, connection)}
  30. def _interactive(authority, session_id):
  31. """The session's frozen launch source (a local session's row records it) names a local surface.
  32. Callers hold the stream lock: one plain read per session, cached (``get_session`` flushes token
  33. counts, a write). Under WAL it takes the lock-free reader pool, as ``_pending_rows`` does there."""
  34. sources = authority.launch_sources
  35. if session_id not in sources:
  36. with authority.db._read_ctx() as conn:
  37. found = conn.execute('SELECT source FROM sessions WHERE id=?', (session_id,)).fetchone()
  38. if found is None:
  39. return False
  40. sources[session_id] = found[0]
  41. return sources[session_id] in _INTERACTIVE_SOURCES
  42. def queued_controls(authority, row):
  43. """The queued-row verbs this owner serves for ``row``: a client shows only these (an older owner
  44. lists none, so its clients show none)."""
  45. payload = row.get('payload') or {}
  46. text = payload.get('text')
  47. if (row.get('status') != 'queued' or set(payload) - _TEXT_ONLY or not isinstance(text, str) or not text.strip()
  48. or (payload.get('display_v1') or {}).get('kind') == 'hidden'
  49. or not _interactive(authority, row['target_session_id'])):
  50. return []
  51. return ['steer', 'replace']
  52. def pending_rows(authority, ref):
  53. """The pending rows a viewer is shown, plus each queued admission in transfer to the running
  54. claim: listed ``started`` and ``steering``, because it may still go back to its queue place, and a
  55. client must not retire an admission it no longer sees. The caller holds the stream lock."""
  56. rows = {row['admission_id']: row for row in authority._pending_rows(ref)}
  57. entry = authority.steer_transfers.get(ref.session_id)
  58. for admission_id in entry[1] if entry is not None else ():
  59. row = get_session_admission(authority.db, admission_id=admission_id)
  60. if row is not None and row['status'] == 'terminal' and row['outcome'] == STEERING:
  61. rows[admission_id] = row
  62. return sorted(rows.values(), key=lambda row: row['seq'])
  63. async def _queued(connection, ref, admission_id):
  64. receipt = await connection.authority.receipt(connection.actor, ref, admission_id)
  65. return receipt, get_session_admission(connection.authority.db, admission_id=admission_id)
  66. def steer_transfers(authority, session_id, generation):
  67. """``{admission_id: delivered}`` handed to this claim; the caller holds the stream lock. Read by
  68. the claim's settlement after its execution returned, when no transfer can still be delivered.
  69. The agent settles each one by its ticket (the admission id), never by its text: one no drain of
  70. the turn consumed (still buffered, or dropped unread) reads undelivered and goes back to its queue."""
  71. entry = authority.steer_transfers.get(session_id)
  72. if entry is None or entry[0] != generation:
  73. return None
  74. adopted_generation, agent = authority.adopted.get(session_id, (None, None))
  75. withdraw = getattr(agent, 'withdraw_steer', None) if adopted_generation == generation else None
  76. for admission_id, delivered in entry[1].items():
  77. if delivered and callable(withdraw) and withdraw(admission_id):
  78. entry[1][admission_id] = False
  79. return dict(entry[1])
  80. def _register(authority, session_id, generation, admission_id):
  81. """``{admission_id: delivered}`` for the claim ``generation``."""
  82. entry = authority.steer_transfers.get(session_id)
  83. if entry is None or entry[0] != generation:
  84. entry = authority.steer_transfers[session_id] = (generation, {})
  85. entry[1].setdefault(admission_id, False) # a concurrent duplicate never resets a delivery
  86. def _unregister(authority, session_id, generation, admission_id):
  87. entry = authority.steer_transfers.get(session_id)
  88. if entry is not None and entry[0] == generation and entry[1].get(admission_id) is False:
  89. del entry[1][admission_id]
  90. def _receiving_agent(authority, session_id, generation):
  91. """The agent the running claim adopted, while that claim still executes. None before adoption (a
  92. latched text would be dropped if construction then failed) and for a turn with no steer seam."""
  93. adopted_generation, agent = authority.adopted.get(session_id, (None, None))
  94. if (adopted_generation != generation or authority.executing.get(session_id) != generation
  95. or not callable(getattr(agent, 'steer', None))):
  96. return None
  97. return agent
  98. def _deliver(authority, session_id, generation, agent, admission_id, text):
  99. """Hand the committed text to the claim's agent; the caller holds the stream lock. False once the
  100. claim stopped executing (its settlement then decides the row) or its agent refused the text."""
  101. entry = authority.steer_transfers.get(session_id)
  102. if (entry is None or entry[0] != generation or admission_id not in entry[1]
  103. or _receiving_agent(authority, session_id, generation) is not agent):
  104. return False
  105. if not entry[1][admission_id]:
  106. # Ticketed by its admission id: settlement withdraws exactly it if no drain of the turn consumed it.
  107. ticketed = callable(getattr(agent, 'withdraw_steer', None))
  108. entry[1][admission_id] = bool(agent.steer(text, ticket=admission_id) if ticketed else agent.steer(text))
  109. return entry[1][admission_id]
  110. async def steer_queued(connection, ref, params):
  111. authority, admission_id = connection.authority, params['admission_id']
  112. authority.authorize(connection.actor, ref, 'session:control')
  113. receipt, row = await _queued(connection, ref, admission_id)
  114. if steer_replayed(row):
  115. if row['outcome'] == STEERING:
  116. # A transfer committed under an uncertain failure is still fenced to its claim: deliver it.
  117. with authority.sessions[ref.session_id].event_stream.lock:
  118. agent = _receiving_agent(authority, ref.session_id, row['generation'])
  119. if agent is not None:
  120. _deliver(authority, ref.session_id, row['generation'], agent, admission_id, row['payload']['text'])
  121. return asdict(receipt) # an exact retry replays the committed transfer
  122. if receipt.status != 'queued':
  123. raise RuntimeStoreError('admission_started')
  124. if 'steer' not in queued_controls(authority, row):
  125. raise RuntimeStoreError('unsupported_control')
  126. handle = authority._handle(ref)
  127. if handle.execution_state != 'running':
  128. raise RuntimeStoreError('session_idle')
  129. generation, text, live = handle.execution_generation, row['payload']['text'], authority.sessions[ref.session_id]
  130. session_id = ref.session_id
  131. with live.event_stream.lock:
  132. agent = _receiving_agent(authority, session_id, generation)
  133. if agent is None:
  134. # Refused before the row is touched: it stays queued and runs in FIFO order.
  135. raise RuntimeStoreError('steer_unavailable', field='admission_id',
  136. detail='the running turn has no agent to take a steer yet')
  137. _register(authority, session_id, generation, admission_id)
  138. from gateway.session_runtime_workers import tracked_write
  139. try:
  140. # The storage wait runs with no lock held; the registration above is the claim's fence.
  141. committed, fresh = await tracked_write(authority, partial(
  142. steer_session_input, authority.db, epoch=authority.epoch, admission_id=admission_id, generation=generation))
  143. except RuntimeStoreError:
  144. # A definite refusal: nothing committed. Any other failure may follow a commit, so the fence
  145. # stays and the claim's settlement decides the row (a no-op when nothing committed).
  146. with live.event_stream.lock:
  147. _unregister(authority, session_id, generation, admission_id)
  148. raise
  149. if fresh:
  150. with live.event_stream.lock:
  151. delivered = _deliver(authority, session_id, generation, agent, admission_id, text)
  152. if not delivered:
  153. # The claim ended first: the text reached nobody, so the admission is queued again.
  154. await tracked_write(authority, partial(revert_steer_input, authority.db, epoch=authority.epoch,
  155. admission_id=admission_id, generation=generation))
  156. with live.event_stream.lock:
  157. _unregister(authority, session_id, generation, admission_id)
  158. authority._publish_pending(ref)
  159. authority._schedule(ref)
  160. raise RuntimeStoreError('steer_unavailable', field='admission_id',
  161. detail='the running turn ended before the steer reached it')
  162. authority._publish_pending(ref) # the card leaves the queue: its text is in the running turn
  163. return asdict(authority._receipt(committed))
  164. def publish_transfers(authority, ref, generation):
  165. """After the claim's settlement: each admission it carried publishes the outcome it settled to
  166. (``steered``, or ``cancelled`` for an interrupted transfer, as a turn's completion reports it)."""
  167. live = authority.sessions.get(ref.session_id)
  168. entry = authority.steer_transfers.get(ref.session_id)
  169. if live is None or entry is None or entry[0] != generation:
  170. return
  171. with live.event_stream.lock:
  172. authority.steer_transfers.pop(ref.session_id, None)
  173. for admission_id in entry[1]:
  174. row = get_session_admission(authority.db, admission_id=admission_id)
  175. if row is not None and row['status'] == 'terminal' and row['outcome'] in ('steered', 'interrupted'):
  176. authority._settle_cancelled(ref, admission_id,
  177. outcome='steered' if row['outcome'] == 'steered' else 'cancelled')
  178. authority._publish_pending(ref) # an undelivered transfer is queued again
  179. async def replace_queued(connection, ref, params):
  180. """Cancel the queued admission and admit the edit at the FIFO tail under a new identity, in one
  181. write. The replacement is bound to the admission it retired: an exact retry (same old admission,
  182. same new ``submission_id``) answers the same new admission; any other old admission under that
  183. ``submission_id`` is ``admission_conflict``, decided inside the admission's own transaction."""
  184. authority, actor, old_id = connection.authority, connection.actor, params['admission_id']
  185. request = connection.submission(ref, {key: value for key, value in params.items() if key != 'admission_id'})
  186. receipt, row = await _queued(connection, ref, old_id)
  187. replacement = await asyncio.to_thread(find_session_admission, authority.db, principal_id=actor.subject,
  188. session_id=ref.session_id, request_id=request.request_id)
  189. if replacement is None:
  190. if receipt.status != 'queued':
  191. raise RuntimeStoreError('admission_started')
  192. if 'replace' not in queued_controls(authority, row):
  193. raise RuntimeStoreError('unsupported_control')
  194. authority.cancel_obligations.add(old_id) # owed from before the write, like prompt.cancel
  195. elif (receipt.status, receipt.outcome) != ('terminal', 'cancelled'):
  196. raise RuntimeStoreError('admission_conflict') # that request id names other work
  197. binding = replacement_binding(actor.subject, ref.session_id, request.request_id)
  198. try:
  199. admitted = await authority.submit(actor, request, queue_while_restarting=connection._operator is True,
  200. _authorize_write=partial(retire_replaced_input, admission_id=old_id, binding=binding),
  201. _replay_guard=partial(check_replaced_input, admission_id=old_id, binding=binding))
  202. finally:
  203. old = get_session_admission(authority.db, admission_id=old_id)
  204. if old_id in authority.cancel_obligations and (old['status'], old['outcome']) == ('terminal', 'cancelled'):
  205. authority._settle_cancelled(ref, old_id)
  206. elif old['status'] == 'queued':
  207. authority.cancel_obligations.discard(old_id) # refused: nothing committed
  208. from gateway.session_ingress_media import release_admission_media
  209. await asyncio.to_thread(release_admission_media, authority.db, old_id)
  210. return asdict(admitted)