sessions.py 49 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991
  1. """Session dashboard routes.
  2. Three routers because global route order matters: ``list_router`` (GET
  3. /api/sessions) mounts before the profiles ``sessions_router``, ``search_router``
  4. right after it, ``manage_router`` (mutation/detail) much later. web_server-owned
  5. helpers are reached via the late-binding seam so monkeypatching keeps working.
  6. """
  7. import asyncio
  8. import json
  9. import re
  10. import sqlite3
  11. import time
  12. from pathlib import Path
  13. from typing import Callable, List, Optional
  14. from fastapi import APIRouter, HTTPException, Query, Request
  15. from fastapi.encoders import jsonable_encoder
  16. from fastapi.responses import StreamingResponse
  17. from hermes_cli.session_listing import subagent_listing_scope
  18. from hermes_cli.web_deps import late
  19. from hermes_cli.web_server_gateway import _strip_session_list_rows
  20. from hermes_cli.web_server_sessions import _session_latest_descendant
  21. from hermes_cli.web_models import (
  22. BulkDeleteSessions, SessionImport, SessionOwnerBackfill, SessionPrune, SessionRename)
  23. from hermes_cli.web_routers._common import (
  24. CORRUPT_STORE_DETAIL, corrupt_store_as_status, log as _log, destructive_profile, http_failure,
  25. )
  26. from hermes_state import is_malformed_db_error
  27. from hermes_state_errors import SessionActiveWriteGuardError, StateDbReplacedError, is_transient_sqlite_error
  28. from hermes_state_health import STORAGE_CORRUPT, note_storage_error, storage_state
  29. list_router = APIRouter()
  30. search_router = APIRouter()
  31. manage_router = APIRouter()
  32. _cron_default_profile = late("_cron_default_profile", "hermes_cli.web_server_cron")
  33. _cron_profile_home = late("_cron_profile_home", "hermes_cli.web_server_cron")
  34. _open_session_db_for_profile = late("_open_session_db_for_profile", "hermes_cli.web_server_sessions")
  35. _session_db_path_for_profile = late("_session_db_path_for_profile", "hermes_cli.web_server_sessions")
  36. _NOT_FOUND = "Session not found"
  37. # CRITICAL — every literal-path route on ``manage_router`` MUST be declared
  38. # BEFORE the templated ``/api/sessions/{session_id}`` family. Starlette matches
  39. # in registration order and ``{session_id}`` is unconstrained, so e.g.
  40. # ``DELETE /api/sessions/empty`` would otherwise be taken as "the session with
  41. # id 'empty'" (404, or worse, deleting the wrong row). Move the block as a unit.
  42. # Stream-safe import: FastAPI otherwise buffers an arbitrarily large JSON body
  43. # before SessionDB can enforce its own per-session and transaction limits.
  44. _SESSION_IMPORT_MAX_BYTES = 25 * 1024 * 1024
  45. async def _read_session_import_body(request: Request) -> bytes:
  46. body = bytearray()
  47. async for chunk in request.stream():
  48. if len(body) + len(chunk) > _SESSION_IMPORT_MAX_BYTES:
  49. raise HTTPException(status_code=413, detail="Session import payload is too large")
  50. body.extend(chunk)
  51. return bytes(body)
  52. # Prune filters forwarded to SessionDB; string filters map "" -> None.
  53. _PRUNE_STR_FILTERS = (
  54. "source", "title_like", "end_reason", "cwd_prefix", "model_like", "provider",
  55. "user_id", "chat_id", "chat_type", "branch_like")
  56. _PRUNE_NUM_FILTERS = (
  57. "min_messages", "max_messages", "min_tokens", "max_tokens", "min_cost", "max_cost",
  58. "min_tool_calls", "max_tool_calls")
  59. _PRUNE_ROW_KEYS = ("id", "source", "title", "model", "started_at", "last_active", "message_count")
  60. def _prune_sessions(body: SessionPrune):
  61. """Delete ended sessions matching filters (mirrors `hermes sessions prune`)."""
  62. from hermes_cli.config import get_hermes_home
  63. has_window = body.started_before is not None or body.started_after is not None
  64. if body.older_than_days is not None and body.older_than_days < 1 and not has_window:
  65. raise HTTPException(status_code=400, detail="older_than_days must be >= 1")
  66. # Mirror the CLI: the implicit 90-day cutoff only applies to a truly bare
  67. # prune. Any attribute filter suppresses it unless older_than_days was
  68. # explicitly sent.
  69. attr_filters_set = any(
  70. getattr(body, f) is not None for f in _PRUNE_STR_FILTERS + _PRUNE_NUM_FILTERS)
  71. effective_older_than = body.older_than_days
  72. if has_window or (attr_filters_set and "older_than_days" not in body.model_fields_set):
  73. effective_older_than = None
  74. profile_home = _cron_profile_home(body.profile)[1] if body.profile else get_hermes_home()
  75. db = _open_session_db_for_profile(body.profile, read_only=body.dry_run)
  76. try:
  77. filters = {
  78. "older_than_days": effective_older_than, "started_before": body.started_before,
  79. "started_after": body.started_after,
  80. "archived": None if body.include_archived else False,
  81. **{f: (getattr(body, f) or None) for f in _PRUNE_STR_FILTERS},
  82. **{f: getattr(body, f) for f in _PRUNE_NUM_FILTERS}}
  83. skipped_open = db.count_open_prune_matches(**filters)
  84. if body.dry_run:
  85. # Same whole-lineage selection prune_sessions applies, so the preview lists what it deletes.
  86. rows = db.list_prune_candidates(**filters, whole_lineages=True)
  87. return {
  88. "ok": True,
  89. "removed": 0,
  90. "matched": len(rows),
  91. "skipped_open": skipped_open,
  92. # Rows are ordered by last activity, not creation time.
  93. "oldest_last_active": rows[0]["last_active"] if rows else None,
  94. "newest_last_active": rows[-1]["last_active"] if rows else None,
  95. "oldest_started_at": min(r["started_at"] for r in rows) if rows else None,
  96. "newest_started_at": max(r["started_at"] for r in rows) if rows else None,
  97. "sessions": [{k: r.get(k) for k in _PRUNE_ROW_KEYS} for r in rows]}
  98. sessions_dir = profile_home / "sessions"
  99. removed = db.prune_sessions(
  100. sessions_dir=sessions_dir if sessions_dir.exists() else None,
  101. exclude_active_write_guards=True, **filters)
  102. return {"ok": True, "removed": removed, "skipped_open": skipped_open}
  103. finally:
  104. db.close()
  105. _ACTIVE_WINDOW_S = 300
  106. def _csv(value: Optional[str]) -> list[str]:
  107. """Split a comma-separated query param into stripped, non-empty items."""
  108. return [s.strip() for s in (value or "").split(",") if s.strip()]
  109. def _is_active(row: dict, now: float) -> bool:
  110. return (
  111. row.get("ended_at") is None
  112. and (now - row.get("last_active", row.get("started_at", 0))) < _ACTIVE_WINDOW_S)
  113. def _with_db(profile: Optional[str], fn: Callable, *, read_only: bool):
  114. """Open the profile's session DB, run ``fn(db)``, always close."""
  115. def run():
  116. db = _open_session_db_for_profile(profile, read_only=read_only)
  117. try:
  118. return fn(db)
  119. finally:
  120. db.close()
  121. if read_only:
  122. return run()
  123. from hermes_cli.web_server_sessions import _with_session_maintenance
  124. return _with_session_maintenance(profile, run)
  125. def _serving_profile(profile: Optional[str]) -> str:
  126. """The profile name rows are stamped with: the requested one, else the
  127. serving process's own — so default-profile rows never circulate unowned."""
  128. return _cron_profile_home(profile)[0] if profile else _cron_default_profile()
  129. def _resolve_session_id(db, session_id: str) -> Optional[str]:
  130. """Resolve *session_id*; a corrupt store (prefix scan raises "malformed") is
  131. reported as 503 with the actual problem instead of a misleading 404."""
  132. try:
  133. return db.resolve_session_id(session_id)
  134. except sqlite3.DatabaseError as exc:
  135. if not is_malformed_db_error(exc):
  136. raise
  137. _log.error("state.db is corrupt while resolving session %s: %s", session_id, exc)
  138. raise HTTPException(
  139. status_code=503,
  140. detail=(
  141. "Session store is corrupt (database disk image is malformed). "
  142. "Sessions cannot be read until it is repaired — run "
  143. "`hermes doctor` for diagnosis."),
  144. ) from exc
  145. except StateDbReplacedError:
  146. # RuntimeError family, not sqlite3: same 503 payload as the analytics reads (#110054).
  147. with corrupt_store_as_status(db.db_path):
  148. raise
  149. # ``le=100`` on limit: an unbounded limit lets one request drag every session
  150. # row (plus correlated-subquery preview work) out of SQLite in a single hit.
  151. @list_router.get("/api/sessions")
  152. def get_sessions(
  153. limit: int = Query(20, ge=0, le=100), offset: int = Query(0, ge=0), min_messages: int = 0,
  154. archived: str = "exclude", order: str = "created", source: str | None = None, sources: str | None = None,
  155. exclude_sources: str | None = None, cwd_prefix: str | None = None, full: bool = False,
  156. profile: Optional[str] = None):
  157. """List sessions.
  158. ``order=recent`` sorts by latest activity across the compression chain, so
  159. a long-running chat stays on page one after it auto-compresses onto a fresh
  160. id. Rows omit ``system_prompt`` / ``model_config`` unless ``full=1``.
  161. """
  162. if archived not in ("exclude", "only", "include"):
  163. raise HTTPException(
  164. status_code=400, detail="archived must be one of: exclude, only, include")
  165. if order not in ("created", "recent"):
  166. raise HTTPException(status_code=400, detail="order must be one of: created, recent")
  167. profile_name = _cron_profile_home(profile)[0] if profile else None
  168. try:
  169. db = _open_session_db_for_profile(profile, read_only=True)
  170. try:
  171. min_message_count = max(0, min_messages)
  172. archived_only = archived == "only"
  173. include_archived = archived == "include"
  174. # Source scoping: the desktop splits recents (exclude=cron) from
  175. # the cron-jobs section (source=cron) into two independent lists.
  176. source_list = _csv(sources)
  177. include_subagents, exclude_list = subagent_listing_scope(
  178. Path(db.db_path).parent, source=source or None, sources=source_list or None,
  179. exclude_sources=_csv(exclude_sources) or None)
  180. scope = dict(
  181. source=source or None, sources=source_list or None,
  182. exclude_sources=exclude_list or None, cwd_prefix=(cwd_prefix or None),
  183. min_message_count=min_message_count, include_archived=include_archived,
  184. archived_only=archived_only, include_subagents=include_subagents)
  185. sessions = db.list_sessions_rich(
  186. limit=limit,
  187. offset=offset,
  188. order_by_last_active=order == "recent",
  189. # Skip the system_prompt blob inside SQLite too (pairs with
  190. # _strip_session_list_rows below).
  191. compact_rows=not full,
  192. include_pinned=True,
  193. **scope)
  194. total = db.session_count(exclude_children=True, **scope)
  195. now = time.time()
  196. row_profile = profile_name or _cron_default_profile()
  197. for s in sessions:
  198. s["is_active"] = _is_active(s, now)
  199. s["profile"] = row_profile
  200. s["is_default_profile"] = row_profile == "default"
  201. # SQLite stores the flags as 0/1; expose real JSON booleans.
  202. s["archived"] = bool(s.get("archived"))
  203. s["pinned"] = bool(s.get("pinned"))
  204. if not full:
  205. _strip_session_list_rows(sessions)
  206. # ``storage`` tells an empty page apart from an unreadable store (#72046); same
  207. # ``{profile: "corrupt"}`` shape as the /api/profiles/sessions* lists.
  208. storage = {row_profile: STORAGE_CORRUPT} if storage_state(db.db_path) == STORAGE_CORRUPT else {}
  209. return {"sessions": sessions, "total": total, "limit": limit, "offset": offset,
  210. "storage": storage}
  211. finally:
  212. db.close()
  213. except HTTPException:
  214. raise
  215. except sqlite3.OperationalError as exc:
  216. _log.exception("GET /api/sessions failed")
  217. # 503, not 500: the store is busy, not gone — the desktop keeps its
  218. # sidebar instead of reading a 500 as an authoritative empty list.
  219. transient = is_transient_sqlite_error(exc)
  220. raise HTTPException(
  221. status_code=503 if transient else 500,
  222. detail=(
  223. "Session store is busy (disk I/O or lock). Retry; the list was not cleared."
  224. if transient
  225. else "Internal server error"),
  226. ) from exc
  227. except sqlite3.DatabaseError as exc:
  228. # A damaged store is unavailable, not empty and not an internal error (#72046).
  229. db_path = _session_db_path_for_profile(profile)
  230. if not (note_storage_error(db_path, exc) or is_malformed_db_error(exc)):
  231. _log.exception("GET /api/sessions failed")
  232. raise HTTPException(status_code=500, detail="Internal server error") from exc
  233. _log.error("GET /api/sessions: state.db at %s is corrupt: %s", db_path, exc)
  234. raise HTTPException(status_code=503, detail=dict(CORRUPT_STORE_DETAIL)) from exc
  235. except StateDbReplacedError:
  236. # RuntimeError family, not sqlite3: same 503 payload as the analytics reads (#110054).
  237. with corrupt_store_as_status(_session_db_path_for_profile(profile)):
  238. raise
  239. except Exception:
  240. _log.exception("GET /api/sessions failed")
  241. raise HTTPException(status_code=500, detail="Internal server error")
  242. def _is_compression_edge(child: dict, parent: dict) -> bool:
  243. parent_ended_at = parent.get("ended_at")
  244. started_at = child.get("started_at")
  245. return (
  246. parent.get("end_reason") == "compression"
  247. and parent_ended_at is not None
  248. and started_at is not None
  249. and started_at >= parent_ended_at)
  250. @search_router.get("/api/sessions/search")
  251. async def search_sessions(
  252. q: str = "", limit: int = 20, profile: Optional[str] = None, source: str | None = None,
  253. sources: str | None = None, exclude_sources: str | None = None):
  254. """Search sessions by ID (first) plus FTS5 message content.
  255. Results are deduped by compression lineage, not raw ``session_id``:
  256. auto-compression rotates a chat onto a fresh id and leaves the old segment
  257. in the FTS index. Branches also use ``parent_session_id`` but are real
  258. alternate conversations — they are NOT collapsed into the parent.
  259. """
  260. if not q or not q.strip():
  261. return {"results": []}
  262. with http_failure("GET /api/sessions/search failed", 500, detail="Search failed"):
  263. row_profile = _serving_profile(profile)
  264. def _search(db):
  265. safe_limit = max(1, min(int(limit or 20), 100))
  266. source_filter = source or None
  267. source_list = _csv(sources)
  268. include_sources = [source_filter] if source_filter else (source_list or None)
  269. exclude_list = _csv(exclude_sources)
  270. now = time.time()
  271. def get_session(sid):
  272. try:
  273. return db.get_session(sid)
  274. except Exception:
  275. return None
  276. # Walk parent_session_id to the compression root, memoized per
  277. # chain; stops at branch/delegate edges (those stay searchable).
  278. root_cache: dict = {}
  279. def compression_root(session_id: str) -> str:
  280. chain, cur, root = [], session_id, session_id
  281. while cur and cur not in chain: # ``not in chain`` guards parent cycles
  282. if cur in root_cache:
  283. root = root_cache[cur]
  284. break
  285. chain.append(cur)
  286. s = get_session(cur)
  287. parent = s.get("parent_session_id") if isinstance(s, dict) else None
  288. parent_session = get_session(parent) if parent else None
  289. if not parent_session or not _is_compression_edge(s, parent_session):
  290. root = cur
  291. break
  292. cur = parent
  293. for node in chain:
  294. root_cache[node] = root
  295. return root
  296. tip_cache: dict = {}
  297. def lineage_tip(session_id: str) -> str:
  298. # Resolve the tip from the MATCHED id, never from the lineage
  299. # root: the forward chain walk is defensively bounded, so a
  300. # lineage deeper than the bound truncates to a stale mid id
  301. # when started at the root. Resuming from the matched id is
  302. # what the CLI does and always reaches the live tip (#125041).
  303. if session_id not in tip_cache:
  304. try:
  305. tip_cache[session_id] = db.get_compression_tip(session_id) or session_id
  306. except Exception:
  307. tip_cache[session_id] = session_id
  308. return tip_cache[session_id]
  309. # One keyspace for id-hits and content-hits, keyed by lineage root;
  310. # first hit wins, and ID matches run first.
  311. seen: dict = {}
  312. def add_lineage_result(raw_sid: str, payload: dict) -> None:
  313. if not raw_sid:
  314. return
  315. root = compression_root(raw_sid)
  316. if root in seen or len(seen) >= safe_limit:
  317. return
  318. payload = dict(payload)
  319. sid = lineage_tip(raw_sid)
  320. payload["session_id"] = sid
  321. payload["lineage_root"] = root
  322. payload["profile"] = row_profile
  323. payload["is_default_profile"] = row_profile == "default"
  324. try:
  325. row = db.get_session_rich_row(sid)
  326. except Exception:
  327. row = None
  328. if row:
  329. last_active = row.get("last_active") or row.get("started_at")
  330. payload.update({
  331. "id": row.get("id") or sid,
  332. "source": row.get("source"),
  333. "model": row.get("model"),
  334. "title": row.get("title"),
  335. "started_at": row.get("started_at"),
  336. "ended_at": row.get("ended_at"),
  337. "last_active": last_active,
  338. "is_active": (
  339. row.get("ended_at") is None and (now - (last_active or 0)) < 300),
  340. "message_count": row.get("message_count") or 0,
  341. "tool_call_count": row.get("tool_call_count") or 0,
  342. "input_tokens": row.get("input_tokens") or 0,
  343. "output_tokens": row.get("output_tokens") or 0,
  344. "preview": row.get("preview"),
  345. "parent_session_id": row.get("parent_session_id"),
  346. "profile": _serving_profile(profile),
  347. "archived": bool(row.get("archived"))})
  348. else:
  349. payload["id"] = sid
  350. seen[root] = payload
  351. def hit_payload(row: dict, snippet: str, role, session_started) -> dict:
  352. # `last_active` rides only on id-match rows (sessions table); FTS
  353. # hits have no row recency and leave it null so the desktop can
  354. # fall back to session_started instead of inventing one.
  355. return {
  356. "snippet": snippet, "role": role, "source": row.get("source"),
  357. "model": row.get("model"), "session_started": session_started,
  358. "last_active": row.get("last_active")}
  359. # Direct ID matches first (pasted ids never appear in message text).
  360. for row in db.search_sessions_by_id(
  361. q, limit=safe_limit, include_archived=True, source=source_filter,
  362. sources=source_list or None, exclude_sources=exclude_list or None):
  363. sid = row.get("id")
  364. preview = (row.get("preview") or "").strip()
  365. snippet = preview or f"Session ID: {sid}"
  366. add_lineage_result(sid, hit_payload(row, snippet, None, row.get("started_at")))
  367. # Prefix wildcards so partial words match ("nimb" -> "nimb*");
  368. # quoted phrases and existing wildcards are kept as-is.
  369. prefix_query = " ".join(
  370. tok if tok.startswith('"') or tok.endswith("*") else tok + "*"
  371. for tok in re.findall(r'"[^"]*"|\S+', q.strip()))
  372. # Over-fetch so lineage dedup can still surface `limit` distinct
  373. # conversations when several hits collapse onto one root.
  374. matches = db.search_messages(
  375. query=prefix_query, source_filter=include_sources,
  376. exclude_sources=exclude_list or None, limit=max(safe_limit * 5, 50),
  377. fields=("session_id", "role", "snippet", "source", "model", "session_started"))
  378. for m in matches:
  379. if len(seen) >= safe_limit:
  380. break
  381. add_lineage_result(
  382. m["session_id"],
  383. hit_payload(m, m.get("snippet", ""), m.get("role"), m.get("session_started")))
  384. # Title matches fill any remaining slots (#66242): the FTS index
  385. # only covers message content, so a term that lives solely in a
  386. # manually-set sessions.title would otherwise return nothing. The
  387. # DB layer already knows how to LIKE-match titles across the whole
  388. # compression chain (list_sessions_rich(search_query=) — the same
  389. # helper the sidebar listing uses), so reuse it rather than adding
  390. # a second title query path here. Best-effort: an old/odd store
  391. # that rejects the call just skips the lane.
  392. if len(seen) < safe_limit:
  393. try:
  394. title_rows = db.list_sessions_rich(
  395. search_query=q.strip(), include_archived=True, order_by_last_active=True,
  396. source=source_filter, sources=source_list or None,
  397. exclude_sources=exclude_list or None, limit=safe_limit)
  398. except Exception: # health: allow BLE001 -- best-effort supplement lane: an old/odd store that rejects the search_query read must not fail the id+content results already collected
  399. _log.debug("Title-match supplement skipped for %r", q[: 200])
  400. title_rows = []
  401. for row in title_rows:
  402. if len(seen) >= safe_limit:
  403. break
  404. sid = row.get("id")
  405. if not sid:
  406. continue
  407. preview = (row.get("preview") or "").strip()
  408. add_lineage_result(
  409. sid, hit_payload(row, preview or f"Session title matched: {q.strip()}",
  410. None, row.get("started_at")))
  411. return {"results": list(seen.values())}
  412. # FTS over a large state.db is the slowest read here; keep it off the loop (#60747).
  413. return await asyncio.to_thread(_with_db, profile, _search, read_only=True)
  414. @manage_router.post("/api/sessions/bulk-delete")
  415. async def bulk_delete_sessions_endpoint(body: BulkDeleteSessions):
  416. """Delete every session in ``body.ids`` in one transaction (POST: many
  417. clients refuse a DELETE body).
  418. Per :meth:`SessionDB.delete_sessions`: unknown ids are skipped (``deleted``
  419. reports what really happened), children are orphaned, active/archived rows
  420. ARE deleted (hand-picked), on-disk cleanup is left to the next prune.
  421. Compression chains are deleted whole: the sessions list shows one row per
  422. logical conversation carrying the chain *tip's* id, so deleting only that
  423. row would leave the root to resurface as the previous chain link on the
  424. next reload (#57543). ``deleted`` still counts the selected rows, not the
  425. expanded chain links.
  426. """
  427. # Hard cap so a runaway selection can't lock the writer for long.
  428. if len(body.ids) > 500:
  429. raise HTTPException(status_code=400, detail="ids must contain at most 500 entries")
  430. profile = destructive_profile(body.profile, "POST /api/sessions/bulk-delete")
  431. skipped: list[str] = [] # rows a live turn/compression still owns; the UI must keep them listed
  432. deleted = await asyncio.to_thread(_with_db, profile, lambda db: db.delete_sessions(
  433. body.ids, exclude_active_write_guards=True, skipped_ids=skipped,
  434. include_compression_chain=True), read_only=False)
  435. return {"ok": True, "deleted": deleted, "skipped_active": skipped}
  436. @manage_router.post("/api/sessions/import")
  437. async def import_sessions_endpoint(request: Request):
  438. """Import sessions exported from the dashboard or CLI (session rows only —
  439. ``/api/ops/import`` restores a whole backup archive)."""
  440. try:
  441. raw_body = await _read_session_import_body(request)
  442. body = SessionImport.model_validate_json(raw_body)
  443. except HTTPException:
  444. raise
  445. except ValueError as exc:
  446. raise HTTPException(status_code=400, detail="Invalid session import payload") from exc
  447. from hermes_cli.web_server_sessions import _mutate_session_request
  448. anchor = body.sessions[0].get('id', '') if body.sessions else ''
  449. return await _mutate_session_request(request, body.profile, anchor,
  450. request_id=body.request_id, expected_revision=body.expected_revision,
  451. operation='import', payload={'sessions': body.sessions})
  452. @manage_router.get("/api/sessions/empty/count")
  453. async def count_empty_sessions_endpoint(profile: Optional[str] = None):
  454. """Count of empty, ended, non-archived sessions (the "Delete empty (N)" button)."""
  455. count = await asyncio.to_thread(
  456. _with_db, profile, lambda db: db.count_empty_sessions(), read_only=True)
  457. return {"count": count}
  458. @manage_router.delete("/api/sessions/empty")
  459. async def delete_empty_sessions_endpoint(profile: Optional[str] = None):
  460. """Delete every empty, ended, non-archived session in one transaction.
  461. "Empty" means NO ``messages`` rows at all — a rewound/compacted chat reads
  462. ``message_count == 0`` while its soft-archived rows are the only transcript
  463. copy (see :meth:`SessionDB.delete_empty_sessions`).
  464. * Active sessions are skipped (``ended_at IS NULL``) so a live agent isn't yanked mid-handshake. *
  465. Archived sessions are skipped — the user explicitly chose to keep those rows. * Children of deleted
  466. parents are orphaned, not cascade-deleted. See #95868.
  467. """
  468. profile = destructive_profile(profile, "DELETE /api/sessions/empty")
  469. deleted = await asyncio.to_thread(
  470. _with_db, profile,
  471. lambda db: db.delete_empty_sessions(sessions_dir=_session_files_dir(profile)), read_only=False)
  472. return {"ok": True, "deleted": deleted}
  473. @manage_router.get("/api/sessions/stats")
  474. async def get_session_stats(profile: Optional[str] = None):
  475. """Session-store statistics (mirrors `hermes sessions stats`)."""
  476. def _stats(db):
  477. out = {
  478. # exclude_children=True: the dashboard Sessions page pairs these counts with
  479. # list_sessions_rich rows, which collapse compression chains to one row carrying
  480. # the tip's id — the raw row count is inflated by the hidden chain links (#54298).
  481. "total": db.session_count(include_archived=True, exclude_children=True),
  482. "active_store": db.session_count(include_archived=False, exclude_children=True),
  483. "archived": db.session_count(archived_only=True, exclude_children=True), "messages": db.message_count(),
  484. "by_source": {}}
  485. try:
  486. out["by_source"] = db.session_count_by_source(
  487. include_archived=True, exclude_children=True)
  488. except Exception:
  489. pass
  490. return out
  491. return await asyncio.to_thread(_with_db, profile, _stats, read_only=True)
  492. @manage_router.get("/api/sessions/{session_id}")
  493. async def get_session_detail(session_id: str, profile: Optional[str] = None):
  494. def _detail(db):
  495. sid = _resolve_session_id(db, session_id)
  496. session = db.get_session(sid) if sid else None
  497. if not session:
  498. raise HTTPException(status_code=404, detail=_NOT_FOUND)
  499. # Always stamp the owner: unowned default-profile rows made multi-profile
  500. # clients resolve them to whichever gateway happened to be active.
  501. session["profile"] = _serving_profile(profile)
  502. session["is_default_profile"] = session["profile"] == "default"
  503. # A cron run's liveness is scheduler ownership, not the 300s activity
  504. # window (#88443): a run inside a long tool call is still owned. A
  505. # unified-runtime run's local id names no job, so stamp its identity first.
  506. from hermes_cli.web_routers.cron import cron_run_scheduler_owned
  507. if session.get("source") == "cron":
  508. session.update(db.cron_run_identity(sid) or {})
  509. owned = cron_run_scheduler_owned(session, profile)
  510. if owned is not None:
  511. session["scheduler_owned"] = owned
  512. return session
  513. return await asyncio.to_thread(_with_db, profile, _detail, read_only=True)
  514. @manage_router.get("/api/sessions/{session_id}/mutation-snapshot")
  515. async def get_session_mutation_snapshot(session_id: str, request: Request, profile: Optional[str] = None):
  516. from hermes_cli.web_server_sessions import _session_mutation_context
  517. authority, _actor = _session_mutation_context(request, profile)
  518. if authority is None: # standalone serve: the counters the offline receipt checks
  519. row = await asyncio.to_thread(_with_db, profile, lambda db: db.get_session(session_id), read_only=True)
  520. else:
  521. row = authority.db.get_session(session_id)
  522. # An absent import anchor has revision zero by the owner's storage contract,
  523. # not by a client guessing after a failed or stale detail request.
  524. return {'session_id': session_id, 'exists': row is not None,
  525. 'runtime_revision': row['runtime_revision'] if row else 0,
  526. 'runtime_generation': row['runtime_generation'] if row else None}
  527. @manage_router.get("/api/sessions/{session_id}/latest-descendant")
  528. async def get_session_latest_descendant(session_id: str, profile: Optional[str] = None):
  529. latest, path = await asyncio.to_thread(
  530. _with_db, profile, lambda db: _session_latest_descendant(session_id, db), read_only=True)
  531. if not latest:
  532. raise HTTPException(status_code=404, detail=_NOT_FOUND)
  533. return {
  534. "requested_session_id": path[0] if path else session_id, "session_id": latest, "path": path,
  535. "changed": bool(path and latest != path[0])}
  536. def _stored_tool_call_labels(message: dict) -> dict:
  537. from agent.display import tool_labels_for_call
  538. from tools.tool_labels import BRIDGE_TOOL_NAMES
  539. out = {}
  540. for call in message.get("tool_calls") or ():
  541. if not isinstance(call, dict):
  542. continue
  543. fn = call.get("function") if isinstance(call.get("function"), dict) else {}
  544. call_id, name = str(call.get("id") or ""), str(fn.get("name") or "")
  545. if not call_id or name not in BRIDGE_TOOL_NAMES:
  546. continue
  547. try:
  548. args = json.loads(fn.get("arguments") or "{}")
  549. except (TypeError, ValueError):
  550. args = {}
  551. labels = [label.as_payload() for label in tool_labels_for_call(name, args if isinstance(args, dict) else {})]
  552. if labels:
  553. out[call_id] = labels
  554. return out
  555. def _with_tool_call_labels(message: dict) -> dict:
  556. labels = _stored_tool_call_labels(message)
  557. return {**message, "tool_call_labels": labels} if labels else message
  558. def _history_profile_home(profile):
  559. if profile:
  560. return _cron_profile_home(profile)[1]
  561. # An omitted profile reads this process's DB (including custom HERMES_HOME),
  562. # not necessarily the registered default profile used by cron routes.
  563. from hermes_cli.config import get_hermes_home
  564. return get_hermes_home()
  565. def _session_files_dir(profile) -> Path:
  566. """Transcript dir of the profile whose store a delete targets: ``SessionDB.delete_session`` only
  567. unlinks the session's on-disk artifacts when handed this, and a row-only delete leaves the
  568. (secret-bearing) ``session_<id>.json`` snapshots and ``request_dump_<id>_*.json`` readable after
  569. the user removed the session (#55088, #60207)."""
  570. return _history_profile_home(profile) / "sessions"
  571. def _is_untyped_scaffold_notice(message) -> bool:
  572. """A ``[System: …]`` role=user row persisted without a ``display_kind``.
  573. ``[System:`` is a reserved gateway-notice namespace — it must never render as a user
  574. bubble (the gateway's own history projection drops these rows outright) — but recovery
  575. scaffolding written before typing existed carries no kind. Rows WITH a kind
  576. (``model_switch``, …) are timeline entries and keep flowing.
  577. """
  578. if not isinstance(message, dict) or message.get("role") != "user" or message.get("display_kind"):
  579. return False
  580. content = message.get("content")
  581. return isinstance(content, str) and content.lstrip().startswith("[System:")
  582. def _project_for_display(messages: list, *, home=None, inline_images: bool = True) -> list:
  583. """Replace compaction summaries with their display-only projection and hide untyped
  584. gateway-scaffold notices.
  585. Recovery scaffolding (e.g. the stream-timeout nudge appended when a tool call's stream
  586. is cut) persists as a ``[System: …]`` ``role=user`` row with no ``display_kind``. This
  587. projection feeds the Desktop's transcript prefetch, which addresses VISIBLE user rows by
  588. durable row id — and the gateway truncation resolver refuses scaffold rows fail-closed,
  589. so a shipped scaffold row can never resolve as a rewind/regenerate target and dead-ends
  590. every retry (``refusing truncation without fallback``). Hide them the same way the
  591. Desktop collapses other display-only rows; typed notices stay for the timeline.
  592. """
  593. from agent.compaction_display import project_compaction_message_for_display
  594. from agent.context_compressor import is_compaction_summary_message
  595. from agent.conversation_compression import _extract_steer_text_from_message
  596. from agent.history_commentary import project_history_commentary
  597. from agent.message_metadata import withheld_prompt_text
  598. from agent.prompt_builder import STEER_DISPLAY_KIND
  599. from agent.turn_failure_copy import untyped_failed_turn_display_kind
  600. # inline_images=False (#116511): render content through the gateway's ``_coerce_message_text``
  601. # projection so a data-URI image part becomes ``[image]`` — the same branch session.resume's
  602. # ``inline_images=false`` uses, kilobytes instead of re-transmitting every stored attachment.
  603. coerce = None
  604. if not inline_images:
  605. from tui_gateway.session_history import _coerce_message_text
  606. def coerce(message: dict) -> dict:
  607. if message.get("content") is not None:
  608. return {**message, "content": _coerce_message_text(message["content"], image_urls=False)}
  609. return message
  610. projected_messages = []
  611. for message in messages:
  612. message = _with_tool_call_labels(message)
  613. if coerce is not None:
  614. message = coerce(message)
  615. # Same read-side typing as session.resume (tui_gateway/session_history.py).
  616. failed_turn = not message.get("display_kind") and untyped_failed_turn_display_kind(
  617. message.get("role"), message.get("content"))
  618. if failed_turn:
  619. message = {**message, "display_kind": failed_turn}
  620. if _is_untyped_scaffold_notice(message):
  621. projected = message.copy()
  622. projected["display_kind"] = "hidden"
  623. projected_messages.append(projected)
  624. continue
  625. # Mid-turn steer: the user's own words, not the model-facing marker (same as session.resume).
  626. if message.get("role") == "user" and message.get("display_kind") == STEER_DISPLAY_KIND and (
  627. steer_text := _extract_steer_text_from_message(message)):
  628. message = {**message, "display_content": steer_text}
  629. # A pre_llm_call veto stores a placeholder; the transcript shows what the user typed.
  630. if message.get("role") == "user" and (typed := withheld_prompt_text(message)) is not None:
  631. message = {**message, "display_content": typed}
  632. if not is_compaction_summary_message(message):
  633. projected_messages.append(message)
  634. continue
  635. display_view = project_compaction_message_for_display(message)
  636. projected = message.copy()
  637. if display_view is None:
  638. if not projected.get("display_kind"):
  639. projected["display_kind"] = "hidden"
  640. else:
  641. # Keep the physical content for inspection/export compatibility;
  642. # Desktop consumes this display-only projection. A legacy hidden
  643. # wrapper must not hide a successfully recovered live ask.
  644. projected["display_content"] = display_view.get("content")
  645. projected.pop("display_kind", None)
  646. projected_messages.append(projected)
  647. return project_history_commentary(projected_messages, home=home)
  648. @manage_router.get("/api/sessions/{session_id}/messages")
  649. async def get_session_messages(
  650. session_id: str, profile: Optional[str] = None, limit: Optional[int] = Query(None, ge=0),
  651. offset: int = Query(0, ge=0), order: Optional[str] = Query(None),
  652. include_compacted: bool = Query(False), inline_images: bool = Query(True)):
  653. if order not in (None, "oldest", "latest"):
  654. raise HTTPException(status_code=400, detail="order must be one of: oldest, latest")
  655. def _read(db):
  656. sid = _resolve_session_id(db, session_id)
  657. if not sid:
  658. return None
  659. sid = db.resolve_resume_session_id(sid)
  660. # Always page (an omitted limit used to load whole transcripts). Explicit
  661. # pagination anchors at the start; the default view is the latest page.
  662. default_page = limit is None
  663. latest_page = order == "latest" or (order is None and default_page)
  664. _limit = 500 if default_page else min(limit, 500)
  665. # Include compression-ancestor messages so the REST transcript
  666. # matches the gateway's session.resume (which uses
  667. # include_ancestors=True). Without this, the desktop's REST
  668. # prefetch only shows the child continuation's messages after a
  669. # compression rotation, hiding the pre-compaction transcript
  670. # (#51058).
  671. return sid, _limit, db.get_messages(
  672. sid, limit=_limit, offset=offset, latest=latest_page,
  673. include_compacted=include_compacted, include_ancestors=True)
  674. result = await asyncio.to_thread(_with_db, profile, _read, read_only=True)
  675. if result is None:
  676. raise HTTPException(status_code=404, detail=_NOT_FOUND)
  677. sid, _limit, messages = result
  678. projected_messages = await asyncio.to_thread(
  679. _project_for_display, messages, home=_history_profile_home(profile),
  680. inline_images=inline_images)
  681. return {
  682. "session_id": sid,
  683. # The same stamp list rows carry, so the Desktop keys a page under the
  684. # owner it already routes the session by.
  685. "profile": _serving_profile(profile),
  686. "messages": projected_messages,
  687. "pagination": {
  688. "limit": _limit, "offset": offset,
  689. "order": order or ("latest" if limit is None else "oldest"),
  690. "returned": len(projected_messages)}}
  691. def _timeline_session_id(db, session_id: str, owner: str) -> str:
  692. # Durable jump addresses are exact ids, never title/prefix guesses. A NULL
  693. # legacy owner belongs to this profile's store, just like /messages pages.
  694. def owned(sid):
  695. row = db._read_one("SELECT profile_name FROM sessions WHERE id = ?", (sid,))
  696. return row is not None and row["profile_name"] in (None, owner)
  697. if not owned(session_id):
  698. raise HTTPException(status_code=404, detail=_NOT_FOUND)
  699. sid = db.resolve_resume_session_id(session_id)
  700. if not owned(sid):
  701. raise HTTPException(status_code=404, detail=_NOT_FOUND)
  702. return sid
  703. @manage_router.get("/api/sessions/{session_id}/timeline")
  704. async def get_session_timeline(
  705. session_id: str, profile: Optional[str] = None,
  706. limit: int = Query(500, ge=1, le=500), after_row_id: int = Query(0, ge=0),
  707. ):
  708. """Prompt metadata only, including compacted display history (never rewind rows).
  709. ``next_cursor`` is a stable logical first-row id; pass it as ``after_row_id``.
  710. Entry ``row_id`` addresses the current representative for /messages/around.
  711. """
  712. from hermes_state_timeline import get_session_timeline as read_timeline
  713. owner = _serving_profile(profile)
  714. def _read(db):
  715. sid = _timeline_session_id(db, session_id, owner)
  716. return {"session_id": sid, "profile": owner,
  717. **read_timeline(db, sid, limit=limit, after_row_id=after_row_id)}
  718. return await asyncio.to_thread(_with_db, profile, _read, read_only=True)
  719. @manage_router.get("/api/sessions/{session_id}/messages/around")
  720. async def get_session_messages_around(
  721. session_id: str, row_id: int = Query(..., ge=1), profile: Optional[str] = None,
  722. limit: int = Query(120, ge=1, le=120),
  723. ):
  724. """Bounded display page starting at a timeline prompt; no intervening payloads."""
  725. from hermes_state_timeline import get_session_messages_around as read_around
  726. owner = _serving_profile(profile)
  727. def _read(db):
  728. sid = _timeline_session_id(db, session_id, owner)
  729. page = read_around(db, sid, row_id, limit=limit)
  730. if page is None:
  731. raise HTTPException(status_code=404, detail="Prompt not found")
  732. return {"session_id": sid, "profile": owner, **page}
  733. result = await asyncio.to_thread(_with_db, profile, _read, read_only=True)
  734. result["messages"] = await asyncio.to_thread(
  735. _project_for_display, result["messages"], home=_history_profile_home(profile))
  736. return result
  737. @manage_router.delete("/api/sessions/{session_id}")
  738. async def delete_session_endpoint(session_id: str, request: Request, profile: Optional[str] = None,
  739. request_id: Optional[str] = None, expected_revision: Optional[int] = None,
  740. expected_generation: Optional[int] = None):
  741. from hermes_cli.web_server_sessions import _mutate_session_request
  742. from hermes_state import SessionDB
  743. try:
  744. result = await _mutate_session_request(request, profile, session_id,
  745. request_id=request_id, expected_revision=expected_revision,
  746. expected_generation=expected_generation, operation='delete', payload={})
  747. except HTTPException as exc:
  748. # Already-absent is an idempotent success: the desktop optimistically removes the row
  749. # and RESTORES it on any error, so a 404 resurrected ghost rows (a row deleted by
  750. # another client between the sidebar snapshot and this DELETE). An exact retry of the
  751. # caller's own committed request never reaches here: mutate_session checks the receipt
  752. # before resolving the id, so it replays that receipt (or 409s on a changed digest).
  753. # The authority also answers ``not_found`` for an EXISTING cold row it cannot restore
  754. # (e.g. an API-server row without its binding); that row was not deleted, so only a
  755. # genuinely absent id is the idempotent success.
  756. if exc.status_code == 404 and exc.detail == 'not_found' and await asyncio.to_thread(
  757. _with_db, profile, lambda db: db.get_session(session_id) is None, read_only=True):
  758. return {"ok": True, "already_absent": True}
  759. raise
  760. # The canonical delete retires rows only: scrub each deleted session's on-disk artifacts
  761. # (secret-bearing ``session_<id>.json`` snapshots, ``request_dump_<id>_*.json``) as the CLI
  762. # delete path does (#60207). Idempotent, so an exact retry of the receipt repeats it safely.
  763. sessions_dir = _session_files_dir(profile)
  764. for sid in result.get('deleted_ids') or ():
  765. await asyncio.to_thread(SessionDB._remove_session_files, sessions_dir, str(sid))
  766. return result
  767. def _owner_db_for(request: Request, profile: Optional[str]):
  768. """The live owner's own store for *profile* when a composed gateway serves it, else None."""
  769. runner = getattr(request.app.state, "gateway_runner", None)
  770. if runner is None:
  771. return None
  772. from gateway.session_authorities import authority_for_home
  773. from hermes_state import _default_db_path
  774. home = Path(_cron_profile_home(profile)[1]) if profile else Path(_default_db_path()).parent
  775. authority = authority_for_home(runner, home)
  776. return getattr(authority, "db", None)
  777. @manage_router.post("/api/sessions/owner-backfill")
  778. async def backfill_session_owner_profiles(body: SessionOwnerBackfill, request: Request):
  779. """Stamp legacy ``profile_name = NULL`` rows with the serving-profile identity.
  780. A multi-connection Desktop fails closed on unowned rows. Each ``state.db``
  781. belongs to exactly one profile, so this is a single-match, idempotent
  782. backfill (non-NULL owners are never overwritten).
  783. That was fine while one backend served everything, but a Desktop with registry topology (≥2 registered
  784. connections) fails closed on unowned rows by design — leaving every pre-campaign session unresumable
  785. with no migration path. Each profile's ``state.db`` belongs to exactly one profile, so stamping that
  786. store's own name is a single-match backfill, never a guess; the value written is the SAME
  787. serving-profile identity the list endpoints already stamp onto outgoing rows (``row_profile`` in
  788. ``get_sessions``). See #95407.
  789. """
  790. stamp = _serving_profile(body.profile)
  791. with http_failure(
  792. "POST /api/sessions/owner-backfill failed", 500, detail="Internal server error"):
  793. owner_db = _owner_db_for(request, body.profile)
  794. if owner_db is not None:
  795. # A live gateway owns this store: it is the only writer (the offline maintenance lock
  796. # would 409 every Desktop boot), so the idempotent stamp runs on its own connection.
  797. stamped = await asyncio.to_thread(owner_db.backfill_null_session_profiles, stamp)
  798. else:
  799. stamped = await asyncio.to_thread(
  800. _with_db, body.profile, lambda db: db.backfill_null_session_profiles(stamp),
  801. read_only=False)
  802. if stamped:
  803. _log.info(
  804. "owner-backfill: stamped %d legacy NULL-profile session row(s) with profile %r",
  805. stamped, stamp)
  806. return {"ok": True, "stamped": stamped, "profile": stamp}
  807. @manage_router.patch("/api/sessions/{session_id}")
  808. async def rename_session_endpoint(session_id: str, body: SessionRename, request: Request):
  809. """Title and sidebar flags share one authoritative revision and receipt."""
  810. from hermes_cli.web_server_sessions import _mutate_session_request
  811. payload = {key: getattr(body, key) for key in ('title', 'archived', 'hidden', 'pinned', 'unread')
  812. if getattr(body, key) is not None}
  813. return await _mutate_session_request(request, body.profile, session_id,
  814. request_id=body.request_id, expected_revision=body.expected_revision,
  815. expected_generation=body.expected_generation, operation='sidebar', payload=payload)
  816. def _compact_json(obj) -> str:
  817. return json.dumps(jsonable_encoder(obj), ensure_ascii=False, separators=(",", ":"))
  818. @manage_router.get("/api/sessions/{session_id}/export")
  819. async def export_session_endpoint(session_id: str, profile: Optional[str] = None):
  820. """Stream a single session (metadata + messages) as JSON."""
  821. def _prepare_export(db):
  822. sid = _resolve_session_id(db, session_id)
  823. return (sid, db.get_session(sid)) if sid else None
  824. prepared = await asyncio.to_thread(_with_db, profile, _prepare_export, read_only=True)
  825. if prepared is None or prepared[1] is None:
  826. raise HTTPException(status_code=404, detail=_NOT_FOUND)
  827. sid, session = prepared
  828. def _stream_export():
  829. db = _open_session_db_for_profile(profile, read_only=True)
  830. try:
  831. yield _compact_json(session)[:-1] + ',"messages":['
  832. # Keyset pagination (id > last_seen): O(n) total over the
  833. # transcript, vs OFFSET's O(n²) on huge sessions. Every row with its
  834. # active/compacted flags, so re-importing restores compacted history as archived.
  835. last_id, first = 0, True
  836. while True:
  837. messages = db.get_messages(sid, limit=500, after_id=last_id, include_inactive=True)
  838. for message in messages:
  839. yield ("" if first else ",") + _compact_json(message)
  840. first = False
  841. last_id = messages[-1].get("id") if len(messages) == 500 else None
  842. if last_id is None: # short page, or cannot keyset without row ids
  843. break
  844. yield "]}"
  845. finally:
  846. db.close()
  847. return StreamingResponse(_stream_export(), media_type="application/json")
  848. @manage_router.post("/api/sessions/prune")
  849. async def prune_sessions_endpoint(body: SessionPrune):
  850. """Delete ended sessions matching filters without blocking the event loop."""
  851. if body.dry_run:
  852. return await asyncio.to_thread(_prune_sessions, body)
  853. # Same destructive rule as the rest of the family; a dry run deletes nothing, so it
  854. # keeps working unnamed (it is the preview the confirm dialog reads).
  855. body = body.model_copy(update={
  856. "profile": destructive_profile(body.profile, "POST /api/sessions/prune")})
  857. from hermes_cli.web_server_sessions import _with_session_maintenance
  858. return await asyncio.to_thread(_with_session_maintenance, body.profile, _prune_sessions, body)