hermes_state_local.py 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419
  1. """Private local creation receipts in the canonical runtime transaction owner."""
  2. import json
  3. import threading
  4. import time
  5. from collections import OrderedDict
  6. from hermes_state_runtime import RuntimeStoreError, _epoch, _json
  7. POLICY_PREFIX = 'gateway.local_policy.v1:'
  8. API_BINDING_PREFIX = 'gateway.api.binding.v1.'
  9. API_DECLARED_PREFIX = 'gateway.api.conversation.v1.'
  10. def commit_local_session(db, *, epoch, receipt):
  11. """Reserve the row, route and immutable policy together, before publication. A staged receipt's
  12. ``on_create`` (owner memory, never stored) is published by the transaction that creates the row
  13. and withdrawn if that transaction fails: an exact retry, a refused or a losing attempt adds none."""
  14. on_create = getattr(receipt, 'on_create', None)
  15. request = getattr(receipt, 'client_request', None) # the staged request's own client_env, never stored
  16. if request is None:
  17. if receipt['policy'].get('client_env_json') is not None:
  18. # Lost (a copy): never judge a retry by this attempt's own filtered map instead.
  19. raise RuntimeStoreError('invalid_params')
  20. request = {}
  21. if on_create is not None:
  22. on_create.read() # its file read: in the caller's thread, outside the write transaction
  23. encoded = _json(receipt)
  24. receipt = json.loads(encoded)
  25. sid, route = receipt['session_id'], receipt['route']
  26. key = POLICY_PREFIX + sid
  27. def write(conn):
  28. _epoch(conn, epoch)
  29. old = conn.execute('SELECT value FROM state_meta WHERE key=?', (key,)).fetchone()
  30. if old is not None:
  31. try:
  32. saved = json.loads(old[0])
  33. same = all(saved[k] == receipt[k] for k in (
  34. 'profile_id', 'principal_id', 'request_id', 'session_id', 'route'))
  35. same = same and same_create_retry(saved['policy'], receipt['policy']['request_json'], request)
  36. except (ValueError, TypeError, KeyError) as exc:
  37. raise RuntimeStoreError('storage_unavailable') from exc
  38. if not same:
  39. raise RuntimeStoreError('invalid_params')
  40. return saved
  41. from hermes_state_mutation_retirement import RETIRED_PREFIX
  42. if conn.execute('SELECT 1 FROM state_meta WHERE key=?', (RETIRED_PREFIX + sid,)).fetchone():
  43. # Deleted: its receipt was retired with the transcript; a create/cron retry must not
  44. # resurrect the row (and re-fire its prompt) under the same deterministic id.
  45. raise RuntimeStoreError('not_found')
  46. if ('legacy_session_id' not in receipt and
  47. conn.execute('SELECT 1 FROM sessions WHERE id=?', (sid,)).fetchone()):
  48. raise RuntimeStoreError('storage_unavailable')
  49. if conn.execute("SELECT 1 FROM gateway_routing WHERE scope='' AND session_key=?", (route,)).fetchone():
  50. raise RuntimeStoreError('admission_conflict')
  51. if 'legacy_session_id' in receipt:
  52. from hermes_state_local_migration import bind_legacy_target
  53. bind_legacy_target(db, conn, receipt)
  54. policy, entry = receipt['policy'], receipt['entry']
  55. from datetime import datetime
  56. started = datetime.fromisoformat(entry['created_at']).timestamp()
  57. # Auxiliary usage inserts created_source='unknown' when it creates the row
  58. # (record_auxiliary_usage carries no surface). The creator upsert repairs
  59. # 'unknown', but this DO NOTHING insert does not, so the surface is stamped here.
  60. # The agent's own accounting passes its surface (turn_usage._agent_session_source)
  61. # and is not that writer. gui's in-process agent is desktop; a managed worker
  62. # creates with the policy label gui.
  63. from gateway.session_policy import created_surface
  64. created = created_surface(policy['source'])
  65. conn.execute('''INSERT INTO sessions(id,source,created_source,user_id,session_key,chat_id,chat_type,
  66. model,cwd,profile_name,origin_json,started_at) VALUES(?,?,?,?,?,?,'dm',?,?,?,?,?)
  67. ON CONFLICT(id) DO NOTHING''',
  68. (sid, policy['source'], created, receipt['principal_id'], route,
  69. entry['origin']['chat_id'], policy['model'], _row_cwd(policy), db._own_profile_name(),
  70. _json(entry['origin']), started))
  71. conn.execute("INSERT INTO gateway_routing(scope,session_key,entry_json,updated_at) VALUES('',?,?,?)",
  72. (route, _json(entry), started))
  73. conn.execute('INSERT INTO state_meta(key,value) VALUES(?,?)', (key, encoded))
  74. if on_create is not None:
  75. on_create.publish() # before the row is visible, so no reader lazy-loads around it
  76. return receipt
  77. try:
  78. return db._execute_write(write)
  79. except BaseException:
  80. if on_create is not None:
  81. on_create.withdraw() # only this attempt's own snapshot, never another winner's
  82. raise
  83. def client_request(request_json, derived=None):
  84. """A frozen create request as the client sent it: an owner-resolved ``-m`` route (``model_requested``)
  85. compares by the name the client typed, not by the model and the *derived* fields (a receipt from
  86. before ``route_derived``: the endpoint) its ``${VAR}`` refs expanded to at the time. ``desktop_local``
  87. (``gateway.session_policy.LOCAL_DESKTOP_CHAT``), which an earlier owner stamped into the request, was
  88. never sent."""
  89. request = json.loads(request_json)
  90. request.pop('desktop_local', None)
  91. if derived is None:
  92. request.pop('route_derived', None)
  93. if 'model_requested' in request:
  94. request.pop('model', None)
  95. for key in ('base_url',) if derived is None else derived:
  96. request.pop(key, None)
  97. return request
  98. def same_create_request(saved_json, retry_json):
  99. """Whether a create retry carries the frozen request it resumes: one check for a retry that finds the
  100. session committed and one staged before it was. The saved receipt's provenance names the owner's
  101. fields; one from before a same-name alias got ``model_requested`` compares exactly, as it did."""
  102. derived = json.loads(saved_json).get('route_derived')
  103. if client_request(saved_json, derived) == client_request(retry_json, derived):
  104. return True
  105. retry = json.loads(retry_json)
  106. if retry.get('model_requested') == retry.get('model'):
  107. retry.pop('model_requested', None)
  108. retry.pop('route_derived', None)
  109. return json.loads(saved_json) == retry
  110. def same_create_retry(saved_policy, retry_json, client_request):
  111. """The one exact-retry identity of a create: ``same_create_request`` on what the client sent, and its
  112. ``client_env`` (``client_request``: the retry's own, never stored) judged by the rules frozen with
  113. *saved_policy*. Used by a retry that finds the session committed, at commit, and by one overlapping
  114. the attempt that holds the session's key slot."""
  115. from agent.session_client_env import retry_matches
  116. return same_create_request(saved_policy['request_json'], retry_json) and retry_matches(saved_policy, client_request)
  117. def _row_cwd(policy):
  118. """The sessions-row ``cwd``: the create request's ``row_cwd`` (``""`` = none) when it sent one,
  119. else the execution cwd. Row metadata only (workspace grouping, ``-c``, cwd restore); the
  120. frozen policy's ``cwd`` / ``TERMINAL_CWD`` stay where the session's tools run."""
  121. try:
  122. request = json.loads(policy.get('request_json') or '{}')
  123. except (TypeError, ValueError):
  124. request = {}
  125. value = request.get('row_cwd') if isinstance(request, dict) else None
  126. return policy['cwd'] if not isinstance(value, str) else (value or None)
  127. def _policy_target(raw):
  128. """Current physical target a creation receipt routes to; None for a malformed receipt, which
  129. then stays (its own reads already refuse it as ``storage_unavailable``) and cannot abort
  130. the delete of an unrelated session."""
  131. try:
  132. value = json.loads(raw)
  133. except (TypeError, ValueError):
  134. return None
  135. entry = value.get('entry') if isinstance(value, dict) else None
  136. return entry.get('session_id') if isinstance(entry, dict) else None
  137. def retire_local_receipts(conn, session_ids):
  138. """Deletion fence half for owner receipts. A local creation policy carries the launch request
  139. (``request_json``: a cron fire's job and raw prompt), so it goes exactly when its route does:
  140. when the receipt's current physical target is deleted (a pruned reset ancestor whose logical
  141. session lives on in a child keeps it). An API binding and the declared conversation key that
  142. resolves to it go with their id, so that key starts a fresh session."""
  143. targets = set(session_ids)
  144. if not targets:
  145. return
  146. # Prefix scans (GLOB uses the key index), not one LIKE per id: a prune retires thousands.
  147. gone = [key for key, value in conn.execute('SELECT key,value FROM state_meta WHERE key GLOB ?',
  148. (POLICY_PREFIX + '*',))
  149. if _policy_target(value) in targets]
  150. gone += [key for key, value in conn.execute('SELECT key,value FROM state_meta WHERE key GLOB ?',
  151. (API_DECLARED_PREFIX + '*',)) if value in targets]
  152. gone += [API_BINDING_PREFIX + sid for sid in targets]
  153. conn.executemany('DELETE FROM state_meta WHERE key=?', [(key,) for key in gone])
  154. def moved_receipts(conn, target_ids=None):
  155. """``{owner id: (moved row id, its source)}`` of local receipts whose current physical target row
  156. now carries another lane's route. An explicit repoint (``/handoff``, a platform ``/resume``)
  157. rewrote that row's routing identity, so the receipt can never restore the conversation again
  158. (the stored identity check in ``gateway.session_local_recovery._checked_entry``). Only the
  159. current target counts: an earlier ``/new`` segment that moved leaves the conversation the
  160. receipt guards local, and releasing it would strand that transcript. *target_ids* narrows the
  161. scan to the rows one repoint rewrote."""
  162. rows = conn.execute(
  163. "SELECT substr(m.key, ?), s.id, s.source FROM state_meta m JOIN sessions s "
  164. "ON s.id = CASE WHEN json_valid(m.value) THEN json_extract(m.value, '$.entry.session_id') END "
  165. "WHERE m.key GLOB ? AND s.session_key IS NOT NULL "
  166. "AND s.session_key IS NOT CASE WHEN json_valid(m.value) THEN json_extract(m.value, '$.route') END",
  167. (len(POLICY_PREFIX) + 1, POLICY_PREFIX + '*')).fetchall()
  168. return {owner: (target, source) for owner, target, source in rows
  169. if target_ids is None or target in target_ids}
  170. def release_receipts(conn, owners):
  171. """Retire *owners*' local receipts (creation policy and legacy binding): the row they guarded now
  172. belongs to a messaging lane, which restores it from its route like any other platform session."""
  173. from hermes_state_local_migration import LEGACY_PREFIX
  174. conn.executemany('DELETE FROM state_meta WHERE key IN (?,?)',
  175. [(POLICY_PREFIX + owner, LEGACY_PREFIX + owner) for owner in owners])
  176. def handoff_head(db, session_id):
  177. """``(local owner or None, row)`` a ``/handoff`` of *session_id* moves: the conversation the user
  178. is looking at. A local conversation continues from its receipt's current target (its latest
  179. ``/new`` segment, then that segment's compression tip), never from an earlier segment; any other
  180. row from its compression tip."""
  181. with db._read_ctx() as conn:
  182. owner = local_lineage_owner(conn, session_id)
  183. saved = conn.execute('SELECT value FROM state_meta WHERE key=?', (POLICY_PREFIX + owner,)).fetchone()
  184. target = _policy_target(saved[0]) if saved else None
  185. start = target or session_id
  186. return (owner if target else None), db.get_compression_tip(start) or start
  187. _LANE_IDENTITY = 'session_key, source, user_id, chat_id, chat_type, thread_id, display_name, origin_json, transport_profile'
  188. def hand_off_conversations(conn, moved):
  189. """Retire the receipts in *moved* (``moved_receipts``: a messaging lane took over each one's
  190. current target) and move the rest of each conversation onto that lane with it. Its earlier
  191. ``/new`` segments take the lane's identity, so they open there as read-only history (a lane
  192. moved past them) instead of staying local rows no receipt restores; the conversation's name
  193. follows its head, which the lane continues as its own conversation. Returns the receipts it
  194. handed off: one whose lineage is malformed stays as it is (its own reads refuse it, logged)."""
  195. handed = {}
  196. for owner, (target, source) in moved.items():
  197. saved = conn.execute('SELECT value FROM state_meta WHERE key=?', (POLICY_PREFIX + owner,)).fetchone()
  198. lineage = (_receipt(saved[0]) or {}).get('lineage', [owner]) if saved else [owner]
  199. if not isinstance(lineage, list) or not all(isinstance(sid, str) for sid in lineage):
  200. continue
  201. segments = list(dict.fromkeys([owner, *lineage]))
  202. conn.execute(f'UPDATE sessions SET ({_LANE_IDENTITY}) = (SELECT {_LANE_IDENTITY} FROM sessions WHERE id=?) '
  203. 'WHERE id IN (SELECT value FROM json_each(?)) AND id != ?', (target, json.dumps(segments), target))
  204. _title_follows_head(conn, owner, _segment_root(conn, segments, target))
  205. handed[owner] = (target, source)
  206. release_receipts(conn, handed)
  207. return handed
  208. def _receipt(raw):
  209. try:
  210. value = json.loads(raw)
  211. except (TypeError, ValueError):
  212. return None
  213. return value if isinstance(value, dict) else None
  214. def _segment_root(conn, segments, target):
  215. """The first row of *target*'s ``/new`` segment: back through the compressions behind it."""
  216. if target not in segments:
  217. return target
  218. index = segments.index(target)
  219. while index > 0 and (row := conn.execute('SELECT end_reason FROM sessions WHERE id=?',
  220. (segments[index - 1],)).fetchone()) and row[0] == 'compression':
  221. index -= 1
  222. return segments[index]
  223. def _title_follows_head(conn, owner, head):
  224. """The conversation's name (a Bot Chat's registry title included) moves to its head, over a
  225. title of lower provenance there (a generated one); a name of equal rank the head carries stays
  226. (``SessionDB._title_rank``: a pre-provenance title ranks as the user's)."""
  227. from hermes_state import SessionDB
  228. row = conn.execute('SELECT title, title_source, hidden FROM sessions WHERE id=?', (owner,)).fetchone()
  229. if head == owner or row is None or not row[0]:
  230. return
  231. kept = conn.execute('SELECT title, title_source FROM sessions WHERE id=?', (head,)).fetchone()
  232. if kept is None or (kept[0] and SessionDB._title_rank(kept[1]) >= SessionDB._title_rank(row[1])):
  233. return
  234. conn.execute('UPDATE sessions SET title=NULL WHERE id IN (?,?)', (owner, head))
  235. conn.execute('UPDATE sessions SET title=?, title_source=?, hidden=? WHERE id=?', (*row, head))
  236. def local_lineage_owner(conn, session_id):
  237. """The creation id whose receipt lineage holds physical segment *session_id* (a reset or
  238. compression child, which carries the owner as ``chat_id``); *session_id* itself otherwise."""
  239. row = conn.execute('SELECT chat_id FROM sessions WHERE id=?', (session_id,)).fetchone()
  240. owner = row[0] if row else None
  241. if not owner or owner == session_id:
  242. return session_id
  243. saved = conn.execute('SELECT value FROM state_meta WHERE key=?', (POLICY_PREFIX + owner,)).fetchone()
  244. try:
  245. lineage = json.loads(saved[0]).get('lineage') if saved else None
  246. except (TypeError, ValueError, AttributeError):
  247. return session_id
  248. return owner if isinstance(lineage, list) and session_id in lineage else session_id
  249. def owned_lineage_ids(conn, session_id):
  250. """[session_id] for any row outside a local reset/compression lineage, else the whole
  251. conversation (*session_id* first). Any segment deletes as all of it: the owner's policy goes
  252. with its current target, and an earlier segment's gap breaks the lineage, so a lone segment
  253. delete strands the rest (and the owner's queued work) readable but never continuable."""
  254. return list(dict.fromkeys([session_id, *local_conversation_ids(conn, session_id)]))
  255. def local_conversation_ids(conn, session_id):
  256. """Every row of the local conversation *session_id* belongs to: its creation id first, then
  257. each segment of the receipt lineage. A canonical reset never forks the logical session (one
  258. policy, FIFO and generation), so listing, delete and retirement treat these ids as one."""
  259. owner = local_lineage_owner(conn, session_id)
  260. saved = conn.execute('SELECT value FROM state_meta WHERE key=?', (POLICY_PREFIX + owner,)).fetchone()
  261. try:
  262. lineage = json.loads(saved[0]).get('lineage') if saved else None
  263. except (TypeError, ValueError, AttributeError):
  264. lineage = None
  265. if not isinstance(lineage, list):
  266. return [session_id]
  267. return list(dict.fromkeys([owner, *(sid for sid in lineage if isinstance(sid, str))]))
  268. def local_lineage_index(conn):
  269. """``(superseded, heads)`` for listing a local conversation as one row, as
  270. ``acp_adapter.catalog`` does: a canonical reset keeps the creation id as the owner and moves the
  271. transcript to a child, so every segment is one conversation. ``superseded`` holds the listable
  272. roots of earlier reset segments (filtered in SQL, before paging); ``heads`` maps the latest
  273. reset segment to ``(owner, lineage)`` for the row that represents the conversation. A delete
  274. of that row removes the whole lineage (``hermes_state_mutation_guards.delete_targets``)."""
  275. superseded, heads = set(), {}
  276. rows = conn.execute("SELECT value FROM state_meta WHERE key GLOB ? AND json_valid(value) "
  277. "AND json_array_length(value, '$.lineage') > 1", (POLICY_PREFIX + '*',)).fetchall()
  278. for (raw,) in rows:
  279. receipt = json.loads(raw)
  280. owner, lineage = receipt.get('session_id'), receipt.get('lineage')
  281. if not isinstance(owner, str) or not all(isinstance(sid, str) for sid in lineage):
  282. continue
  283. marks = ','.join('?' * len(lineage))
  284. ended = dict(conn.execute(f'SELECT id,end_reason FROM sessions WHERE id IN ({marks})', lineage).fetchall())
  285. starts = [sid for i, sid in enumerate(lineage) if i == 0 or ended.get(lineage[i - 1]) == 'session_reset']
  286. superseded.update(starts[:-1])
  287. heads[starts[-1]] = (owner, lineage)
  288. return superseded, heads
  289. def _lineage_version(conn):
  290. # data_version sees OTHER connections' commits; total_changes sees this connection's writes.
  291. return conn.total_changes, conn.execute('PRAGMA main.data_version').fetchone()[0]
  292. def _copy_lineage_index(value):
  293. superseded, heads = value
  294. return set(superseded), {key: (owner, list(lineage)) for key, (owner, lineage) in heads.items()}
  295. def _cached_local_lineage_index(db, conn):
  296. # Owned by this SessionDB, not a process-global path/id cache. Bound retained connections
  297. # across read-pool churn and close/reopen; a closed/replaced connection cannot match a new one.
  298. cache, lock = db.__dict__.setdefault('_local_lineage_cache', (OrderedDict(), threading.Lock()))
  299. if conn.in_transaction:
  300. # A snapshot or uncommitted answer must never outlive its transaction (including rollback).
  301. with lock:
  302. cache.pop(conn, None)
  303. return local_lineage_index(conn)
  304. version = _lineage_version(conn)
  305. with lock:
  306. saved = cache.get(conn)
  307. if saved is not None and saved[0] == version:
  308. cache.move_to_end(conn)
  309. return _copy_lineage_index(saved[1])
  310. value = local_lineage_index(conn)
  311. # A concurrent writer may commit between the receipt scan and the end_reason reads. Never
  312. # publish that in-flight projection as a stable cache entry; the next call must rebuild it.
  313. if not conn.in_transaction and _lineage_version(conn) == version:
  314. with lock:
  315. cache[conn] = (version, value)
  316. cache.move_to_end(conn)
  317. if len(cache) > 8:
  318. cache.popitem(last=False)
  319. return _copy_lineage_index(value)
  320. def exclude_superseded_segments(db, where_clauses, params):
  321. """Drop earlier reset segments from a listing or count query (one conversation, one row),
  322. in SQL before paging; returns ``heads`` for :func:`annotate_local_lineages`."""
  323. with db._read_ctx() as conn:
  324. superseded, heads = _cached_local_lineage_index(db, conn)
  325. if superseded:
  326. where_clauses.append("s.id NOT IN (SELECT value FROM json_each(?))")
  327. params.append(json.dumps(sorted(superseded)))
  328. return heads
  329. def annotate_local_lineages(sessions, heads):
  330. """Name every segment on the conversation's representative row (``_lineage_ids``, which the
  331. Desktop matches deletes, tombstones and stored ids against). ``_lineage_root_id`` stays the
  332. compression root: pins and archive flags live on the listed segment's own chain."""
  333. for row in sessions:
  334. found = heads.get(row.get('_lineage_root_id') or row['id'])
  335. if found is not None:
  336. row['_lineage_ids'] = list(dict.fromkeys([*found[1], *(row.get('_lineage_ids') or ())]))
  337. return sessions
  338. def local_receipt(db, session_id):
  339. with db._read_ctx() as conn:
  340. row = conn.execute('SELECT value FROM state_meta WHERE key=?', (POLICY_PREFIX + session_id,)).fetchone()
  341. if row is None:
  342. raise RuntimeStoreError('storage_unavailable')
  343. try:
  344. value = json.loads(row[0])
  345. if not isinstance(value, dict):
  346. raise ValueError('invalid receipt')
  347. return value
  348. except (TypeError, ValueError) as exc:
  349. raise RuntimeStoreError('storage_unavailable') from exc
  350. def end_idle_local_session(db, *, epoch, session_id, target_id, reason):
  351. """Stamp ``ended_at`` on *target_id* only while the logical *session_id*'s FIFO is idle.
  352. The idle check and the stamp share one owner write txn, so an admission committed first keeps
  353. the row open; one committed after is reopened by the drain (``reopen_local_session``)."""
  354. def write(conn):
  355. _epoch(conn, epoch)
  356. if conn.execute("SELECT 1 FROM session_admissions WHERE target_session_id=? AND status IN ('queued','started','unknown')",
  357. (session_id,)).fetchone():
  358. return 0
  359. if conn.execute("SELECT 1 FROM worker_executions WHERE session_id IN (?,?) AND status IN ('registered','running','unknown')",
  360. (session_id, target_id)).fetchone():
  361. return 0
  362. return db._end_and_bump(conn, 'UPDATE sessions SET ended_at=?, end_reason=? WHERE id=? AND ended_at IS NULL',
  363. (time.time(), reason, target_id), target_id, reason)
  364. return db._execute_write(write)