hermes_state_sessions.py 106 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981
  1. """Session lifecycle mixin for SessionDB: row upsert/inheritance, lifecycle
  2. flags (end/reopen/archive/pin/hide/read), model_config patching, listing and
  3. counting, delete cascades, and the auto-archive sweep."""
  4. import glob
  5. import json
  6. import logging
  7. import re
  8. import sqlite3
  9. import time
  10. from pathlib import Path
  11. from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Union
  12. from agent.session_activity import (
  13. ActivityProvenance, bound_activity_description, normalize_activity_provenance,
  14. )
  15. from hermes_state_errors import SessionActiveWriteGuardError
  16. from hermes_state_common import (
  17. _LISTABLE_CHILD_SQL, _RECOVERABLE_END_REASONS,
  18. _RECOVERABLE_END_REASONS_SQL, _RESET_CHILD_SQL, _RESET_END_REASONS, _legacy_reset_child_sql, _non_continuation_child_sql,
  19. _shape_preview, _sql_preview_raw, QUEUED_PROMPT_METADATA_KEY,
  20. _sql_in_window, _sql_json_extract, _sql_session_last_active, _sql_session_last_active_by_id,
  21. escape_like as _escape_like, _SQL_IN_CHUNK, _id_chunks, _placeholders as _session_ids_placeholders,
  22. _source_match_clause, emit_session_deleted, launch_stub_filter_sql,
  23. )
  24. from hermes_state_compression import _CHAIN_CAP, _UNSET_CREATED_SQL
  25. # caplog tests pin the "hermes_state" logger name.
  26. logger = logging.getLogger("hermes_state")
  27. def workspace_key(row: dict[str, Any]) -> Optional[str]:
  28. """Workspace grouping key: git repo root, else cwd, else None (branch excluded: a checkout must not
  29. fragment history)."""
  30. return (row.get("git_repo_root") or "").strip() or (row.get("cwd") or "").strip() or None
  31. def _delegate_from_json(col: str = "model_config") -> str:
  32. return _sql_json_extract(col, "$._delegate_from")
  33. # _merge_model_config_json's "no such row" result — distinct from the legal None
  34. # ("merged config is empty → store NULL").
  35. _MODEL_CONFIG_ROW_MISSING = object()
  36. # ``lineage(id)``: the compression lineage of the session bound twice as ``(?, ?)`` — ancestors and
  37. # continuations over compression edges only (a branch forked from a compressed chat is another chat).
  38. _LINEAGE_CTE_SQL = f"""
  39. WITH RECURSIVE
  40. ancestors(id) AS (
  41. SELECT ?
  42. UNION
  43. SELECT parent.id
  44. FROM ancestors a
  45. JOIN sessions child ON child.id = a.id
  46. JOIN sessions parent ON parent.id = child.parent_session_id
  47. WHERE parent.end_reason = 'compression'
  48. {_non_continuation_child_sql('child.', 'parent.id')}
  49. ),
  50. descendants(id) AS (
  51. SELECT ?
  52. UNION
  53. SELECT child.id
  54. FROM descendants d
  55. JOIN sessions parent ON parent.id = d.id
  56. JOIN sessions child ON child.parent_session_id = parent.id
  57. WHERE parent.end_reason = 'compression'
  58. {_non_continuation_child_sql('child.', 'parent.id')}
  59. ),
  60. lineage(id) AS (
  61. SELECT id FROM ancestors
  62. UNION
  63. SELECT id FROM descendants
  64. )"""
  65. def _parse_model_config(raw: Any) -> dict[str, Any]:
  66. """Tolerant ``model_config`` decode: JSON text or dict -> dict copy; anything else -> {}."""
  67. if isinstance(raw, str) and raw.strip():
  68. try:
  69. raw = json.loads(raw)
  70. except (json.JSONDecodeError, TypeError):
  71. return {}
  72. return dict(raw) if isinstance(raw, dict) else {}
  73. def _cwd_prefix_clause(cwd_prefix: str) -> tuple[str, list[str]]:
  74. prefix = cwd_prefix.rstrip("/\\") or cwd_prefix
  75. # ``_``/``%`` are LIKE wildcards but ordinary path characters: unescaped, a
  76. # prefix also matches sibling directories. The ``=`` arm keeps the raw prefix.
  77. esc = _escape_like(prefix)
  78. return (
  79. "(s.cwd = ? OR s.cwd LIKE ? ESCAPE '\\' OR s.cwd LIKE ? ESCAPE '\\')",
  80. [prefix, f"{esc}/%", f"{esc}\\\\%"],
  81. )
  82. def _workspace_key_clause(key: str) -> tuple[str, list[str]]:
  83. """WHERE for ``workspace_key(row) == key``: git_repo_root equals ``key``, or (rows predating
  84. per-session git metadata) cwd is at/under ``key``."""
  85. prefix = key.rstrip("/\\") or key
  86. cwd_clause, cwd_params = _cwd_prefix_clause(prefix)
  87. return (
  88. f"(s.git_repo_root = ? OR (COALESCE(s.git_repo_root, '') = '' AND {cwd_clause}))",
  89. [prefix, *cwd_params],
  90. )
  91. def _where_sql(clauses: list[str], lead: str = "") -> str:
  92. """``WHERE a AND b`` (with *lead* prefix) or "" when there are no clauses."""
  93. return f"{lead}WHERE {' AND '.join(clauses)}" if clauses else ""
  94. def _session_filter_where(
  95. *, exclude_children: bool = False, source: str | None = None, sources: list[str] | None = None,
  96. session_key: str | None = None, exclude_sources: list[str] | None = None, cwd_prefix: str | None = None,
  97. min_message_count: int = 0, archived_only: bool = False, include_archived: bool = False,
  98. include_subagents: bool = False, local_created_sources: Sequence[str] | None = None,
  99. ) -> tuple[list[str], list[Any]]:
  100. """Shared ``sessions s`` WHERE builder so counts line up with listed rows. ``exclude_children``
  101. hides sub-agent runs and compression continuations but keeps branch/reset children
  102. (``_LISTABLE_CHILD_SQL``); ``include_subagents`` re-admits the sub-agent runs only
  103. (``sessions.show_subagents``). Clause order is part of the SQL text contract."""
  104. where: list[str] = []
  105. params: list[Any] = []
  106. if exclude_children and include_subagents:
  107. where.append(f"({_LISTABLE_CHILD_SQL} OR {_delegate_from_json('s.model_config')} IS NOT NULL)")
  108. elif exclude_children:
  109. where += [_LISTABLE_CHILD_SQL, f"{_delegate_from_json('s.model_config')} IS NULL"]
  110. # Show roots and user-visible branch/reset sessions, while still hiding sub-agent runs and compression
  111. # continuations. All four carry parent_session_id, so the shared predicate classifies the edge from
  112. # stable markers plus legacy-compatible parent metadata. Branch sessions are identified two ways, OR'd
  113. # for robustness: 1. A stable ``_branched_from`` marker in model_config, written by /branch at creation
  114. # time. This survives the parent being reopened and re-ended with a different end_reason (e.g.
  115. # tui_shutdown overwriting 'branched'), which otherwise hides the branch — see issue #20856. 2. The
  116. # legacy heuristic (parent ended with 'branched' before the child started), covering branch sessions
  117. # created before the marker existed.
  118. include_sources = [source] if source else list(sources or [])
  119. source_clause, source_params = _source_match_clause(include_sources, local_created_sources)
  120. for clause, values in (
  121. (source_clause, source_params),
  122. ("s.session_key = ?", [session_key] if session_key else []),
  123. (f"s.source NOT IN ({_session_ids_placeholders(exclude_sources or ())})", exclude_sources or []),
  124. (_cwd_prefix_clause(cwd_prefix) if cwd_prefix else ("", [])),
  125. ("s.message_count >= ?", [min_message_count] if min_message_count > 0 else []),
  126. ):
  127. if values:
  128. where.append(clause)
  129. params.extend(values)
  130. if archived_only:
  131. where.append("s.archived = 1")
  132. elif not include_archived:
  133. where.append("s.archived = 0")
  134. return where, params
  135. def _expand_compression_lineage_ids(conn, frontier: list[str]) -> list[str]:
  136. """One both-direction compression-edge step from *frontier*: forward through every
  137. continuation child and backward through the compression parent, using the SAME edge
  138. definition as ``_CHAIN_STEP_SQL`` / the list-projection CTE (parent ended with
  139. ``reason='compression'``, child is not a branch / reset / delegate / tool session).
  140. Branch/reset children are NOT continuations — they are their own conversations."""
  141. ids = [sid for sid in frontier if sid]
  142. if not ids:
  143. return []
  144. out: list[str] = []
  145. for chunk in _id_chunks(ids, _SQL_IN_CHUNK // 4): # each id bound 4x below
  146. ph = _session_ids_placeholders(chunk)
  147. child_filter = (
  148. f"{_sql_json_extract('child.model_config', '$._branched_from')} IS NULL "
  149. f"AND {_sql_json_extract('child.model_config', '$._delegate_from')} IS NULL "
  150. f"AND NOT ({_RESET_CHILD_SQL.format(a='child')}) "
  151. "AND COALESCE(child.source, '') != 'tool'"
  152. )
  153. out.extend(row["id"] for row in conn.execute(
  154. # forward: every continuation of a compression-ended frontier row
  155. f"SELECT child.id FROM sessions parent "
  156. f"JOIN sessions child ON child.parent_session_id = parent.id "
  157. f"WHERE parent.id IN ({ph}) AND parent.end_reason = 'compression' AND {child_filter}",
  158. chunk,
  159. ).fetchall())
  160. out.extend(row["id"] for row in conn.execute(
  161. # backward: the compression parent of a frontier row
  162. f"SELECT parent.id FROM sessions child "
  163. f"JOIN sessions parent ON parent.id = child.parent_session_id "
  164. f"WHERE child.id IN ({ph}) AND parent.end_reason = 'compression' "
  165. f"AND {child_filter}",
  166. chunk,
  167. ).fetchall())
  168. return out
  169. def _collect_delegate_child_ids(conn, parent_ids: list[str]) -> list[str]:
  170. """Delegate-subagent ids (``_delegate_from`` marker, walked recursively) to cascade-delete with
  171. *parent_ids*; untagged children stay orphaned, not deleted."""
  172. df = _delegate_from_json()
  173. seeds = {sid for sid in parent_ids if sid}
  174. # Seed visited with the parents: a marker chain can loop back onto a parent,
  175. # which would then be collected as its own descendant. Never return parents.
  176. # A delegation marker chain can loop back onto a parent — a cycle, or a parent that is also another
  177. # parent's delegate child when several ids are deleted at once — and without this guard that parent
  178. # would be collected as one of its own descendants and cascade-deleted along with all of its messages.
  179. # Callers delete the parents separately, so parents must never appear in the returned child set.
  180. # (#49148)
  181. found: set[str] = set(seeds)
  182. frontier = list(seeds)
  183. while frontier:
  184. next_frontier: list[str] = []
  185. for chunk in _id_chunks(frontier, _SQL_IN_CHUNK // 2): # each id is bound twice below
  186. ph = _session_ids_placeholders(chunk)
  187. cursor = conn.execute(
  188. f"SELECT id FROM sessions WHERE {df} IN ({ph}) "
  189. f"OR (parent_session_id IN ({ph}) AND {df} IS NOT NULL)", chunk + chunk,
  190. )
  191. for row in cursor.fetchall():
  192. if row["id"] not in found:
  193. found.add(row["id"])
  194. next_frontier.append(row["id"])
  195. frontier = next_frontier
  196. return [sid for sid in found if sid not in seeds]
  197. def _delete_delegate_children(conn, parent_ids: list[str]) -> list[str]:
  198. ids = _collect_delegate_child_ids(conn, parent_ids)
  199. from hermes_state_mutation_retirement import retire_sessions
  200. retire_sessions(conn, ids)
  201. for chunk in _id_chunks(ids):
  202. ph = _session_ids_placeholders(chunk)
  203. conn.execute(f"DELETE FROM messages WHERE session_id IN ({ph})", chunk)
  204. # FK safety: orphan any untagged stragglers pointing at a doomed row.
  205. conn.execute(f"UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id IN ({ph})", chunk)
  206. conn.execute(f"DELETE FROM sessions WHERE id IN ({ph})", chunk)
  207. return ids
  208. # Lifecycle statuses surfaced by session pickers; classified from the final
  209. # message row ONLY so it stays O(1) per session.
  210. # Sessions that are not human conversations (kanban workers, third-party tool integrations, finite one-shot
  211. # runs): every human picker — TUI/Desktop session lists, ``/sessions`` in the CLI, ``sessions list`` in the
  212. # console — excludes them. A deny-list, so new interactive platforms surface automatically.
  213. INTERNAL_LISTING_SOURCES = ("kanban", "tool", "oneshot")
  214. SESSION_STATUS_COMPLETE = "complete"
  215. SESSION_STATUS_INTERRUPTED = "interrupted"
  216. SESSION_STATUS_ERROR = "error"
  217. SESSION_STATUS_EMPTY = "empty"
  218. # finish_reason values meaning the turn ended in a provider/agent error.
  219. _ERROR_FINISH_REASONS = frozenset({"error", "agent_error", "content_filter"})
  220. def classify_session_status(role: Optional[str], has_tool_calls: bool, finish_reason: Optional[str]) -> str:
  221. """Error finish → ``error``; assistant with pending tool_calls or a trailing user/tool row →
  222. ``interrupted``; otherwise ``complete`` (benign default: pickers must not alarm on unknown shapes)."""
  223. if (finish_reason or "").strip().lower() in _ERROR_FINISH_REASONS:
  224. return SESSION_STATUS_ERROR
  225. r = (role or "").strip().lower()
  226. if r in {"user", "tool"} or (r == "assistant" and has_tool_calls):
  227. return SESSION_STATUS_INTERRUPTED
  228. return SESSION_STATUS_COMPLETE
  229. # Parent→child profile_name inheritance fence: keyless rows inherit freely; two
  230. # ``agent:<ns>:...`` keyed rows must agree on the namespace.
  231. # ``agent:<ns>:...`` gateway keys encode the profile namespace; a keyless row (CLI / subagent lineage)
  232. # carries none and inherits freely. Two keyed rows must agree on ``agent:<ns>:`` — a default child
  233. # (``agent:main:``) forked from a sibling profile's row must not be durably mislabelled as that profile's.
  234. # See #88381.
  235. _SAME_KEY_NAMESPACE_SQL = (
  236. "p.session_key IS NULL OR sessions.session_key IS NULL"
  237. " OR substr(p.session_key, 1, instr(substr(p.session_key, 7), ':') + 6)"
  238. " = substr(sessions.session_key, 1, instr(substr(sessions.session_key, 7), ':') + 6)"
  239. )
  240. # Upsert tail of _insert_session_row: every routing/metadata column keeps the value an
  241. # earlier writer set (whitespace is part of the SQL text).
  242. _UPSERT_KEEP_EXISTING_SQL = ",\n".join(
  243. f" {col} = COALESCE(sessions.{col}, excluded.{col})" for col in (
  244. "session_key", "chat_id", "chat_type", "thread_id", "parent_session_id", "cwd", "profile_name",
  245. "transport_profile", "git_repo_root", "origin_json", "display_name",
  246. )
  247. ) + ",\n" + (
  248. # Accounting may insert before the creator ('unknown') and a routing write carries 'local':
  249. # neither is creation provenance (_UNSET_CREATED_SQL), so a later creator replaces them and
  250. # 'local' never replaces anything. A real source, once stamped, is preserved (#56439).
  251. " created_source = CASE WHEN "
  252. + _UNSET_CREATED_SQL.format(col="sessions.created_source")
  253. + " THEN COALESCE(NULLIF(excluded.created_source, 'local'), sessions.created_source)"
  254. " ELSE sessions.created_source END"
  255. )
  256. def _inherit_col_sql(col: str, extra: str = "") -> str:
  257. """``col = COALESCE(sessions.col, (SELECT p.col FROM parent))`` (whitespace is part of the SQL text)."""
  258. pad = " " * (30 + len(col))
  259. return (
  260. f"{col} = COALESCE(sessions.{col},\n{pad}(SELECT p.{col} FROM sessions p\n"
  261. f"{pad} WHERE p.id = sessions.parent_session_id{extra}))"
  262. )
  263. _INHERIT_SEP = ",\n" + " " * 27
  264. _INHERIT_PARENT_META_SQL = (
  265. "UPDATE sessions\n SET "
  266. + _INHERIT_SEP.join((
  267. *(_inherit_col_sql(c) for c in ("cwd", "git_repo_root", "git_branch")),
  268. _inherit_col_sql("profile_name", "\n" + " " * 46 + f"AND ({_SAME_KEY_NAMESPACE_SQL})"),
  269. ))
  270. + "\n WHERE id = ? AND parent_session_id IS NOT NULL"
  271. )
  272. # A delegate/branch fork of a row that happens to have ended on compression is still not that
  273. # conversation's continuation. Markers are matched against the QUERIED parent id rather than mere
  274. # presence, for the same reason as _NON_CONTINUATION_CHILD_FILTER_SQL: a continuation inherits its
  275. # parent's model_config verbatim, so presence-matching would misclassify it as a delegate.
  276. _FORK_EDGE_EXCLUSION_SQL = "".join(
  277. f"\n AND COALESCE({_sql_json_extract('model_config', f'$.{marker}')}, '')"
  278. "\n != parent_session_id"
  279. for marker in ("_delegate_from", "_branched_from")
  280. )
  281. _INHERIT_PARENT_ROUTING_SQL = (
  282. "UPDATE sessions\n SET "
  283. + _INHERIT_SEP.join(_inherit_col_sql(c) for c in (
  284. "user_id", "session_key", "chat_id", "chat_type", "thread_id", "display_name", "origin_json",
  285. "transport_profile",
  286. ))
  287. + "\n WHERE id = ? AND parent_session_id IS NOT NULL\n"
  288. " AND EXISTS (\n"
  289. " SELECT 1 FROM sessions p\n"
  290. " WHERE p.id = sessions.parent_session_id\n"
  291. " AND p.end_reason = 'compression'\n"
  292. " )"
  293. + _FORK_EDGE_EXCLUSION_SQL
  294. )
  295. class SessionSessionsMixin:
  296. """Session rows: create/inherit, lifecycle flags, model_config, listing, deletion."""
  297. def _own_profile_name(self) -> Optional[str]:
  298. """The profile owning THIS store, from ``db_path`` alone (``<root>/state.db`` → default,
  299. ``<root>/profiles/<name>/state.db`` → name): a gateway serving a NON-launch profile opens that
  300. profile's store. None outside the profile tree — NULL beats a fabricated owner."""
  301. try:
  302. from hermes_constants import get_default_hermes_root
  303. root = get_default_hermes_root().resolve()
  304. parent = Path(self.db_path).resolve().parent
  305. if parent == root:
  306. return "default"
  307. is_profile_dir = parent.parent == root / "profiles"
  308. if is_profile_dir and re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,63}", parent.name):
  309. return parent.name
  310. except Exception:
  311. logger.debug("own-profile derivation failed", exc_info=True)
  312. return None
  313. @staticmethod
  314. def _inherit_parent_session_metadata(conn, session_id: str) -> None:
  315. """NULL-fill a child's cwd/git/profile from its parent (profile_name only within the same
  316. ``agent:<ns>:`` namespace). Gateway routing columns are inherited ONLY by compression forks
  317. (a crash before the gateway re-records the peer would strand the child unroutable); delegate
  318. and branch children must NOT inherit them (peer recovery could repoint traffic into a
  319. subagent's session), including when their parent row itself ended on compression — a long
  320. batch outlives its coordinator's rotation, and two live rows holding one routing key is the
  321. shape reported in #92859."""
  322. conn.execute(_INHERIT_PARENT_META_SQL, (session_id,))
  323. conn.execute(_INHERIT_PARENT_ROUTING_SQL, (session_id,))
  324. def _insert_session_row(
  325. self, session_id: str, source: str, model: str | None = None, model_config: dict[str, Any] | None = None,
  326. system_prompt: str | None = None, user_id: str | None = None, session_key: Optional[str] = None,
  327. chat_id: str | None = None, chat_type: str | None = None, thread_id: str | None = None,
  328. parent_session_id: str | None = None, cwd: str | None = None, profile_name: Optional[str] = None,
  329. git_repo_root: str | None = None, origin_json: str | None = None, display_name: str | None = None,
  330. transport_profile: Optional[str] = None,
  331. ) -> None:
  332. """Upsert a session row, never overwriting what an earlier writer set (the gateway creates a
  333. bare row before create_session carries the real model/prompt) — the one exception is the
  334. token-accounting guard's placeholder ``source='unknown'``, which a later writer's real surface
  335. replaces (#111999): once minted, that placeholder otherwise labelled a real session anonymous
  336. for life, because this upsert is the only writer that could correct it. chat_id/thread_id scope gateway
  337. /resume (IDOR). Children backfill from the parent; a missing profile_name is stamped with THIS
  338. store's own (NULL reads as unowned).
  339. When ``parent_session_id`` is set (compression fork, delegate/subagent spawn, branch continuation)
  340. and this row's own ``cwd``/``git_repo_root``/ ``git_branch``/``profile_name`` are still NULL after
  341. the insert, they are backfilled from the parent row. Callers of ``create_session`` for a child
  342. session historically didn't propagate these fields themselves (e.g. the compression-fork path), so a
  343. lineage could silently lose its working directory and drop out of the project sidebar every time it
  344. forked (#64709), or lose its owning profile and be aggregated as "default" every time it rotated or
  345. branched (the cross-profile session-jump bug). This only fills NULLs — an explicit value on the
  346. child is never overwritten. For compression forks specifically (parent ended with
  347. ``end_reason='compression'``), the gateway origin columns
  348. (``user_id``/``session_key``/``chat_id``/``chat_type``/
  349. ``thread_id``/``display_name``/``origin_json``) are inherited too, so a crash before the gateway
  350. re-records the peer can't strand the child without a recoverable routing mapping (#59527).
  351. When the caller passes no ``profile_name`` at all, the row is stamped with THIS store's own profile
  352. (:meth:`_own_profile_name`) instead of NULL. Every ``state.db`` belongs to exactly one profile — the
  353. same single-match contract :meth:`backfill_null_session_profiles` relies on — so the stamp is
  354. derivation, not a guess. Rows minted NULL after that one-shot #94724 backfill ran stayed NULL
  355. forever, and profile-keyed consumers (desktop sidebar scope matching, ``@session:<profile>/<id>``
  356. deep links, the fail-closed owner ladder) treat NULL as unowned: the session vanishes from the
  357. sidebar even though its transcript is intact (#99222). Stores outside the profile tree (explicit
  358. ``db_path`` in tests, ad-hoc copies) derive nothing and keep NULL — never guess.
  359. """
  360. from hermes_state_worker_lifecycle import insert_session_row_in_transaction
  361. params = dict(session_id=session_id, source=source, model=model, model_config=model_config,
  362. system_prompt=system_prompt, user_id=user_id, session_key=session_key,
  363. chat_id=chat_id, chat_type=chat_type, thread_id=thread_id,
  364. parent_session_id=parent_session_id, cwd=cwd, profile_name=profile_name,
  365. git_repo_root=git_repo_root, origin_json=origin_json, display_name=display_name,
  366. transport_profile=transport_profile)
  367. self._execute_write(lambda conn: insert_session_row_in_transaction(self, conn, **params),
  368. patience_s=self._TRANSCRIPT_WRITE_PATIENCE_S)
  369. def create_session(self, session_id: str, source: str, **kwargs) -> str:
  370. """Create (upsert) a session record. Returns the session_id."""
  371. self._insert_session_row(session_id, source, **kwargs)
  372. return session_id
  373. def ensure_session(self, session_id: str, source: str = "unknown", model: str | None = None, **kwargs) -> str:
  374. """Ensure a session row exists (upsert). Accepts optional kwargs."""
  375. self._insert_session_row(session_id, source, model=model, **kwargs)
  376. return session_id
  377. def set_expiry_finalized(self, session_id: str, finalized: bool = True) -> None:
  378. """Mirror ``SessionEntry.expiry_finalized`` so it survives a lost sessions.json.
  379. See #9006.
  380. """
  381. if not session_id:
  382. return
  383. self._write_sql(
  384. "UPDATE sessions SET expiry_finalized = ? WHERE id = ?", (1 if finalized else 0, session_id),
  385. )
  386. def find_session_by_origin(
  387. self, *, platform: str, chat_id: str, thread_id: Optional[str] = None,
  388. user_id: Optional[str] = None,
  389. ) -> Optional[str]:
  390. """Most recent live session_id for source + chat_id (+ thread_id). With ``user_id`` exact sender
  391. matches win; several distinct users and no match → None (never another participant's session)."""
  392. if not platform or chat_id in (None, ""):
  393. return None
  394. query = """
  395. SELECT id, user_id, started_at FROM sessions
  396. WHERE LOWER(source) = LOWER(?)
  397. AND session_key IS NOT NULL
  398. AND chat_id = ?
  399. AND ended_at IS NULL
  400. """
  401. params: list = [platform, str(chat_id)]
  402. if thread_id is not None:
  403. query += " AND COALESCE(thread_id, '') = ?"
  404. params.append(str(thread_id))
  405. rows = [dict(r) for r in self._read_all(query + " ORDER BY started_at DESC", params)]
  406. if not rows:
  407. return None
  408. if user_id:
  409. exact = [r for r in rows if str(r.get("user_id") or "") == str(user_id)]
  410. if exact:
  411. return str(exact[0]["id"])
  412. if len(rows) > 1:
  413. return None
  414. elif len({u for u in (str(r.get("user_id") or "").strip() for r in rows) if u}) > 1:
  415. return None
  416. return str(rows[0]["id"])
  417. # Orphaned gateway-session repair: widest plausible gap between a keyed predecessor going
  418. # quiet and its unkeyed successor (incident was ~60s; 15 min without spanning conversations).
  419. _ORPHAN_ADOPTION_MAX_GAP_S = 900.0
  420. # Children that are NOT compression continuations (see _non_continuation_child_sql); presence-
  421. # matching misclassified inherited markers as delegates. Callers bind the parent id three times.
  422. _NON_CONTINUATION_CHILD_FILTER_SQL = _non_continuation_child_sql("{alias}")
  423. def end_session(self, session_id: str, end_reason: str) -> None:
  424. """Mark a session ended; the first end_reason wins (a compression split must keep
  425. ``'compression'`` even if a stale end_session() lands later); reopen_session() to re-end."""
  426. self._execute_write(lambda conn: self._end_and_bump(
  427. conn, "UPDATE sessions SET ended_at = ?, end_reason = ? WHERE id = ? AND ended_at IS NULL",
  428. (time.time(), end_reason, session_id), session_id, end_reason,
  429. ))
  430. def _end_and_bump(self, conn, sql: str, params: tuple, session_id: str, reason: str) -> int:
  431. """Run an end-stamp UPDATE; only a boundary this call actually wrote advances the
  432. conversation generation (a no-op must not rotate the peer). Returns rowcount."""
  433. changed = conn.execute(sql, params).rowcount
  434. if changed:
  435. self._bump_conversation_generation(conn, session_id, reason)
  436. return changed
  437. @staticmethod
  438. def _retire_undrained_queue_rows_conn(conn, session_id: str) -> int:
  439. """The still-marked == never-drained accept-row UPDATE (#125577), on a caller's connection."""
  440. return conn.execute(
  441. "UPDATE messages SET active = 0 "
  442. "WHERE session_id = ? AND role = 'user' AND active = 1 "
  443. f"AND COALESCE({_sql_json_extract('display_metadata', '$.' + QUEUED_PROMPT_METADATA_KEY)}, 0) = 1",
  444. (session_id,),
  445. ).rowcount
  446. def retire_undrained_queue_rows(self, session_id: str) -> int:
  447. """Deactivate busy-queue accept rows that never drained (#125577): a restart discarded the
  448. in-memory queue, so nothing re-placed/deactivated the row written at accept time and
  449. alternation repair would glue the never-run prompt into the previous turn's user message.
  450. The drain's replacement row carries no marker, so still-marked == never drained; a
  451. dispatched-then-interrupted turn's row is never marked (its discard is handled in-process,
  452. #123532). Deactivated, never deleted — the row stays as history.
  453. Split out of :meth:`reopen_session` so the read-only mount paths (#85303: resume,
  454. lazy watch, hydration) can retire stale accept rows WITHOUT clearing ``ended_at`` —
  455. after a restart the marked row would otherwise stay active and visible on every
  456. mount until the next send. Idempotent; returns the number of rows retired.
  457. """
  458. return self._execute_write(
  459. lambda conn: self._retire_undrained_queue_rows_conn(conn, session_id))
  460. def reopen_session(self, session_id: str) -> None:
  461. """Clear ended_at/end_reason so a session can be resumed; first freeze markerless legacy reset
  462. children, skipping explicit fork/delegate provenance and children that predate the parent itself.
  463. The guard compares against the parent's started_at, not its current ended_at: a parent that was
  464. reopened and re-ended later still owns reset children from its earlier boundaries."""
  465. def _do(conn):
  466. self._retire_undrained_queue_rows_conn(conn, session_id)
  467. conn.execute(
  468. "UPDATE sessions AS child SET model_config = json_set("
  469. "COALESCE(child.model_config, '{}'), '$._reset_from', child.parent_session_id) "
  470. f"WHERE child.parent_session_id = ? AND {_sql_json_extract('child.model_config', '$._reset_from')} IS NULL "
  471. f"AND {_sql_json_extract('child.model_config', '$._branched_from')} IS NULL "
  472. f"AND {_sql_json_extract('child.model_config', '$._delegate_from')} IS NULL "
  473. "AND COALESCE(child.source, '') != 'tool' "
  474. "AND child.started_at >= (SELECT p.started_at FROM sessions p WHERE p.id = child.parent_session_id) "
  475. f"AND {_legacy_reset_child_sql('child', _session_ids_placeholders(_RESET_END_REASONS))}",
  476. (session_id, *_RESET_END_REASONS),
  477. )
  478. conn.execute(
  479. "UPDATE sessions SET ended_at = NULL, end_reason = NULL WHERE id = ?", (session_id,),
  480. )
  481. # Resuming re-activates the chat: drop the idle sweep's archive (never a manual one).
  482. self._unarchive_auto_archived_lineage(conn, session_id)
  483. self._execute_write(_do)
  484. def promote_to_session_reset(self, session_id: str, reason: str = "session_reset") -> bool:
  485. """Durably mark an intentional reset boundary on live rows or rows with a *recoverable* accidental
  486. end_reason (explicit boundaries are preserved): an ``agent_close`` row left recoverable would be
  487. resurrected by stale-route recovery. Keep in sync with find_latest_gateway_session_for_peer.
  488. Plain ``end_session()`` is NOT sufficient for reset boundaries: it no-ops on an already-ended row,
  489. so a row that agent cleanup already closed as ``agent_close`` would stay recoverable and stale-route
  490. recovery would resurrect the reset session with its full history (#61220, #61993, #63539).
  491. """
  492. if not session_id:
  493. return False
  494. now = time.time()
  495. # /new and policy auto-resets promote rather than end_session, so the
  496. # generation advances here too — same transaction, only when written.
  497. try:
  498. return bool(self._execute_write(lambda conn: self._end_and_bump(
  499. conn, "UPDATE sessions SET ended_at = ?, end_reason = ? WHERE id = ? AND (ended_at IS NULL "
  500. f"OR end_reason IN ({_RECOVERABLE_END_REASONS_SQL}))",
  501. (now, reason, session_id), session_id, reason,
  502. )))
  503. except Exception:
  504. return False
  505. def update_session_cwd(
  506. self, session_id: str, cwd: str, git_branch: Optional[str] = None,
  507. git_repo_root: Optional[str] = None, replace_git_meta: bool = False,
  508. ) -> Optional[int]:
  509. """Persist the authoritative cwd and claim a Git metadata generation. git fields are written
  510. only when non-empty (a probe failure never clobbers a value) except under ``replace_git_meta``
  511. (a workspace MOVE overwrites the old repo identity). Async probes publish with the returned
  512. generation so an older worker cannot overwrite a newer claim (A -> B -> A)."""
  513. if not session_id or not cwd:
  514. return None
  515. branch = (git_branch or "").strip()
  516. repo_root = (git_repo_root or "").strip()
  517. def _do(conn):
  518. current = conn.execute("SELECT cwd FROM sessions WHERE id = ?", (session_id,)).fetchone()
  519. if current is None:
  520. return None
  521. sets = ["cwd = ?", "git_metadata_generation = COALESCE(git_metadata_generation, 0) + 1"]
  522. params: list[Any] = [cwd]
  523. if current[0] != cwd or replace_git_meta:
  524. sets.extend(("git_branch = ?", "git_repo_root = ?"))
  525. params.extend((branch or None, repo_root or None))
  526. else: # same cwd: only overwrite with captured (non-empty) values
  527. for col, val in (("git_branch", branch), ("git_repo_root", repo_root)):
  528. if val:
  529. sets.append(f"{col} = ?")
  530. params.append(val)
  531. conn.execute(f"UPDATE sessions SET {', '.join(sets)} WHERE id = ?", [*params, session_id])
  532. row = conn.execute(
  533. "SELECT git_metadata_generation FROM sessions WHERE id = ?", (session_id,),
  534. ).fetchone()
  535. return None if row is None else int(row[0])
  536. return self._execute_write(_do)
  537. def publish_session_git_metadata(
  538. self, session_id: str, cwd: str, generation: int, git_branch: Optional[str] = None,
  539. git_repo_root: Optional[str] = None,
  540. ) -> bool:
  541. """Publish async Git enrichment only while its cwd claim is current."""
  542. valid_generation = isinstance(generation, int) and not isinstance(generation, bool) and generation >= 1
  543. if not session_id or not cwd or not valid_generation:
  544. return False
  545. fields = [
  546. (col, val) for col, val in (
  547. ("git_branch", (git_branch or "").strip()), ("git_repo_root", (git_repo_root or "").strip()),
  548. ) if val
  549. ]
  550. if not fields:
  551. return False
  552. return self._write_rowcount(
  553. f"UPDATE sessions SET {', '.join(f'{col} = ?' for col, _ in fields)} "
  554. "WHERE id = ? AND cwd = ? AND git_metadata_generation = ?",
  555. [val for _, val in fields] + [session_id, cwd, generation],
  556. ) == 1
  557. def backfill_repo_roots(self, cwd_to_root: dict[str, str]) -> None:
  558. """Backfill git repo roots for cwds without one; never clobbers a recorded root."""
  559. pairs = [(root, cwd) for cwd, root in cwd_to_root.items() if root and cwd]
  560. if pairs:
  561. self._write_sql(
  562. "UPDATE sessions SET git_repo_root = ? WHERE cwd = ? AND COALESCE(git_repo_root, '') = ''",
  563. pairs, many=True,
  564. )
  565. def touch_session_activity(
  566. self, session_id: str, ts: Optional[float] = None, *, description: Optional[str] = None,
  567. provenance: Optional[ActivityProvenance] = None,
  568. ) -> None:
  569. """Stamp durable mid-turn activity (observation-only; rate-limited by the caller) so surfaces see
  570. activity before any message row lands. Never moves ``last_activity_at`` backwards.
  571. Called (rate-limited) from ``AIAgent._touch_activity`` so gateway/CLI surfaces and stall consumers
  572. observe API/tool/compaction activity even when no new message row has been written yet (#72016 /
  573. #72039).
  574. """
  575. if not session_id:
  576. return
  577. when = float(ts if ts is not None else time.time())
  578. self._write_sql(
  579. "UPDATE sessions SET last_activity_at = ?, "
  580. "last_activity_description = ?, last_activity_provenance = ? "
  581. "WHERE id = ? AND (last_activity_at IS NULL OR last_activity_at < ?)",
  582. (
  583. when, bound_activity_description(description),
  584. normalize_activity_provenance(provenance).value, session_id, when,
  585. ),
  586. patience_s=self._ACTIVITY_WRITE_PATIENCE_S,
  587. )
  588. # Observation-only write: never let it ride the full routine write-patience budget (#76354 review S1).
  589. # Under contention a heartbeat that waits ~20s would delay the response-critical path it is merely
  590. # observing; give up after a sub-second budget instead (the next due window retries naturally).
  591. def clear_session_activity_labels(self, session_id: str) -> None:
  592. """Clear activity labels after a turn (``last_activity_at`` is kept so idle / watchdog clocks stay
  593. continuous). A no-op clear skips the write transaction.
  594. Description and provenance are observation labels for *what was happening at* that timestamp during
  595. an active turn; once the turn is idle they must not keep advertising "compressing" / "executing
  596. tool" (#72039).
  597. Response-critical-path contract (#76354 review S1): runs in the turn's ``finally``; a no-op clear
  598. (labels already empty) skips the write transaction entirely, and a real clear uses the same short
  599. sub-second busy budget as :meth:`touch_session_activity` instead of the full routine write patience.
  600. """
  601. if not session_id:
  602. return
  603. try:
  604. row = self._read_one(
  605. "SELECT last_activity_description, last_activity_provenance FROM sessions WHERE id = ?",
  606. (session_id,),
  607. )
  608. except sqlite3.Error:
  609. row = None
  610. if row is not None and not row[0] and (not row[1] or row[1] == ActivityProvenance.UNKNOWN.value):
  611. return
  612. self._write_sql(
  613. "UPDATE sessions SET last_activity_description = ?, last_activity_provenance = ? WHERE id = ?",
  614. ("", ActivityProvenance.UNKNOWN.value, session_id), patience_s=self._ACTIVITY_WRITE_PATIENCE_S,
  615. )
  616. def update_session_meta(
  617. self, session_id: str, model_config_json: str, model: Optional[str] = None,
  618. ) -> None:
  619. """Update model_config and (COALESCE) optionally model."""
  620. self.flush_token_counts() # barrier against queued token deltas — see update_session_model
  621. self._write_sql(
  622. "UPDATE sessions SET model_config = ?, model = COALESCE(?, model) WHERE id = ?",
  623. (model_config_json, model, session_id),
  624. )
  625. def update_system_prompt(self, session_id: str, system_prompt: Optional[str]) -> None:
  626. """Store the full assembled system prompt snapshot."""
  627. def _do(conn):
  628. conn.execute(
  629. "UPDATE sessions SET system_prompt_hash = ?, system_prompt = NULL WHERE id = ?",
  630. (self._store_system_prompt(conn, system_prompt), session_id),
  631. )
  632. self._delete_unreferenced_system_prompts(conn)
  633. self._execute_write(_do)
  634. def update_session_tool_names(self, session_id: str, pin: Any) -> None:
  635. """Persist the session's ``tools[]`` pin (JSON-serializable) so a rebuilt AIAgent sends the
  636. same bytes; ``None`` clears. The array repeats across sessions like a system prompt does, so it
  637. is stored in the same content-addressed ``system_prompts`` table and the column holds its hash
  638. (legacy rows: an inline JSON name list); ``get_session`` resolves either."""
  639. payload = json.dumps(pin) if pin is not None else None
  640. def _do(conn):
  641. conn.execute("UPDATE sessions SET tool_names = ? WHERE id = ?",
  642. (self._store_system_prompt(conn, payload), session_id))
  643. self._delete_unreferenced_system_prompts(conn)
  644. self._execute_write(_do)
  645. def update_session_model(
  646. self, session_id: str, model: str, provider: Optional[str] = None, *,
  647. base_url: Optional[str] = None, api_mode: Optional[str] = None,
  648. ) -> None:
  649. """Set the model after a mid-session /model switch (unconditionally) and drop any Browser
  650. runtime lock (lineage markers survive).
  651. Route writers never touch the stored prompt; ``_stored_prompt_matches_runtime`` decides staleness.
  652. When *provider* is given the whole route is written, in both shapes resume reads (top-level
  653. keys for the TUI/Desktop, ``gateway_runtime`` for the CLI), so a later resume recombines the
  654. model with the provider that serves it (#79536). ``base_url``/``api_mode`` are always
  655. replaced then (``None`` deletes): the previous provider's endpoint must not survive a switch,
  656. or resume sends the new provider's model to the old host. Callers without provider knowledge
  657. leave the stored route untouched.
  658. """
  659. # Flush first: a still-queued pre-switch delta applied after this UPDATE would trip the
  660. # first_accounted_route overwrite and resurrect the old route.
  661. self.flush_token_counts()
  662. patch: dict[str, Any] = {"browser_model_lock": None}
  663. if model:
  664. patch["model"] = model
  665. if provider:
  666. route = {"provider": provider, "base_url": base_url or None, "api_mode": api_mode or None}
  667. patch.update(route, gateway_runtime=route)
  668. self._write_model_config_patch(
  669. session_id, patch, "UPDATE sessions SET model = ?, model_config = ? WHERE id = ?",
  670. lambda merged: (model, merged, session_id),
  671. )
  672. def _write_model_config_patch(
  673. self, session_id: str, patch: dict[str, Any],
  674. sql: str = "UPDATE sessions SET model_config = ? WHERE id = ?",
  675. params: Optional[Callable[[Optional[str]], tuple]] = None,
  676. ) -> None:
  677. """Merge ``patch`` into model_config then run ``sql`` with ``params(merged)`` in one write
  678. transaction; no-op when the row doesn't exist."""
  679. def _do(conn):
  680. merged = self._merge_model_config_json(conn, session_id, patch)
  681. if merged is _MODEL_CONFIG_ROW_MISSING:
  682. return
  683. conn.execute(sql, params(merged) if params else (merged, session_id))
  684. self._execute_write(_do)
  685. def _merge_model_config_json(
  686. self, conn, session_id: str, patch: dict[str, Any], *, on_missing: str = "skip",
  687. ):
  688. """SELECT + tolerant-parse + merge ``patch`` into model_config (the one place that keeps
  689. ``_branched_from``/``_delegate_from`` alive); ``None`` deletes a key. Returns serialized JSON
  690. (``None`` when empty) or ``_MODEL_CONFIG_ROW_MISSING`` (``on_missing="raise"`` → ValueError)."""
  691. row = conn.execute("SELECT model_config FROM sessions WHERE id = ?", (session_id,)).fetchone()
  692. if row is None:
  693. if on_missing == "raise":
  694. raise ValueError(f"Session not found: {session_id}")
  695. return _MODEL_CONFIG_ROW_MISSING
  696. config = _parse_model_config(row[0])
  697. for key, value in patch.items():
  698. if value is None:
  699. config.pop(key, None)
  700. else:
  701. config[key] = value
  702. return json.dumps(config) if config else None
  703. def patch_session_model_config(self, session_id: str, patch: dict[str, Any]) -> None:
  704. """Merge ``patch`` into model_config atomically (``None`` removes a key);
  705. no-op when the row or patch is empty."""
  706. if not session_id or not patch:
  707. return
  708. self._write_model_config_patch(session_id, patch)
  709. def get_session_model_config_value(self, session_id: str, key: str, default: Any = None) -> Any:
  710. """Read one key out of a session's model_config JSON (tolerant parse)."""
  711. session = self.get_session(session_id) or {}
  712. return _parse_model_config(session.get("model_config")).get(key, default)
  713. def update_conversation_model_config_value(self, session_id: str, key: str,
  714. update: Callable[[Any], Any]) -> Optional[str]:
  715. """Write ``update(value)`` of a conversation-wide key at the compression tip (one transaction)."""
  716. from hermes_state_sessions_model_config import update_conversation_model_config_value
  717. return update_conversation_model_config_value(self, session_id, key, update)
  718. def session_ids_with_model_config_key(self, key: str) -> list[str]:
  719. """Ids of the sessions whose model_config carries ``key``, newest first."""
  720. from hermes_state_sessions_model_config import session_ids_with_model_config_key
  721. return session_ids_with_model_config_key(self, key)
  722. def update_session_runtime_lock(
  723. self, session_id: str, *, model: Optional[str] = None, provider: Optional[str] = None,
  724. model_options: Optional[dict[str, Any]] = None, route_source: Optional[str] = None,
  725. confirmed: bool = False,
  726. ) -> None:
  727. """Persist a Browser / API-client runtime lock into model_config (lineage markers survive).
  728. Route writers never touch the stored prompt; ``_stored_prompt_matches_runtime`` decides staleness."""
  729. lock = {
  730. "provider": provider or "", "model": model or "", "model_options": model_options or {},
  731. "route_source": route_source or "", "confirmed": bool(confirmed), "updated_at": time.time(),
  732. }
  733. self._write_model_config_patch(
  734. session_id, {"browser_model_lock": lock},
  735. """UPDATE sessions SET
  736. model_config = ?,
  737. model = COALESCE(?, model)
  738. WHERE id = ?""",
  739. lambda merged: (merged, model, session_id),
  740. )
  741. def set_session_yolo(self, session_id: str, enabled: bool) -> None:
  742. """Persist the per-session YOLO flag so ``/yolo`` survives ``--resume``; no-op without a row."""
  743. if not session_id:
  744. return
  745. self._write_model_config_patch(session_id, {"yolo_mode": bool(enabled)})
  746. @staticmethod
  747. def session_yolo_enabled(session_meta: Optional[dict[str, Any]]) -> bool:
  748. """Persisted YOLO flag; False on any parse failure (resume must never enable the bypass)."""
  749. return bool(_parse_model_config((session_meta or {}).get("model_config")).get("yolo_mode"))
  750. def get_session(self, session_id: str) -> Optional[dict[str, Any]]:
  751. """Get a session by ID (drains queued token deltas first so cost readers see exact totals)."""
  752. self.flush_for_read()
  753. row = self._read_one(
  754. "SELECT s.*, COALESCE(sp.prompt, s.system_prompt) AS _system_prompt_resolved, "
  755. "COALESCE(tp.prompt, s.tool_names) AS _tool_names_resolved "
  756. "FROM sessions s LEFT JOIN system_prompts sp ON sp.hash = s.system_prompt_hash "
  757. "LEFT JOIN system_prompts tp ON tp.hash = s.tool_names WHERE s.id = ?",
  758. (session_id,),
  759. )
  760. return self._session_row_dict(row) if row else None
  761. def get_session_list_row(self, session_id: str) -> Optional[dict[str, Any]]:
  762. """Picker columns only: the live listing skips ``get_session``'s prompt/tool JOIN and flush."""
  763. row = self._read_one(
  764. "SELECT id, source, title, started_at, ended_at, message_count, model, hidden, archived "
  765. "FROM sessions WHERE id = ?",
  766. (session_id,),
  767. )
  768. return dict(row) if row else None
  769. def get_recent_session_model_route(self, session_id: str) -> Optional[dict[str, Any]]:
  770. """Most recently used main-loop model route as one coherent per-call tuple
  771. (``session_model_usage`` keeps model+provider together; ``sessions`` mixes route changes).
  772. Recency, not lifetime call count: on a long session a route retired weeks ago can hold the
  773. highest ``api_call_count`` forever, and /status and /usage would keep calling it current.
  774. ``rowid DESC`` breaks same-timestamp ties toward the route that first appeared later; without
  775. it SQLite's temp-sort order is unspecified and the retired route can win."""
  776. self.flush_for_read()
  777. row = self._read_one(
  778. """SELECT model, billing_provider, billing_base_url, billing_mode,
  779. api_call_count
  780. FROM session_model_usage
  781. WHERE session_id = ?
  782. AND task = ''
  783. AND model <> 'unknown'
  784. AND billing_provider <> ''
  785. ORDER BY last_seen DESC, rowid DESC
  786. LIMIT 1""",
  787. (session_id,),
  788. )
  789. return dict(row) if row else None
  790. def resolve_session_id(self, session_id_or_prefix: str) -> Optional[str]:
  791. """Exact id, else the single unambiguous prefix match, else None."""
  792. exact = self.get_session(session_id_or_prefix)
  793. if exact:
  794. return exact["id"]
  795. matches = self._read_all(
  796. "SELECT id FROM sessions WHERE id LIKE ? ESCAPE '\\' ORDER BY started_at DESC LIMIT 2",
  797. (f"{_escape_like(session_id_or_prefix)}%",),
  798. )
  799. return matches[0]["id"] if len(matches) == 1 else None
  800. def backfill_null_session_profiles(self, profile_name: str) -> int:
  801. """Stamp this store's own profile onto legacy ``profile_name IS NULL`` rows, which the fail-closed
  802. owner ladder cannot route. Never overwrites a non-NULL owner. Returns rows stamped.
  803. Sessions created before the durable-ownership work (#95407 lineage) carry ``profile_name = NULL``.
  804. On single-backend installs that was harmless, but once a Desktop registers a second connection the
  805. fail-closed owner ladder (which is correct for new sessions) can no longer route those rows anywhere
  806. — every pre-campaign session becomes unresumable after upgrade (#94724, field report).
  807. """
  808. stamp = (profile_name or "").strip()
  809. if not stamp:
  810. return 0
  811. return int(self._write_rowcount(
  812. """UPDATE sessions
  813. SET profile_name = ?
  814. WHERE profile_name IS NULL OR TRIM(profile_name) = ''""",
  815. (stamp,),
  816. ) or 0)
  817. def backfill_acp_session_cwd(self) -> int:
  818. """Promote ``model_config.cwd`` into the cwd column for ACP rows lacking one.
  819. ACP sessions minted before the adapter populated the column still carry
  820. their workspace inside ``model_config``, written by the same adapter that
  821. knew the real directory — so this is a record being promoted, not a guess.
  822. Only fills NULL/empty; an explicit column value always wins. Returns the
  823. number of rows changed.
  824. """
  825. return int(self._write_rowcount(
  826. """UPDATE sessions
  827. SET cwd = json_extract(model_config, '$.cwd')
  828. WHERE source = 'acp'
  829. AND COALESCE(cwd, '') = ''
  830. AND json_valid(model_config)
  831. AND COALESCE(json_extract(model_config, '$.cwd'), '') != ''""",
  832. (),
  833. ) or 0)
  834. def _set_lineage_column(self, column: str, session_id: str, value: Any, *,
  835. extra_set_sql: str = "") -> bool:
  836. """Set one ``sessions`` column across a whole compression lineage: Desktop projects roots
  837. forward to their tip, so updating only the tip would let the root resurrect it on refresh.
  838. *extra_set_sql* (trusted literal, ``, col = expr``) rides the same UPDATE."""
  839. return bool(self._execute_write(
  840. lambda conn: self._set_lineage_column_in_transaction(
  841. conn, column, session_id, value, extra_set_sql=extra_set_sql)
  842. ))
  843. def _set_lineage_column_in_transaction(self, conn, column: str, session_id: str, value: Any, *,
  844. extra_set_sql: str = ""):
  845. """Return affected IDs so authority revisions share this exact lineage selector. A plain
  846. ``archived`` write (canonical mutation, user/CLI/API) is the DELIBERATE archive and clears
  847. the idle sweep's ``auto_archived`` provenance, same as :meth:`set_session_archived`."""
  848. if column == "archived" and not extra_set_sql:
  849. extra_set_sql = ", auto_archived = 0"
  850. return [row[0] for row in conn.execute(
  851. _LINEAGE_CTE_SQL + f"""
  852. UPDATE sessions
  853. SET {column} = ?{extra_set_sql}
  854. WHERE id IN (SELECT id FROM lineage)
  855. RETURNING id
  856. """,
  857. (session_id, session_id, value),
  858. ).fetchall()]
  859. def set_session_archived(self, session_id: str, archived: bool, *, notify: bool = True) -> bool:
  860. """Soft-hide (or unhide) a session and its compression lineage; messages are kept.
  861. This is the DELIBERATE archive (user, CLI, API): it clears the ``auto_archived``
  862. provenance, so re-activation never un-hides it on the user's behalf. A real
  863. unarchived -> archived flip fires ``on_session_delete`` (``reason="archive"``) after commit;
  864. ``notify=False`` is for housekeeping that hides a row whose session lives on elsewhere."""
  865. def _do(conn):
  866. row = conn.execute("SELECT archived FROM sessions WHERE id = ?", (session_id,)).fetchone()
  867. ids = self._set_lineage_column_in_transaction(
  868. conn, "archived", session_id, int(archived), extra_set_sql=", auto_archived = 0")
  869. return ids, bool(archived and ids and row is not None and not row[0])
  870. ids, newly_archived = self._execute_write(_do)
  871. if newly_archived and notify:
  872. emit_session_deleted(self, ids, reason="archive", primary=session_id)
  873. return bool(ids)
  874. def _auto_archive_lineage(self, session_id: str) -> bool:
  875. """The idle sweep's archive: like :meth:`set_session_archived` but stamps
  876. ``auto_archived`` on the rows IT hides. A row already archived keeps its provenance, so a
  877. deliberately archived ancestor is never relabelled as sweep-owned (SQLite evaluates every
  878. SET expression against the pre-update row)."""
  879. return self._set_lineage_column(
  880. "archived", session_id, 1,
  881. extra_set_sql=", auto_archived = CASE WHEN archived = 0 THEN 1 ELSE auto_archived END")
  882. @staticmethod
  883. def _unarchive_auto_archived_lineage(conn, session_id: str) -> bool:
  884. """Un-hide a lineage the idle sweep archived, on *conn* (caller's write txn). A tip that is
  885. published (compression) or reopened (resume) under it is live again, and the listing admits
  886. a lineage by its ROOT's flag, so leaving the sweep's stamp would hide an active chat (#117713).
  887. A lineage with ANY deliberately archived row (``archived = 1 AND auto_archived = 0``) is left
  888. alone: a manual archive stays until the user un-archives it. True when rows were un-hidden."""
  889. params = (session_id, session_id)
  890. manual = conn.execute(
  891. _LINEAGE_CTE_SQL + """
  892. SELECT 1 FROM sessions
  893. WHERE id IN (SELECT id FROM lineage) AND archived <> 0 AND COALESCE(auto_archived, 0) = 0
  894. LIMIT 1
  895. """, params).fetchone()
  896. if manual is not None:
  897. return False
  898. return conn.execute(
  899. _LINEAGE_CTE_SQL + """
  900. UPDATE sessions SET archived = 0, auto_archived = 0
  901. WHERE id IN (SELECT id FROM lineage) AND archived <> 0
  902. """, params).rowcount > 0
  903. # Accidental end reasons recovery treats as resumable (also interpolated into
  904. # the recovery/promotion SQL so literals cannot drift).
  905. RECOVERABLE_END_REASONS = _RECOVERABLE_END_REASONS
  906. def unarchive_recoverable_session(self, session_id: str) -> bool:
  907. """Un-archive a session archived by a recoverable accident (ws_orphan_reap, agent_close);
  908. deliberate archives are left alone. True when un-archived.
  909. Registry-style lookups (Bot Mode's canonical "Bot Chat") use this to resurrect a row the ws-orphan
  910. reaper (``ws_orphan_reap``) or older agent cleanup (``agent_close``) archived: those ends are
  911. accidents, not user intent, so the identity-scoped canonical chat must survive them (#92687).
  912. Sessions archived with no end_reason or an explicit boundary reason (user archived deliberately,
  913. ``session_reset``, …) are left untouched — returns ``False`` for those, ``True`` only when the row
  914. was archived for a recoverable reason and is now un-archived (whole compression lineage, via
  915. :meth:`set_session_archived`).
  916. """
  917. if not session_id:
  918. return False
  919. try:
  920. row = self.get_session(session_id)
  921. except Exception:
  922. return False
  923. if not row or not row.get("archived"):
  924. return False
  925. # The accidental stamp lives on the live TIP; judge recoverability there.
  926. tip = row
  927. try:
  928. tip_id = self.get_compression_tip(session_id) or session_id
  929. if tip_id != session_id:
  930. tip = self.get_session(tip_id) or row
  931. except Exception:
  932. pass
  933. if (tip.get("end_reason") or "") not in self.RECOVERABLE_END_REASONS:
  934. return False
  935. if not self.set_session_archived(session_id, False):
  936. return False
  937. # Clear the accidental end stamp, or a LATER deliberate archive (which never
  938. # writes end_reason) would auto-resurrect on the next lookup.
  939. self._write_sql(
  940. "UPDATE sessions SET ended_at = NULL, end_reason = NULL WHERE id = ?", (tip["id"],),
  941. )
  942. return True
  943. def set_session_pinned(self, session_id: str, pinned: bool) -> bool:
  944. """Pin/unpin a session and its compression lineage (pins are exempt from the auto_archive sweep).
  945. Pinning also clears ``hidden``: a pin means "keep this visible", and a hidden+pinned row is
  946. otherwise absent from both the default listing and the pinned back-fill (see #106171).
  947. Exempt the canonical Bot Chat (hidden + exact registry title): the desktop contract keeps it
  948. hidden and reachable only through the bot row, and unhiding it would also disable the
  949. rename guard in ``_set_session_title`` that protects its identity (see review on #106180)."""
  950. result = self._set_lineage_column("pinned", session_id, int(pinned))
  951. if pinned:
  952. row = self.get_session(session_id)
  953. is_canonical_bot_chat = bool(row) and bool(row.get("hidden")) and (
  954. (row.get("title") or "") == self.CANONICAL_BOT_CHAT_TITLE
  955. )
  956. if not is_canonical_bot_chat:
  957. self._set_lineage_column("hidden", session_id, 0)
  958. return result
  959. def set_session_hidden(self, session_id: str, hidden: bool) -> bool:
  960. """Hide/unhide a session and its compression lineage from the default listing; still resumable."""
  961. return self._set_lineage_column("hidden", session_id, int(hidden))
  962. def set_session_read(self, session_id: str, read: bool = True) -> bool:
  963. """Mark read/unread across the compression lineage. ``last_read_at`` is a watermark: unread when
  964. activity postdates it (no write on the message path). NULL = never tracked = read; 0 = unread."""
  965. return self._set_lineage_column("last_read_at", session_id, time.time() if read else 0.0)
  966. @staticmethod
  967. def session_unread(session_row: dict[str, Any]) -> bool:
  968. """Unread = activity postdates the ``last_read_at`` watermark (NULL = read)."""
  969. last_read = session_row.get("last_read_at")
  970. if last_read is None:
  971. return False
  972. last_active = session_row.get("last_active") or session_row.get("started_at")
  973. return float(last_active or 0) > float(last_read)
  974. # compact_rows excludes only payload-heavy blobs no list consumer renders.
  975. _SESSION_COMPACT_EXCLUDED = frozenset(
  976. {"system_prompt", "system_prompt_hash", "git_metadata_generation"}
  977. )
  978. _session_compact_cols_sql: Optional[str] = None
  979. @staticmethod
  980. def _chain_search_where(where_sql: str, id_needle: str, search_needle: str) -> tuple[str, list[Any]]:
  981. """Extend ``where_sql`` with the id_query / search_query filters: a row is admitted when its own
  982. id or any id in its forward compression chain matches (search also matches titles and a
  983. punctuation-stripped form so ``an94`` finds ``AN-94``); chain membership bounds the LIKE."""
  984. params: list[Any] = []
  985. clauses: list[str] = []
  986. def like(needle: str) -> str:
  987. return f"%{_escape_like(needle)}%"
  988. if id_needle:
  989. clauses.append(
  990. "EXISTS (SELECT 1 FROM chain cq WHERE cq.root_id = s.id"
  991. " AND LOWER(cq.cur_id) LIKE ? ESCAPE '\\')"
  992. )
  993. params.append(like(id_needle))
  994. if search_needle:
  995. compact_needle = re.sub(r"[\W_]+", "", search_needle)
  996. search_clause = (
  997. "EXISTS (SELECT 1 FROM chain cq JOIN sessions cs ON cs.id = cq.cur_id"
  998. " WHERE cq.root_id = s.id AND (LOWER(COALESCE(cs.title, '')) LIKE ? ESCAPE '\\'"
  999. " OR LOWER(cq.cur_id) LIKE ? ESCAPE '\\'"
  1000. )
  1001. params.extend([like(search_needle)] * 2)
  1002. if compact_needle:
  1003. search_clause += (
  1004. " OR REPLACE(REPLACE(REPLACE(REPLACE(LOWER(COALESCE(cs.title, '')),"
  1005. " '-', ''), '_', ''), '.', ''), ' ', '') LIKE ? ESCAPE '\\'"
  1006. )
  1007. params.append(like(compact_needle))
  1008. clauses.append(search_clause + "))")
  1009. if not clauses:
  1010. return where_sql, params
  1011. combined = " AND ".join(clauses)
  1012. return (f"{where_sql} AND {combined}" if where_sql else f"WHERE {combined}"), params
  1013. def list_recent_sessions_bounded(
  1014. self,
  1015. *,
  1016. limit: int = 20,
  1017. exclude_sources: list[str] | None = None,
  1018. timeout_seconds: float = 3.0,
  1019. candidate_limit: int | None = None,
  1020. lineage_limit: int | None = None,
  1021. ) -> list[dict[str, Any]]:
  1022. """Latency-bounded recent-conversation browse (``session_search()``): preselect a small candidate set
  1023. from the indexed durable activity timestamp (fallback ``started_at``), resolve only those across
  1024. compression ancestry/chains, then hydrate activity/previews for that bounded set. Lineage traversal
  1025. uses ``UNION`` plus a total-row ceiling so a corrupt cycle or a deep/branching lineage cannot defeat
  1026. the bound; a lineage that hits the ceiling before a terminal root/tip is omitted, not expanded.
  1027. A cooperative SQLite progress deadline interrupts sustained work past ``timeout_seconds`` and raises
  1028. ``TimeoutError`` (cheap statements may finish between callbacks). Supports only the agent-tool
  1029. browse filters; rich callers keep using :meth:`list_sessions_rich`."""
  1030. limit = max(1, int(limit))
  1031. timeout_seconds = max(0.0, float(timeout_seconds))
  1032. if candidate_limit is None:
  1033. candidate_limit = max(128, limit * 8)
  1034. candidate_limit = max(limit, min(int(candidate_limit), 2048))
  1035. if lineage_limit is None:
  1036. lineage_limit = min(8192, candidate_limit * 8)
  1037. lineage_limit = max(candidate_limit, min(int(lineage_limit), 8192))
  1038. candidate_clauses = [
  1039. "s.archived = 0",
  1040. "s.hidden = 0",
  1041. f"{_delegate_from_json('s.model_config')} IS NULL",
  1042. ]
  1043. candidate_params: list[Any] = []
  1044. if exclude_sources:
  1045. placeholders = ",".join("?" for _ in exclude_sources)
  1046. candidate_clauses.append(f"s.source NOT IN ({placeholders})")
  1047. candidate_params.extend(exclude_sources)
  1048. candidate_where = " AND ".join(candidate_clauses)
  1049. # A compression continuation is an implementation edge, unlike /new
  1050. # reset and /branch children which are independent user-visible
  1051. # conversations. The same predicate is used in both directions so a
  1052. # candidate tip maps to its logical root and the root maps back to the
  1053. # freshest live tip.
  1054. compression_parent_edge = f"""
  1055. parent.end_reason = 'compression'
  1056. AND child.parent_session_id = parent.id
  1057. AND json_extract(
  1058. COALESCE(child.model_config, '{{}}'), '$._branched_from'
  1059. ) IS NULL
  1060. AND {_delegate_from_json('child.model_config')} IS NULL
  1061. AND COALESCE(child.source, '') != 'tool'
  1062. """
  1063. query = f"""
  1064. WITH RECURSIVE
  1065. recent_candidates(id) AS (
  1066. SELECT s.id
  1067. FROM sessions s
  1068. WHERE {candidate_where}
  1069. ORDER BY COALESCE(s.last_activity_at, s.started_at) DESC,
  1070. s.started_at DESC, s.id DESC
  1071. LIMIT ?
  1072. ),
  1073. ancestors(candidate_id, cur_id) AS (
  1074. SELECT id, id FROM recent_candidates
  1075. UNION
  1076. SELECT a.candidate_id, parent.id
  1077. FROM ancestors a
  1078. JOIN sessions child ON child.id = a.cur_id
  1079. JOIN sessions parent ON {compression_parent_edge}
  1080. LIMIT ?
  1081. ),
  1082. candidate_roots(root_id) AS (
  1083. SELECT DISTINCT a.cur_id
  1084. FROM ancestors a
  1085. JOIN sessions child ON child.id = a.cur_id
  1086. WHERE NOT EXISTS (
  1087. SELECT 1
  1088. FROM sessions parent
  1089. WHERE {compression_parent_edge}
  1090. )
  1091. ),
  1092. chain(root_id, cur_id) AS (
  1093. SELECT root_id, root_id FROM candidate_roots
  1094. UNION
  1095. SELECT c.root_id, child.id
  1096. FROM chain c
  1097. JOIN sessions parent ON parent.id = c.cur_id
  1098. JOIN sessions child ON {compression_parent_edge}
  1099. LIMIT ?
  1100. ),
  1101. chain_rows AS (
  1102. SELECT
  1103. c.root_id,
  1104. c.cur_id,
  1105. {_sql_session_last_active_by_id('c.cur_id')} AS activity,
  1106. CASE WHEN EXISTS (
  1107. SELECT 1
  1108. FROM sessions parent
  1109. JOIN sessions child ON {compression_parent_edge}
  1110. WHERE parent.id = c.cur_id
  1111. ) THEN 0 ELSE 1 END AS is_tip
  1112. FROM chain c
  1113. ),
  1114. ranked_tips AS (
  1115. SELECT root_id, cur_id, activity,
  1116. ROW_NUMBER() OVER (
  1117. PARTITION BY root_id
  1118. ORDER BY activity DESC, cur_id DESC
  1119. ) AS rank_in_root
  1120. FROM chain_rows
  1121. WHERE is_tip = 1
  1122. )
  1123. SELECT
  1124. tip.id,
  1125. tip.source,
  1126. tip.model,
  1127. COALESCE(tip.title, s.title) AS title,
  1128. s.started_at AS started_at,
  1129. tip.ended_at,
  1130. tip.end_reason,
  1131. tip.message_count,
  1132. tip.tool_call_count,
  1133. rt.activity AS last_active,
  1134. {_sql_preview_raw('tip.id')},
  1135. CASE WHEN s.id != tip.id THEN s.id ELSE NULL END
  1136. AS _lineage_root_id
  1137. FROM ranked_tips rt
  1138. JOIN sessions s ON s.id = rt.root_id
  1139. JOIN sessions tip ON tip.id = rt.cur_id
  1140. WHERE rt.rank_in_root = 1
  1141. AND s.archived = 0
  1142. AND s.hidden = 0
  1143. AND {_LISTABLE_CHILD_SQL}
  1144. AND {_delegate_from_json('s.model_config')} IS NULL
  1145. ORDER BY rt.activity DESC, s.started_at DESC, tip.id DESC
  1146. LIMIT ?
  1147. """
  1148. params = candidate_params + [
  1149. candidate_limit,
  1150. lineage_limit,
  1151. lineage_limit,
  1152. limit,
  1153. ]
  1154. deadline = time.monotonic() + timeout_seconds
  1155. interrupted_by_deadline = False
  1156. def _deadline_progress_handler() -> int:
  1157. nonlocal interrupted_by_deadline
  1158. if time.monotonic() >= deadline:
  1159. interrupted_by_deadline = True
  1160. return 1
  1161. return 0
  1162. try:
  1163. with self._read_ctx() as conn:
  1164. conn.set_progress_handler(_deadline_progress_handler, 1000)
  1165. try:
  1166. rows = conn.execute(query, params).fetchall()
  1167. finally:
  1168. conn.set_progress_handler(None, 0)
  1169. except sqlite3.OperationalError as exc:
  1170. if interrupted_by_deadline and "interrupt" in str(exc).lower():
  1171. raise TimeoutError(
  1172. f"recent-session browse exceeded {timeout_seconds:g}s deadline"
  1173. ) from exc
  1174. raise
  1175. sessions = []
  1176. for row in rows:
  1177. session = self._session_row_dict(row)
  1178. session["preview"] = _shape_preview(session.pop("_preview_raw", ""))
  1179. session["unread"] = self.session_unread(session)
  1180. sessions.append(session)
  1181. return sessions
  1182. @classmethod
  1183. def _list_row(cls, row: sqlite3.Row) -> dict[str, Any]:
  1184. """Project a list_sessions_rich row: shape the preview, drop internal ordering columns."""
  1185. s = cls._session_row_dict(row)
  1186. s["preview"] = _shape_preview(s.pop("_preview_raw", ""))
  1187. s.pop("_effective_last_active", None)
  1188. return s
  1189. def list_sessions_rich(
  1190. self, source: str | None = None, sources: list[str] | None = None, exclude_sources: list[str] | None = None,
  1191. cwd_prefix: str | None = None, limit: int = 20, offset: int = 0, include_children: bool = False,
  1192. min_message_count: int = 0, project_compression_tips: bool = True,
  1193. order_by_last_active: bool = False, include_archived: bool = False, archived_only: bool = False,
  1194. id_query: str | None = None, search_query: str | None = None, compact_rows: bool = False,
  1195. include_pinned: bool = False, session_key: str | None = None, include_hidden: bool = False,
  1196. include_subagents: bool = False, local_created_sources: Sequence[str] | None = None,
  1197. ) -> list[dict[str, Any]]:
  1198. """List sessions with preview and ``last_active`` in one query. ``order_by_last_active`` sorts
  1199. by the chain TIP via a recursive CTE (the only path honouring ``id_query`` / ``search_query``);
  1200. ``include_pinned`` back-fills pins the page missed, still obeying the other
  1201. filters except archived: a pin is an explicit keep, so a pinned row stamped
  1202. archived must still return. ``local_created_sources`` restricts ``source='local'``
  1203. rows to those surfaces before LIMIT/OFFSET."""
  1204. self.flush_for_read() # rows carry token/cost totals
  1205. where_clauses, params = _session_filter_where(
  1206. exclude_children=not include_children, source=source, sources=sources, session_key=session_key,
  1207. exclude_sources=exclude_sources, cwd_prefix=cwd_prefix, min_message_count=min_message_count,
  1208. archived_only=archived_only, include_archived=include_archived, include_subagents=include_subagents,
  1209. local_created_sources=local_created_sources,
  1210. )
  1211. # The archived-only view is the recovery surface for rows that dropped out of every
  1212. # default list: a session that is archived AND hidden (Bot Mode marks its sessions
  1213. # hidden) must still be reachable there, or nothing but direct DB access can bring
  1214. # it back (#90946).
  1215. if not include_hidden and not archived_only:
  1216. where_clauses.append("s.hidden = 0")
  1217. heads = {}
  1218. from hermes_state_local import exclude_superseded_segments
  1219. if not include_children:
  1220. # A local reset lineage is one conversation (hermes_state_local.local_lineage_index):
  1221. # earlier segments leave the page in SQL, before LIMIT/OFFSET, not after it.
  1222. heads = exclude_superseded_segments(self, where_clauses, params)
  1223. where_sql = _where_sql(where_clauses)
  1224. # Shared projection head of the three list queries (whitespace is part of the SQL text).
  1225. select_head = (
  1226. f"SELECT {self._compact_session_cols() if compact_rows else 's.*'}"
  1227. + ("" if compact_rows else ", COALESCE(sp.prompt, s.system_prompt) AS _system_prompt_resolved")
  1228. + f",\n {_sql_preview_raw()},\n "
  1229. )
  1230. prompt_join = (
  1231. "" if compact_rows else "LEFT JOIN system_prompts sp ON sp.hash = s.system_prompt_hash"
  1232. )
  1233. from_sessions = f"FROM sessions s\n {prompt_join}"
  1234. if order_by_last_active:
  1235. # The CTE walks compression-continuation edges forward from the admitted
  1236. # rows; MAX over the chain gives effective_last_active in SQL. Do NOT
  1237. # require child.started_at >= parent.ended_at: races insert the
  1238. # continuation before ended_at is written.
  1239. #
  1240. # The page is ranked and cut on ids alone (``page``); only its rows then
  1241. # pay for the projection. Projecting in the ranked query made SQLite
  1242. # build every admitted row's full result — s.*, the resolved system
  1243. # prompt, the preview subquery over message content — before LIMIT:
  1244. # 4-11s per page at 25k rows, for LIMIT 1 as much as LIMIT 200.
  1245. #
  1246. # Unless a search needs every row's chain (it matches a row's own id and
  1247. # title through it), only rows that HAVE a child seed the walk. A
  1248. # childless row's chain is itself alone, so its MAX is just its own
  1249. # last_active, which the outer COALESCE reads directly. Seeding every
  1250. # admitted row made the CTE + GROUP BY materialise the whole table on
  1251. # every page: ~12s of a 13s list on a 25k-session store where 1 row had
  1252. # a child, at LIMIT 1 or 200.
  1253. id_needle = (id_query or "").strip().lower()
  1254. search_needle = (search_query or "").strip().lower()
  1255. seed_where = where_sql if (id_needle or search_needle) else _where_sql(where_clauses + [
  1256. "EXISTS (SELECT 1 FROM sessions _seed_c WHERE _seed_c.parent_session_id = s.id)"])
  1257. outer_where, id_params = self._chain_search_where(where_sql, id_needle, search_needle)
  1258. query = f"""
  1259. WITH RECURSIVE chain(root_id, cur_id) AS (
  1260. SELECT s.id, s.id FROM sessions s {seed_where}
  1261. UNION ALL
  1262. SELECT c.root_id, child.id
  1263. FROM chain c
  1264. JOIN sessions parent ON parent.id = c.cur_id
  1265. JOIN sessions child ON child.parent_session_id = c.cur_id
  1266. WHERE parent.end_reason = 'compression'
  1267. AND {_sql_json_extract('child.model_config', '$._branched_from')} IS NULL
  1268. AND {_sql_json_extract('child.model_config', '$._delegate_from')} IS NULL
  1269. AND NOT ({_RESET_CHILD_SQL.format(a='child')})
  1270. AND COALESCE(child.source, '') != 'tool'
  1271. ),
  1272. chain_max AS (
  1273. SELECT
  1274. root_id,
  1275. MAX({_sql_session_last_active_by_id("cur_id")}) AS effective_last_active
  1276. FROM chain
  1277. GROUP BY root_id
  1278. ),
  1279. page AS (
  1280. SELECT s.id AS page_id,
  1281. COALESCE(cm.effective_last_active, {_sql_session_last_active("s")},
  1282. {_sql_in_window("s.started_at")}) AS effective_last_active
  1283. FROM sessions s
  1284. LEFT JOIN chain_max cm ON cm.root_id = s.id
  1285. {outer_where}
  1286. ORDER BY effective_last_active DESC, s.started_at DESC, s.id DESC
  1287. LIMIT ? OFFSET ?
  1288. )
  1289. {select_head}{_sql_session_last_active("s")} AS last_active,
  1290. page.effective_last_active AS _effective_last_active
  1291. FROM page
  1292. JOIN sessions s ON s.id = page.page_id
  1293. {prompt_join}
  1294. ORDER BY _effective_last_active DESC, s.started_at DESC, s.id DESC
  1295. """
  1296. params = params + params + id_params + [limit, offset] # WHERE binds twice (seed + outer)
  1297. else:
  1298. query = f"""
  1299. {select_head}{_sql_session_last_active("s")} AS last_active
  1300. {from_sessions}
  1301. {where_sql}
  1302. ORDER BY s.started_at DESC
  1303. LIMIT ? OFFSET ?
  1304. """
  1305. params.extend([limit, offset])
  1306. sessions = [self._list_row(row) for row in self._read_all(query, params)]
  1307. # Pinned back-fill runs BEFORE compression projection so a back-filled root
  1308. # projects to its tip like any other row. Do not inherit the archived
  1309. # constraint: the sidebar lists with include_archived=False, and a pin
  1310. # must stay reachable even when that row is also archived.
  1311. if include_pinned:
  1312. seen_ids = {s["id"] for s in sessions}
  1313. pinned_clauses, pinned_params = _session_filter_where(
  1314. exclude_children=not include_children, source=source, sources=sources,
  1315. session_key=session_key, exclude_sources=exclude_sources, cwd_prefix=cwd_prefix,
  1316. min_message_count=min_message_count, archived_only=False, include_archived=True,
  1317. include_subagents=include_subagents, local_created_sources=local_created_sources,
  1318. )
  1319. if not include_hidden and not archived_only:
  1320. pinned_clauses.append("s.hidden = 0")
  1321. if heads:
  1322. exclude_superseded_segments(self, pinned_clauses, pinned_params)
  1323. pinned_clauses.append("s.pinned = 1")
  1324. pinned_where = _where_sql(pinned_clauses)
  1325. pinned_query = f"""
  1326. {select_head}{_sql_session_last_active("s")} AS last_active
  1327. {from_sessions}
  1328. {pinned_where}
  1329. ORDER BY s.started_at DESC
  1330. """
  1331. for row in self._read_all(pinned_query, pinned_params):
  1332. s = self._list_row(row)
  1333. if s["id"] not in seen_ids:
  1334. seen_ids.add(s["id"])
  1335. sessions.append(s)
  1336. if project_compression_tips and not include_children:
  1337. from hermes_state_session_list import project_compression_tips
  1338. sessions = project_compression_tips(self, sessions, compact_rows)
  1339. if heads:
  1340. from hermes_state_local import annotate_local_lineages
  1341. sessions = annotate_local_lineages(sessions, heads)
  1342. # last_read_at is lineage-stamped, so root and tip watermarks agree.
  1343. for s in sessions:
  1344. s["unread"] = self.session_unread(s)
  1345. return sessions
  1346. def session_lifecycle_statuses(self, session_ids: list[str]) -> dict[str, str]:
  1347. """``{session_id: status}`` from each session's LAST message row (``'empty'`` when none); one
  1348. query, MAX(id) per session joined back — never scans transcripts."""
  1349. ids = [sid for sid in (session_ids or []) if sid]
  1350. if not ids:
  1351. return {}
  1352. statuses: dict[str, str] = {sid: "empty" for sid in ids}
  1353. rows = self._read_all(f"""
  1354. SELECT m.session_id, m.role,
  1355. m.tool_calls IS NOT NULL AS has_tool_calls,
  1356. m.finish_reason
  1357. FROM messages m
  1358. JOIN (
  1359. SELECT session_id, MAX(id) AS max_id
  1360. FROM messages
  1361. WHERE session_id IN ({_session_ids_placeholders(ids)})
  1362. GROUP BY session_id
  1363. ) latest ON m.id = latest.max_id
  1364. """, ids)
  1365. for row in rows:
  1366. statuses[row["session_id"]] = classify_session_status(
  1367. role=row["role"], has_tool_calls=bool(row["has_tool_calls"]),
  1368. finish_reason=row["finish_reason"],
  1369. )
  1370. return statuses
  1371. def assert_export_safe(self, session_id: str, max_messages: Optional[int] = None) -> int:
  1372. """Row count of this segment — every row, archived included, as the transfer export materializes
  1373. it — or raise SessionExportTooLargeError (the LIMITed subquery
  1374. stops once the bound is exceeded). ``None`` resolves ``sessions.max_export_messages``; 0 disables
  1375. the guard."""
  1376. from hermes_state import SessionExportTooLargeError, resolved_max_export_messages
  1377. if max_messages is None:
  1378. max_messages = resolved_max_export_messages()
  1379. if max_messages < 0:
  1380. raise ValueError("max_messages must be non-negative")
  1381. if max_messages == 0:
  1382. return 0
  1383. row = self._read_one(
  1384. "SELECT COUNT(*) FROM (SELECT 1 FROM messages WHERE session_id = ? LIMIT ?)",
  1385. (session_id, max_messages + 1),
  1386. )
  1387. message_count = int(row[0] if row else 0)
  1388. if message_count > max_messages:
  1389. raise SessionExportTooLargeError(session_id, message_count, max_messages)
  1390. return message_count
  1391. def assert_exports_safe(self, session_ids, max_messages: Optional[int] = None) -> None:
  1392. """assert_export_safe for each id with the limit resolved once; 0 disables (no queries)."""
  1393. from hermes_state import resolved_max_export_messages
  1394. if max_messages is None:
  1395. max_messages = resolved_max_export_messages()
  1396. if max_messages == 0:
  1397. return
  1398. for session_id in session_ids:
  1399. self.assert_export_safe(session_id, max_messages=max_messages)
  1400. def _is_explicit_branch_session(self, session_id: str) -> bool:
  1401. """Copied user-facing branch (``_branched_from``)? Branches own a copied transcript;
  1402. compression continuations need the parent's archived rows."""
  1403. if not session_id:
  1404. return False
  1405. row = self._read_one("SELECT model_config FROM sessions WHERE id = ?", (session_id,))
  1406. return row is not None and bool(_parse_model_config(row[0]).get("_branched_from"))
  1407. def _session_lineage_root_to_tip(self, session_id: str) -> list[str]:
  1408. if not session_id:
  1409. return [session_id]
  1410. chain: list[str] = []
  1411. current = session_id
  1412. with self._read_ctx() as conn:
  1413. while current and current not in chain and len(chain) < 100:
  1414. chain.append(current)
  1415. row = conn.execute(
  1416. "SELECT parent_session_id FROM sessions WHERE id = ?", (current,),
  1417. ).fetchone()
  1418. if row is None:
  1419. break
  1420. current = row[0]
  1421. return list(reversed(chain)) or [session_id]
  1422. def search_sessions(
  1423. self, source: str | Sequence[str] | None = None, limit: int = 20, offset: int = 0,
  1424. workspace_key: str | None = None, local_created_sources: Sequence[str] | None = None,
  1425. skip_launch_stubs: bool = False,
  1426. ) -> list[dict[str, Any]]:
  1427. """Sessions MRU-first with a computed ``last_active``; ``workspace_key`` scopes to one workspace
  1428. so ``hermes -c``/``--resume`` picks its last session. ``source`` may be one label or several.
  1429. ``local_created_sources`` restricts ``source='local'`` rows before LIMIT/OFFSET, and
  1430. ``skip_launch_stubs`` drops empty launch stubs (launch_stub_filter_sql) before it too."""
  1431. where_clauses = [launch_stub_filter_sql(self)] if skip_launch_stubs else []
  1432. params: list = []
  1433. if source:
  1434. sources = [source] if isinstance(source, str) else list(source)
  1435. clause, bound = _source_match_clause(sources, local_created_sources)
  1436. where_clauses.append(clause)
  1437. params.extend(bound)
  1438. if workspace_key:
  1439. ws_clause, ws_params = _workspace_key_clause(workspace_key)
  1440. where_clauses.append(ws_clause)
  1441. params.extend(ws_params)
  1442. return [self._session_row_dict(row) for row in self._read_all(
  1443. "SELECT s.*, COALESCE(sp.prompt, s.system_prompt) AS _system_prompt_resolved, "
  1444. f"{_sql_session_last_active('s')} AS last_active "
  1445. "FROM sessions s LEFT JOIN system_prompts sp ON sp.hash = s.system_prompt_hash "
  1446. f"{_where_sql(where_clauses, ' ')} "
  1447. "ORDER BY last_active DESC, s.started_at DESC, s.id DESC LIMIT ? OFFSET ?",
  1448. [*params, limit, offset],
  1449. )]
  1450. def session_count(
  1451. self, source: str | None = None, sources: list[str] | None = None, cwd_prefix: str | None = None,
  1452. min_message_count: int = 0, include_archived: bool = False, archived_only: bool = False,
  1453. exclude_children: bool = False, exclude_sources: list[str] | None = None, include_subagents: bool = False,
  1454. local_created_sources: Sequence[str] | None = None,
  1455. ) -> int:
  1456. """Count sessions with list_sessions_rich's filters so a paired "load more" total matches."""
  1457. where_clauses, params = _session_filter_where(
  1458. exclude_children=exclude_children, source=source, sources=sources,
  1459. exclude_sources=exclude_sources, cwd_prefix=cwd_prefix, min_message_count=min_message_count,
  1460. archived_only=archived_only, include_archived=include_archived, include_subagents=include_subagents,
  1461. local_created_sources=local_created_sources,
  1462. )
  1463. if exclude_children:
  1464. from hermes_state_local import exclude_superseded_segments
  1465. exclude_superseded_segments(self, where_clauses, params)
  1466. return self._read_one(f"SELECT COUNT(*) FROM sessions s{_where_sql(where_clauses, ' ')}", params)[0]
  1467. def session_count_ge(self, n: int = 1) -> bool:
  1468. """At least N sessions exist (archived included); LIMIT short-circuits session_count()'s scan."""
  1469. return len(self._read_all("SELECT 1 FROM sessions LIMIT ?", (n,))) >= n
  1470. def session_count_by_source(
  1471. self, *, include_archived: bool = False, archived_only: bool = False,
  1472. exclude_children: bool = False,
  1473. ) -> dict[str, int]:
  1474. """``{source: count}`` via one GROUP BY; ``exclude_children`` mirrors listing visibility."""
  1475. where_clauses, params = _session_filter_where(
  1476. exclude_children=exclude_children, archived_only=archived_only,
  1477. include_archived=include_archived,
  1478. )
  1479. if exclude_children:
  1480. from hermes_state_local import exclude_superseded_segments
  1481. exclude_superseded_segments(self, where_clauses, params)
  1482. with self._read_ctx() as conn:
  1483. if self._conn is None:
  1484. raise RuntimeError("SessionDB connection is closed")
  1485. rows = conn.execute(
  1486. "SELECT COALESCE(NULLIF(s.source, ''), 'cli') AS source, COUNT(*) AS count "
  1487. f"FROM sessions s{_where_sql(where_clauses, ' ')} "
  1488. "GROUP BY COALESCE(NULLIF(s.source, ''), 'cli') ORDER BY count DESC", params,
  1489. ).fetchall()
  1490. return {str(row["source"]): int(row["count"] or 0) for row in rows}
  1491. def declared_scope_identity(self, session_id: str) -> tuple[bool, str]:
  1492. """(is_fork_child, source) in ONE read (prompt_cache_scope needs both from the same row).
  1493. Missing row → (False, ""); DB errors propagate (fail closed).
  1494. ``agent/prompt_cache_scope.py`` needs both to resolve a host-declared conversation scope, and both
  1495. live on the same ``sessions`` row; asking for them separately read that row twice per resolution
  1496. (@teknium1 on 98811). The marker rules stay here, beside :meth:`is_explicit_fork_child`, instead of
  1497. being re-implemented by the caller. See #98811.
  1498. """
  1499. session = self.get_session(session_id)
  1500. if not session:
  1501. return False, ""
  1502. return self._is_explicit_fork_child_row(session), str(session.get("source") or "").strip()
  1503. @staticmethod
  1504. def _remove_session_files(sessions_dir: Optional[Path], session_id: str) -> None:
  1505. """Remove ``<id>.json``/``.jsonl``, the legacy ``session_<id>.json`` snapshot, and gateway
  1506. ``request_dump_<id>_*.json``; OSError is swallowed so a filesystem hiccup never blocks a
  1507. DB operation. Every historical writer name is swept because a "deleted" session's snapshot
  1508. can carry plaintext secrets (#20334, #60207)."""
  1509. if sessions_dir is None:
  1510. return
  1511. targets = [sessions_dir / f"{session_id}{suffix}" for suffix in (".json", ".jsonl")]
  1512. targets.append(sessions_dir / f"session_{session_id}.json")
  1513. try:
  1514. # glob.escape: a session id carrying ``[`` / ``?`` / ``*`` is a PATTERN otherwise, so the
  1515. # dump sweep either matches nothing or matches another session's files.
  1516. targets.extend(sessions_dir.glob(f"request_dump_{glob.escape(session_id)}_*.json"))
  1517. except OSError:
  1518. pass
  1519. for p in targets:
  1520. try:
  1521. p.unlink(missing_ok=True)
  1522. except OSError:
  1523. pass
  1524. def get_session_delete_targets(self, session_id: str) -> list[str]:
  1525. """Rows :meth:`delete_session` would remove: the session, then its recursive delegate children
  1526. (branch/compression children are orphaned, not deleted)."""
  1527. with self._read_ctx() as conn:
  1528. if not conn.execute("SELECT 1 FROM sessions WHERE id = ? LIMIT 1", (session_id,)).fetchone():
  1529. return []
  1530. # Use the borrowed read connection, never self._conn: handing the shared writer connection to a
  1531. # helper here executes on it without self._lock — the same unsynchronized-read class as
  1532. # #99349/#90734.
  1533. from hermes_state_local import owned_lineage_ids
  1534. scope = owned_lineage_ids(conn, session_id)
  1535. delegate_ids = _collect_delegate_child_ids(conn, scope)
  1536. return [session_id, *sorted(set(scope) - {session_id}), *sorted(delegate_ids)]
  1537. def _expand_compression_lineage(self, conn, session_ids: list[str]) -> list[str]:
  1538. """Expand *session_ids* to every member of their compression chains.
  1539. The dashboard sessions list surfaces one row per logical conversation: compression
  1540. roots are projected forward to their latest continuation, and the surfaced row
  1541. carries the *tip's* id (see :meth:`list_sessions_rich`). Deleting only that tip row
  1542. leaves the root behind, and the next list re-projects the root onto the previous
  1543. link — the "deleted" conversation reappears (#57543).
  1544. Walks compression-continuation edges in BOTH directions from the given ids:
  1545. backward to the chain root, and forward through every continuation — including
  1546. stale sibling continuations (e.g. ``ws_orphan_reap`` leftovers), which would
  1547. otherwise be orphaned into brand-new visible top-level rows by the delete itself.
  1548. The edge definition matches ``_CHAIN_STEP_SQL`` / ``get_compression_tip`` and the
  1549. list-projection CTE: parent ended with ``reason='compression'``, child is not a
  1550. branch / reset / delegate / tool session. Branch, reset and delegate children are
  1551. deliberately NOT pulled in — a branch/reset is its own conversation, and delegates
  1552. are handled by the existing cascade in the delete paths.
  1553. Runs inside the caller's write transaction (*conn*). The walk is defensively
  1554. bounded like ``get_compression_chain`` — ``seen`` guards cycles.
  1555. """
  1556. seen = set(session_ids)
  1557. frontier = list(session_ids)
  1558. for _ in range(_CHAIN_CAP):
  1559. if not frontier:
  1560. break
  1561. targets = _expand_compression_lineage_ids(conn, frontier)
  1562. frontier = [sid for sid in targets if sid not in seen]
  1563. seen.update(frontier)
  1564. # A local reset lineage (creation id + every segment, compression children included) is one
  1565. # listed conversation: deleting any segment must not strand the others without an owner.
  1566. from hermes_state_local import local_conversation_ids
  1567. for sid in list(seen):
  1568. seen.update(local_conversation_ids(conn, sid))
  1569. return list(seen)
  1570. def delete_session(
  1571. self, session_id: str, sessions_dir: Optional[Path] = None,
  1572. expected_delete_ids: Optional[list[str]] = None,
  1573. expected_display_messages: Optional[dict[str, list[dict[str, Any]]]] = None,
  1574. exclude_active_write_guards: bool = False,
  1575. include_compression_chain: bool = False,
  1576. ) -> bool:
  1577. """Delete a session and its messages; delegate children cascade, branch/compression children
  1578. are orphaned. Optional expected ids fence delegate drift; expected display snapshots fence
  1579. transcript drift. Both checks run inside the same write transaction as deletion.
  1580. With ``exclude_active_write_guards``, raises :class:`SessionActiveWriteGuardError` if the row
  1581. is protected by an active turn lease or compression lock.
  1582. With ``include_compression_chain=True`` the whole compression chain the session belongs to
  1583. is deleted with it (root and every continuation) — the dashboard delete endpoints use this
  1584. variant because their list rows carry chain-*tip* ids; deleting only that physical row
  1585. would leave the rest of the chain to resurface on the next list (#57543). Default False so
  1586. callers that operate on a single physical session keep the historic contract. Routing
  1587. through :meth:`delete_sessions` keeps the chain-aware guard/counting semantics in one
  1588. place; its return value counts the *requested* ids that existed, so ``> 0`` is exactly
  1589. "the session was found"."""
  1590. if include_compression_chain:
  1591. return self.delete_sessions(
  1592. [session_id], sessions_dir=sessions_dir,
  1593. exclude_active_write_guards=exclude_active_write_guards,
  1594. include_compression_chain=True,
  1595. ) > 0
  1596. removed_ids: list[str] = []
  1597. expected_ids = set(expected_delete_ids) if expected_delete_ids is not None else None
  1598. def _do(conn):
  1599. if conn.execute("SELECT 1 FROM sessions WHERE id = ? LIMIT 1", (session_id,)).fetchone() is None:
  1600. return False
  1601. # A local reset/compression conversation deletes whole from any segment: the listed row
  1602. # is its latest segment, and a lone segment delete strands the owner's policy and FIFO.
  1603. from hermes_state_local import owned_lineage_ids
  1604. scope = owned_lineage_ids(conn, session_id)
  1605. target_ids = (
  1606. [*scope, *_collect_delegate_child_ids(conn, scope)]
  1607. if exclude_active_write_guards or expected_ids is not None else None
  1608. )
  1609. if exclude_active_write_guards and self._guarded_ids(conn, target_ids):
  1610. # Delegate children cascade with the root, so a guard on any of them refuses too.
  1611. raise SessionActiveWriteGuardError(
  1612. f"session '{session_id}' (or a delegate child) has an active turn lease or compression lock"
  1613. )
  1614. if expected_ids is not None and expected_ids != set(target_ids):
  1615. return False
  1616. if expected_display_messages is not None and any(
  1617. self._display_messages_from_conn(conn, covered_id) != expected
  1618. for covered_id, expected in expected_display_messages.items()
  1619. ):
  1620. return False
  1621. from hermes_state_mutation_retirement import retire_sessions
  1622. retire_sessions(conn, scope)
  1623. removed_ids.extend(_delete_delegate_children(conn, scope))
  1624. for sid in scope: # orphan remaining children (branches) so FK is satisfied
  1625. conn.execute("UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id = ?", (sid,))
  1626. conn.execute("DELETE FROM messages WHERE session_id = ?", (sid,))
  1627. conn.executemany("DELETE FROM sessions WHERE id = ?", [(sid,) for sid in scope])
  1628. self._delete_unreferenced_system_prompts(conn)
  1629. removed_ids.extend(scope)
  1630. return True
  1631. deleted = self._execute_write(_do)
  1632. if deleted:
  1633. emit_session_deleted(self, removed_ids, reason="delete", primary=session_id, sessions_dir=sessions_dir)
  1634. from hermes_state_media import collect_retired_media
  1635. collect_retired_media(self)
  1636. for sid in removed_ids:
  1637. self._remove_session_files(sessions_dir, sid)
  1638. return bool(deleted)
  1639. def discard_unadmitted_session(self, session_id: str) -> bool:
  1640. """Abort a row this same flow just created and nobody has been admitted against (seed-copy
  1641. compensation): remove it WITHOUT the retirement fence so the id can be lazily recreated.
  1642. A row with any admission or worker receipt is a real session and takes the fenced
  1643. :meth:`delete_session` path instead."""
  1644. def _do(conn):
  1645. if conn.execute(
  1646. "SELECT 1 FROM session_admissions WHERE target_session_id=? UNION ALL "
  1647. "SELECT 1 FROM worker_executions WHERE session_id=? LIMIT 1", (session_id, session_id)).fetchone():
  1648. return None
  1649. conn.execute("DELETE FROM messages WHERE session_id = ?", (session_id,))
  1650. cur = conn.execute("DELETE FROM sessions WHERE id = ?", (session_id,))
  1651. return cur.rowcount > 0
  1652. result = self._execute_write(_do)
  1653. if result is None:
  1654. return self.delete_session(session_id)
  1655. return bool(result)
  1656. def delete_session_if_empty(self, session_id: str, sessions_dir: Optional[Path] = None) -> bool:
  1657. """Delete *session_id* only if it has no messages, no title and no children; check and delete
  1658. share one transaction so a concurrent flush can't be lost. A row under an active turn lease
  1659. or compression lock is never a candidate: the emptiness predicate reads committed state, so a
  1660. row whose first turn is already leased but not yet flushed would be deleted mid-turn
  1661. (#123583). A guarded row is simply not deleted (returns ``False``), like any non-empty row."""
  1662. def _do(conn):
  1663. from hermes_state_local import owned_lineage_ids
  1664. if self._guarded_ids(conn, [session_id]) or owned_lineage_ids(conn, session_id) != [session_id]:
  1665. return False # an empty reset tip is still its conversation's current target
  1666. eligible = conn.execute(
  1667. """
  1668. SELECT 1 FROM sessions
  1669. WHERE id = ?
  1670. AND title IS NULL
  1671. AND NOT EXISTS (
  1672. SELECT 1 FROM messages WHERE messages.session_id = sessions.id
  1673. )
  1674. AND NOT EXISTS (
  1675. SELECT 1 FROM sessions child
  1676. WHERE child.parent_session_id = sessions.id
  1677. )
  1678. """,
  1679. (session_id,),
  1680. ).fetchone()
  1681. if eligible is None:
  1682. return False
  1683. # Same BEGIN IMMEDIATE transaction as the check above: retire the ledger rows
  1684. # (ON DELETE RESTRICT) and delete without re-evaluating eligibility. Housekeeping, not
  1685. # a user delete: its fence ages out at the horizon (an untitled row is never a Bot Chat).
  1686. from hermes_state_mutation_retirement import retire_sessions
  1687. retire_sessions(conn, [session_id], expiring=[session_id])
  1688. conn.execute("DELETE FROM sessions WHERE id = ?", (session_id,))
  1689. self._delete_unreferenced_system_prompts(conn)
  1690. return True
  1691. deleted = self._execute_write(_do)
  1692. if deleted:
  1693. emit_session_deleted(self, [session_id], reason="empty_sweep", sessions_dir=sessions_dir)
  1694. from hermes_state_media import collect_retired_media
  1695. collect_retired_media(self)
  1696. if deleted:
  1697. self._remove_session_files(sessions_dir, session_id)
  1698. return deleted
  1699. def delete_sessions(
  1700. self, session_ids: list[str], sessions_dir: Optional[Path] = None,
  1701. exclude_active_write_guards: bool = False, skipped_ids: Optional[list[str]] = None,
  1702. include_compression_chain: bool = False,
  1703. ) -> int:
  1704. """Bulk delete with :meth:`delete_session` semantics per row, in ONE transaction. Unknown ids
  1705. are skipped (UI selection can race another tab's delete). With ``exclude_active_write_guards``, rows
  1706. protected by an active turn lease or compression lock are skipped and, when given, appended
  1707. to ``skipped_ids`` so callers can tell the user. Returns the number deleted.
  1708. With ``include_compression_chain=True``, each selected id is expanded to its full
  1709. compression chain (root + every continuation, including stale sibling continuations)
  1710. via :meth:`_expand_compression_lineage` — the dashboard rows carry chain-tip ids, so
  1711. without the expansion a "deleted" conversation resurfaces as the previous chain link on
  1712. the next list reload (#57543). The returned count still reflects the *requested* rows,
  1713. not the expanded chain links, so the caller's toast matches the user's selection."""
  1714. unique_ids = list({sid for sid in session_ids or () if isinstance(sid, str) and sid})
  1715. if not unique_ids:
  1716. return 0
  1717. removed_ids: list[str] = []
  1718. def _do(conn):
  1719. existing = [row["id"] for chunk in _id_chunks(unique_ids) for row in conn.execute(
  1720. f"SELECT id FROM sessions WHERE id IN ({_session_ids_placeholders(chunk)})", chunk,
  1721. ).fetchall()]
  1722. if not existing:
  1723. return 0
  1724. from hermes_state_local import owned_lineage_ids
  1725. def expand(ids):
  1726. # A local reset/compression segment deletes as its whole conversation (delete_session).
  1727. if include_compression_chain:
  1728. return self._expand_compression_lineage(conn, ids)
  1729. return list(dict.fromkeys(x for sid in ids for x in owned_lineage_ids(conn, sid)))
  1730. # Expand BEFORE the guard pass so a guarded lineage member (active turn lease /
  1731. # compression lock anywhere in it) keeps its selected root listed too.
  1732. expanded = expand(existing)
  1733. guard_pool = [*expanded, *_collect_delegate_child_ids(conn, expanded)]
  1734. if exclude_active_write_guards:
  1735. # A root is skipped when it or any delegate child it would cascade is guarded, so the
  1736. # cascade below never deletes a guarded row reported back as kept. When the chain
  1737. # expansion is on, a guard on ANY lineage member keeps its selected root: deleting
  1738. # a torn chain would re-surface it (the root re-projects onto a surviving link).
  1739. # One batched check first; per-root attribution only when something is guarded.
  1740. active_ids: set = set()
  1741. if self._guarded_ids(conn, guard_pool):
  1742. if include_compression_chain:
  1743. for sid in existing:
  1744. member_lineage = set(self._expand_compression_lineage(conn, [sid]))
  1745. member_lineage.add(sid)
  1746. if self._guarded_ids(conn, [*member_lineage,
  1747. *_collect_delegate_child_ids(conn, list(member_lineage))]):
  1748. active_ids.add(sid)
  1749. else:
  1750. active_ids = {
  1751. sid for sid in existing
  1752. if self._guarded_ids(conn, [*(members := expand([sid])),
  1753. *_collect_delegate_child_ids(conn, members)])
  1754. }
  1755. existing = [sid for sid in existing if sid not in active_ids]
  1756. if skipped_ids is not None:
  1757. skipped_ids.extend(sorted(active_ids))
  1758. if not existing:
  1759. return 0
  1760. expanded = expand(existing)
  1761. from hermes_state_mutation_retirement import retire_sessions
  1762. retire_sessions(conn, expanded)
  1763. removed_ids.extend(_delete_delegate_children(conn, expanded))
  1764. for chunk in _id_chunks(expanded):
  1765. ph = _session_ids_placeholders(chunk)
  1766. conn.execute( # orphan children whose parent is in the kill list (FK)
  1767. f"UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id IN ({ph})", chunk,
  1768. )
  1769. conn.execute(f"DELETE FROM messages WHERE session_id IN ({ph})", chunk)
  1770. conn.execute(f"DELETE FROM sessions WHERE id IN ({ph})", chunk)
  1771. self._delete_unreferenced_system_prompts(conn)
  1772. removed_ids.extend(expanded)
  1773. # Count the ids the CALLER asked for, not the expanded chain links —
  1774. # the dashboard toast should say "3 deleted" when the user selected
  1775. # 3 rows, however many physical links those rows had.
  1776. return len(existing)
  1777. count = self._execute_write(_do)
  1778. if count:
  1779. emit_session_deleted(self, removed_ids, reason="delete", primary=unique_ids[0] if len(unique_ids) == 1 else None,
  1780. sessions_dir=sessions_dir)
  1781. from hermes_state_media import collect_retired_media
  1782. collect_retired_media(self)
  1783. for sid in removed_ids:
  1784. self._remove_session_files(sessions_dir, sid)
  1785. return count
  1786. # Shared by count_empty_sessions / delete_empty_sessions so badge and sweep agree. message_count
  1787. # counts live rows only (rewind/compaction keep dropped turns as active = 0): NOT EXISTS is authority.
  1788. # The ``NOT EXISTS`` probe is the authority; : ``message_count = 0`` stays as a cheap prefilter. Same
  1789. # shape as every : other emptiness guard in this module. (#95868)
  1790. _EMPTY_SESSION_WHERE = (
  1791. "message_count = 0 AND ended_at IS NOT NULL AND archived = 0 AND NOT EXISTS ("
  1792. "SELECT 1 FROM messages WHERE messages.session_id = sessions.id)"
  1793. )
  1794. def count_empty_sessions(self) -> int:
  1795. """Count of empty, ended, non-archived sessions; ended_at guards a fresh session's first message."""
  1796. return self._read_one(f"SELECT COUNT(*) FROM sessions WHERE {self._EMPTY_SESSION_WHERE}")[0]
  1797. def delete_empty_sessions(self, sessions_dir: Optional[Path] = None) -> int:
  1798. """Delete every empty, ended, non-archived session in one transaction, orphaning (not cascading)
  1799. children; transcript files are swept too."""
  1800. removed_ids: list[str] = []
  1801. def _do(conn):
  1802. session_ids = {row["id"] for row in conn.execute(
  1803. f"SELECT id FROM sessions WHERE {self._EMPTY_SESSION_WHERE}"
  1804. ).fetchall()}
  1805. from hermes_state_mutation_retirement import retire_prunable
  1806. session_ids = retire_prunable(conn, sorted(session_ids))
  1807. if not session_ids:
  1808. return 0
  1809. for chunk in _id_chunks(session_ids):
  1810. ph = _session_ids_placeholders(chunk)
  1811. conn.execute(f"UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id IN ({ph})", chunk)
  1812. # DELETE FROM messages: a row inserted between the SELECT and here
  1813. # would otherwise dangle (clean FK state).
  1814. conn.execute(f"DELETE FROM messages WHERE session_id IN ({ph})", chunk)
  1815. conn.execute(f"DELETE FROM sessions WHERE id IN ({ph})", chunk)
  1816. removed_ids.extend(chunk)
  1817. self._delete_unreferenced_system_prompts(conn)
  1818. return len(session_ids)
  1819. count = self._execute_write(_do)
  1820. if count:
  1821. emit_session_deleted(self, removed_ids, reason="empty_sweep", sessions_dir=sessions_dir)
  1822. from hermes_state_media import collect_retired_media
  1823. collect_retired_media(self)
  1824. for sid in removed_ids:
  1825. self._remove_session_files(sessions_dir, sid)
  1826. return count
  1827. def archive_sessions(
  1828. self, older_than_days: Optional[float] = None, source: str | None = None, **filters,
  1829. ) -> int:
  1830. """Bulk soft-hide with prune_sessions' filter surface, via set_session_archived so each lineage
  1831. flips as a unit; idempotent. Returns matches. A lineage is matched through its TIP only: an
  1832. old compression ancestor never qualifies on its own age, or the fan-out would hide an open,
  1833. recently active continuation (#115489)."""
  1834. filters.setdefault("archived", False)
  1835. filters["lineage_tips_only"] = True
  1836. rows = self.list_prune_candidates(older_than_days=older_than_days, source=source, **filters)
  1837. for row in rows:
  1838. self.set_session_archived(row["id"], True)
  1839. return len(rows)