sessions_cmd.py 68 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462
  1. """``hermes sessions`` command.
  2. ``cmd_sessions`` routes ``args.sessions_action`` through ``_PRE_DB_HANDLERS`` (repair / recover /
  3. import — must run without opening ``SessionDB()``, which a malformed schema prevents) and
  4. ``_DB_HANDLERS`` (everything else, sharing one ``SessionDB``). ``get_hermes_home`` is resolved through
  5. ``hermes_cli.main`` at call time so monkeypatches keep working. Picker: :mod:`hermes_cli.sessions_cmd_browse`.
  6. """
  7. import json
  8. import os
  9. import shutil
  10. import sqlite3
  11. import sys
  12. from functools import partial
  13. from pathlib import Path
  14. from hermes_cli.cli_output import print_truncated
  15. from hermes_cli.sessions_cmd_browse import _relative_time, _session_browse_picker
  16. from hermes_state_errors import SessionActiveWriteGuardError
  17. def get_hermes_home():
  18. from hermes_cli import main
  19. return main.get_hermes_home()
  20. def _sessions_dir() -> Path:
  21. return get_hermes_home() / "sessions"
  22. def _size_mb(path) -> float:
  23. return os.path.getsize(path) / (1024 * 1024) if path.exists() else 0.0
  24. def _size_delta_label(saved_mb: float) -> str:
  25. """A negative delta means the file GREW (concurrent writes during a long optimize); "reclaimed
  26. -163.0 MB" reads as data loss, so say "grew by"."""
  27. return f"reclaimed {saved_mb:.1f} MB" if saved_mb >= 0 else f"grew by {-saved_mb:.1f} MB"
  28. def _confirm_prompt(prompt: str) -> bool | None:
  29. """Prompt for y/N confirmation. ``None`` when stdin is not a terminal and hits EOF (/dev/null, an empty
  30. pipe: cron, a wrapper), which is not the same as the user saying no; Ctrl-D at a terminal is a no.
  31. Ctrl-C propagates: an interrupt is neither a no nor a success."""
  32. try:
  33. return input(prompt).strip().lower() in {"y", "yes"}
  34. except EOFError:
  35. print()
  36. # isatty() alone is True for Windows NUL; the console check keeps `< NUL` unattended (#113977).
  37. from hermes_cli.gateway_windows import _stdin_console_mode_ok, _stdin_is_interactive
  38. return False if _stdin_is_interactive(isatty=sys.stdin.isatty(), console_mode_ok=_stdin_console_mode_ok()) else None
  39. def _confirm_or_exit_code(prompt: str, *, declined: str = "Cancelled.", unattended: str | None = "--yes") -> int | None:
  40. """``None`` to proceed, else the exit code after saying why not. A decline exits 0; a run nobody could
  41. answer exits 1, so a cron job or wrapper that forgot *unattended* does not read "nothing happened" as
  42. success."""
  43. try:
  44. answer = _confirm_prompt(prompt)
  45. except KeyboardInterrupt:
  46. print("\nInterrupted; nothing was changed.")
  47. return 130
  48. if answer:
  49. return None
  50. if answer is None:
  51. hint = f" Pass {unattended} to run it unattended." if unattended else " Run it from an interactive terminal."
  52. print(f"No answer on a non-interactive stdin; nothing was changed.{hint}")
  53. return 1
  54. print(declined)
  55. return 0
  56. def _not_found(session_id) -> int:
  57. print(f"No session '{session_id}'. Run: hermes sessions list to find the id.")
  58. return 1
  59. def _print_dry_run_preview(candidates, filters) -> None:
  60. from hermes_cli.session_filters import describe_filters
  61. print(f"Would export {len(candidates)} session(s) ({describe_filters(filters)}).")
  62. for row in candidates[:100]:
  63. print(f" {row.get('id')} {row.get('source', '')}")
  64. if len(candidates) > 100:
  65. print_truncated(len(candidates) - 100)
  66. _FILTER_ARGS = (
  67. "older_than", "newer_than", "before", "after", "source", "title", "end_reason", "cwd", "min_messages",
  68. "max_messages", "model", "provider", "user", "chat_id", "chat_type", "branch", "min_tokens", "max_tokens",
  69. "min_cost", "max_cost", "min_tool_calls", "max_tool_calls",
  70. )
  71. def _any_filter_args(args) -> bool:
  72. return any(getattr(args, a, None) is not None for a in _FILTER_ARGS)
  73. def _export_dir(output) -> Path:
  74. """``--output`` dir for multi-file exports; ``~/.hermes/session-exports`` when empty or ``-``."""
  75. return Path(output).expanduser() if output and output != "-" else get_hermes_home() / "session-exports"
  76. def _output_file_in_dir(output, default_name: str):
  77. """Single-file exports accept a directory too (``--help`` calls the positional a path, and md/qmd take
  78. one): an existing directory, or one spelled with a trailing separator, means ``<dir>/<default_name>``."""
  79. if not output or output == "-":
  80. return output
  81. if output.endswith(("/", os.sep)) or os.path.isdir(output):
  82. os.makedirs(output, exist_ok=True)
  83. return os.path.join(output, default_name)
  84. return output
  85. def _write_output(output, text, summary) -> None:
  86. """Write to stdout when *output* is empty or ``-``; else to the file + print *summary*."""
  87. if not output or output == "-":
  88. sys.stdout.write(text)
  89. return
  90. with open(output, "w", encoding="utf-8") as f:
  91. f.write(text)
  92. print(summary)
  93. # -- handlers that must run BEFORE SessionDB() is opened ----------------------
  94. def _cmd_repair(args):
  95. from hermes_state import DEFAULT_DB_PATH as db_path, SessionDB
  96. from hermes_state_repair import _db_opens_cleanly, repair_state_db_schema
  97. if not db_path.exists():
  98. print(f"No session database at {db_path} (nothing to repair).")
  99. return
  100. from hermes_state_reconcile import repair_declarative_schema, schema_drift_reason
  101. # A missing canonical sessions table is not additive upgrade drift: creating
  102. # an empty one could hide lost history. Preserve corruption/recovery routing.
  103. reason = _db_opens_cleanly(db_path)
  104. # Opens cleanly but lags SCHEMA_SQL: additive drift (snapshot reconcile), not corruption surgery.
  105. drift_only = reason is None
  106. if drift_only:
  107. try:
  108. reason = schema_drift_reason(db_path)
  109. except (sqlite3.Error, OSError) as exc:
  110. print(f"✗ Could not check session schema: {exc}")
  111. return 1
  112. repair = repair_declarative_schema if drift_only else repair_state_db_schema
  113. if reason is None:
  114. print(f"✓ {db_path} opens cleanly — no repair needed.")
  115. return
  116. print(f"✗ {db_path} does not open cleanly: {reason}")
  117. if getattr(args, "check_only", False):
  118. return 1
  119. print("Repairing (a backup copy is made first)…")
  120. report = repair(db_path, backup=not getattr(args, "no_backup", False))
  121. if report.get("repaired"):
  122. if report.get("backup_path"):
  123. print(f" backup: {report['backup_path']}")
  124. print(f" strategy: {report.get('strategy')}")
  125. try:
  126. with SessionDB(db_path=db_path, read_only=drift_only) as _repair_db:
  127. n = _repair_db._conn.execute("SELECT COUNT(*) FROM sessions").fetchone()[0]
  128. print(f"✓ Repaired — {n} sessions recovered.")
  129. except Exception:
  130. print("✓ Repaired.")
  131. return
  132. print(f"✗ Repair failed: {report.get('error')}")
  133. if drift_only:
  134. if report.get('backup_path'):
  135. print(f" A backup is preserved at: {report['backup_path']}")
  136. return 1
  137. if report.get("backup_path"):
  138. print(f" A backup is preserved at: {report['backup_path']}")
  139. # Without this pointer the user is at a dead end; lead with --inspect-only before writing.
  140. source_hint = report.get("backup_path") or db_path
  141. print(
  142. " Keep state.db and the backup; do not delete them.\n"
  143. "\n Next step — offline recovery (never modifies the source):\n"
  144. f" hermes sessions recover --source {source_hint} \\\n"
  145. " --inspect-only\n"
  146. " If that reports the data is recoverable, rebuild it into\n"
  147. " a NEW database (the active one is left untouched):\n"
  148. f" hermes sessions recover --source {source_hint} \\\n"
  149. " --output recovered-state.db"
  150. )
  151. return 1
  152. def _cmd_recover(args):
  153. """Offline recovery: works on a disposable copy of the source; never touches the active database."""
  154. import sqlite3
  155. from hermes_cli.session_recovery import (
  156. SessionRecoveryError, inspect_session_database, recover_session_database, write_recovery_report,
  157. )
  158. source, output = args.source, getattr(args, "output", None)
  159. inspect_only = bool(getattr(args, "inspect_only", False))
  160. allow_partial = bool(getattr(args, "allow_partial", False))
  161. report_path = getattr(args, "report", None)
  162. if not inspect_only and output is not None and report_path is None:
  163. report_path = output.with_name(output.name + ".recovery.json")
  164. usage_errors = (
  165. (inspect_only and output is not None, "--output cannot be used with --inspect-only."),
  166. (inspect_only and allow_partial, "--allow-partial cannot be used with --inspect-only."),
  167. (not inspect_only and output is None, "--output is required unless --inspect-only is used."),
  168. (
  169. report_path is not None and os.path.lexists(report_path.expanduser()),
  170. f"refusing to overwrite existing report: {report_path}",
  171. ),
  172. )
  173. for bad, msg in usage_errors:
  174. if bad:
  175. print(f"Error: {msg}")
  176. return 2
  177. work_dir = getattr(args, "work_dir", None)
  178. try:
  179. if inspect_only:
  180. report = inspect_session_database(source, work_dir=work_dir)
  181. else:
  182. print("Recovering canonical session data into a new database…")
  183. progress = _RecoveryProgress()
  184. report = recover_session_database(
  185. source, output, work_dir=work_dir, chunk_size=getattr(args, "chunk_size", 1000),
  186. progress_cb=progress, allow_partial=allow_partial,
  187. )
  188. progress.finish()
  189. except (SessionRecoveryError, OSError, sqlite3.DatabaseError) as exc:
  190. print(f"Error: session recovery failed: {exc}\nThe supplied source database was not replaced or deleted.")
  191. return 1
  192. if report_path is None:
  193. print(json.dumps(report, indent=2, sort_keys=True))
  194. else:
  195. try:
  196. print(f"Recovery report: {write_recovery_report(report_path, report)}")
  197. except (FileExistsError, OSError) as exc:
  198. print(f"Error: could not write recovery report: {exc}")
  199. return 1
  200. if inspect_only:
  201. return 0 if report.get("recoverable") else 1
  202. return _print_recovery_verdict(report, output, allow_partial)
  203. class _RecoveryProgress:
  204. """`recover` progress printer: one live-updating `` <table>: n/total`` line per table."""
  205. table = None
  206. def __call__(self, info):
  207. table = info.get("table")
  208. if table != self.table:
  209. self.finish()
  210. print(f" {table}: ", end="", flush=True)
  211. self.table = table
  212. total = info.get("source_rows")
  213. suffix = f"/{int(total):,}" if total is not None else ""
  214. print(f"\r {table}: {int(info.get('copied_rows') or 0):,}{suffix}", end="", flush=True)
  215. def finish(self):
  216. if self.table is not None:
  217. print()
  218. def _print_recovery_verdict(report, output, allow_partial) -> int:
  219. if report.get("complete"):
  220. print(
  221. f"✓ Recovered database verified at: {output}\n"
  222. " The active session database was not changed.\n"
  223. " Review the JSON report before installing this database."
  224. )
  225. return 0
  226. if allow_partial and report.get("verified"):
  227. counts = report.get("verification", {}).get("table_counts", {})
  228. if report.get("best_effort"):
  229. print(
  230. f"✓ BEST-EFFORT page-level salvage verified at: {output}\n"
  231. " The source table schemas were unreadable; rows were rebuilt from raw pages "
  232. "via sqlite3 .recover and mapped heuristically."
  233. )
  234. else:
  235. print(f"✓ Partial recovery output verified at: {output}")
  236. sessions_n, messages_n = int(counts.get("sessions") or 0), int(counts.get("messages") or 0)
  237. print(
  238. f" Recovered {sessions_n:,} sessions and {messages_n:,} messages.\n"
  239. " The active session database was not changed.\n"
  240. " This output is incomplete. Review every skipped range and orphan count in the "
  241. "JSON report before installing it."
  242. )
  243. return 0
  244. print(
  245. "✗ Recovery output did not pass every verification check.\n"
  246. " Do not install it. Review the JSON report for partial data or errors."
  247. )
  248. return 1
  249. def _cmd_import(args):
  250. from hermes_cli.foreign_sessions import run_sessions_import
  251. # Explicit path but nothing imported -> non-zero for scripts. Picker cancel (no path) -> exit 0.
  252. if run_sessions_import(args) is None and getattr(args, "path", None):
  253. return 1
  254. # -- handlers that receive an open SessionDB ----------------------------------
  255. def _default_exclude(args):
  256. """Hide third-party tool sessions by default, but honour explicit --source."""
  257. return None if getattr(args, "source", None) else ["tool"]
  258. def _surface_reader(db):
  259. """``--source cli`` also matches a gateway row stored as ``local`` with that created surface."""
  260. from hermes_cli.gateway_session_store import SurfaceLabelReader
  261. return SurfaceLabelReader(db)
  262. def _cmd_list(db, args):
  263. from hermes_state_sessions import workspace_key as _ws_key
  264. # LIMIT lives in the query, so probe one row past the cap: it is the only way to know the
  265. # page was cut without a second COUNT query (``--limit 0`` is ``LIMIT 0``: no rows, no probe).
  266. limit = args.limit
  267. sessions = _surface_reader(db).list_sessions_rich(
  268. source=args.source, exclude_sources=_default_exclude(args), limit=limit + 1 if limit > 0 else limit,
  269. )
  270. truncated = limit > 0 and len(sessions) > limit
  271. sessions = sessions[:limit] if truncated else sessions
  272. # Workspace filter: workspace key (git repo root, else cwd) — path substring or exact basename.
  273. _ws_filter = (getattr(args, "workspace", None) or "").strip()
  274. if _ws_filter:
  275. _needle = _ws_filter.lower()
  276. keyed = ((s, (_ws_key(s) or "").lower()) for s in sessions)
  277. sessions = [
  278. s for s, key in keyed if key and (_needle in key or _needle == os.path.basename(key.rstrip("/\\")))
  279. ]
  280. if not sessions:
  281. print("No sessions found.")
  282. return
  283. # Workspace column only when some session carries a key (or when filtering): unbound listings read as before.
  284. has_ws = bool(_ws_filter) or any(_ws_key(s) for s in sessions)
  285. has_titles = any(s.get("title") for s in sessions)
  286. def _ws(s): # repo/dir basename, "—" when unbound
  287. key = _ws_key(s)
  288. return ((os.path.basename(key.rstrip("/\\")) or key) if key else "—")[:16]
  289. _title = lambda s, n: (s.get("title") or "—")[:n]
  290. _preview = lambda s, n: s.get("preview", "")[:n]
  291. _ago = lambda s: _relative_time(s.get("last_active"), session_id=s["id"])
  292. def _src(s): # current routing platform; "<created>→<current>" when provenance diverged (#56439)
  293. created = s.get("created_source") or ""
  294. return f"{created}→{s['source']}" if created and created != s["source"] else s["source"]
  295. layouts = { # (has_ws, has_titles): header, rule width, row formatter
  296. (True, True): (f"{'Title':<28} {'Workspace':<18} {'Last Active':<13} {'ID'}", 110,
  297. lambda s: f"{_title(s, 26):<28} {_ws(s):<18} {_ago(s):<13} {s['id']}"),
  298. (True, False): (f"{'Preview':<38} {'Workspace':<18} {'Last Active':<13} {'Src':<16} {'ID'}", 110,
  299. lambda s: f"{_preview(s, 36):<38} {_ws(s):<18} {_ago(s):<13} {_src(s):<16} {s['id']}"),
  300. (False, True): (f"{'Title':<32} {'Preview':<40} {'Last Active':<13} {'ID'}", 110,
  301. lambda s: f"{_title(s, 30):<32} {_preview(s, 38):<40} {_ago(s):<13} {s['id']}"),
  302. (False, False): (f"{'Preview':<50} {'Last Active':<13} {'Src':<16} {'ID'}", 105,
  303. lambda s: f"{_preview(s, 48):<50} {_ago(s):<13} {_src(s):<16} {s['id']}"),
  304. }
  305. header, rule, fmt = layouts[(has_ws, has_titles)]
  306. print(header + "\n" + "─" * rule)
  307. for s in sessions:
  308. print(fmt(s))
  309. if truncated:
  310. print_truncated(None, f"use --limit {limit * 2} to see more")
  311. # -- export -----------------------------------------------------------------
  312. def _cmd_export(db, args):
  313. from hermes_cli.session_filters import build_prune_filters
  314. filters = None
  315. if _any_filter_args(args):
  316. try:
  317. filters = build_prune_filters(args)
  318. except ValueError as e:
  319. print(f"Error: {e}")
  320. return 1
  321. # A backup includes protected rows; prune's keep rules must not omit them.
  322. filters["archived"] = None
  323. filters["include_pinned"] = True
  324. if args.session_id and not db.resolve_session_id(args.session_id):
  325. return _not_found(args.session_id)
  326. def _redact(data):
  327. if not args.redact or data is None:
  328. return data
  329. from hermes_cli.session_export_md import redact_session_data
  330. return redact_session_data(data)
  331. from hermes_cli.session_export import SAVE_TRANSCRIPT_FORMATS, export_projection
  332. # --only is a transcript view too (md/jsonl of what the user saw); md/qmd without --only go to _export_markdown.
  333. shown = args.format in SAVE_TRANSCRIPT_FORMATS or bool(getattr(args, "only", None))
  334. projection = export_projection(shown)
  335. def _too_large(session_ids=None) -> bool:
  336. """The transfer projection holds every stored row in memory: the console export's per-session
  337. ``sessions.max_export_messages`` guard (0 disables) runs before any is loaded. ``None`` = the
  338. sessions a bare export loads."""
  339. from hermes_state import SessionExportTooLargeError, resolved_max_export_messages
  340. if shown:
  341. return False
  342. limit = resolved_max_export_messages()
  343. if limit == 0:
  344. return False # resolved before the bare-path scan: a disabled guard costs nothing
  345. if session_ids is None:
  346. session_ids = [s["id"] for s in db.search_sessions(source=None, limit=100000)]
  347. try:
  348. db.assert_exports_safe(session_ids, max_messages=limit)
  349. except SessionExportTooLargeError as exc:
  350. print(f"Error: {exc}")
  351. return True
  352. return False
  353. def _collect_sessions():
  354. """--session-id / filters / bare export -> redacted session dicts, None after a dry-run preview,
  355. or an exit code after printing an error."""
  356. def _one(session_id):
  357. return _redact(db.export_session(session_id, **projection))
  358. if args.session_id:
  359. resolved = db.resolve_session_id(args.session_id)
  360. if resolved and _too_large([resolved]):
  361. return 1
  362. data = _one(resolved) if resolved else None
  363. if not data:
  364. return _not_found(args.session_id)
  365. return [data]
  366. if filters:
  367. candidates = db.list_prune_candidates(**filters)
  368. if args.dry_run:
  369. return _print_dry_run_preview(candidates, filters)
  370. if _too_large([row["id"] for row in candidates]):
  371. return 1
  372. return [s for s in (_one(row["id"]) for row in candidates) if s]
  373. if args.dry_run:
  374. print("--dry-run requires at least one filter.")
  375. return 1
  376. if _too_large():
  377. return 1
  378. return [_redact(s) for s in db.export_all(source=None, **projection)]
  379. if getattr(args, "only", None):
  380. return _export_flat("only", args, _collect_sessions)
  381. if args.format == "trace":
  382. return _export_trace(db, args, filters)
  383. if args.format in _FLAT_EXPORTERS:
  384. return _export_flat(args.format, args, _collect_sessions)
  385. return _export_markdown(db, args, filters, _redact)
  386. def _render_only(args, sessions):
  387. """--only user-prompts: one prompt record per line (jsonl) or headed sections (md)."""
  388. from hermes_cli.session_export import export_record_count, render_sessions_export
  389. rendered = render_sessions_export(sessions, fmt="markdown" if args.format == "md" else "jsonl", only=args.only)
  390. count, noun = export_record_count(sessions, only=args.only)
  391. return rendered, f"Exported {count} {noun}{'' if count == 1 else 's'} to {args.output}"
  392. def _render_html(args, sessions):
  393. """One self-contained file (single session, or multi-session with sidebar)."""
  394. from hermes_cli.session_export_html import generate_html_export, generate_multi_session_html_export
  395. single = len(sessions) == 1
  396. content = generate_html_export(sessions[0]) if single else generate_multi_session_html_export(sessions)
  397. return content, f"Exported {len(sessions)} {'session' if single else 'sessions'} to {args.output} (HTML)"
  398. def _render_jsonl(args, sessions):
  399. lines = "".join(json.dumps(s, ensure_ascii=False) + "\n" for s in sessions)
  400. return lines, f"Exported {len(sessions)} {'session' if args.session_id else 'sessions'} to {args.output}"
  401. #: kind -> (usage error when the --output/--format combination is unusable, renderer)
  402. _FLAT_EXPORTERS = {
  403. "only": (
  404. lambda a: a.format not in ("jsonl", "md"), "--only user-prompts supports --format jsonl or md.", _render_only
  405. ),
  406. "html": (lambda a: not a.output or a.output == "-", "HTML export requires an output file path.", _render_html),
  407. "jsonl": (lambda a: not a.output, "JSONL export requires an output path (use - for stdout).", _render_jsonl),
  408. }
  409. def _export_flat(kind, args, collect):
  410. """Single-file export: validate the output target, collect sessions, render, write."""
  411. unusable, message, render = _FLAT_EXPORTERS[kind]
  412. if unusable(args):
  413. print(message)
  414. return 1
  415. sessions = collect()
  416. if isinstance(sessions, int):
  417. return sessions
  418. if sessions is not None:
  419. from hermes_cli.session_export import default_save_filename
  420. name = (default_save_filename(sessions[0].get("id", ""), args.format) if len(sessions) == 1
  421. else f"hermes_sessions.{args.format}")
  422. args.output = _output_file_in_dir(args.output, name)
  423. _write_output(args.output, *render(args, sessions))
  424. def _export_trace(db, args, filters):
  425. """Claude Code JSONL trace export — local file or HF upload. Redaction is ON by default (traces
  426. leave the machine with --upload); --no-redact opts out."""
  427. session_id = args.session_id
  428. if not session_id and not filters: # "the last thing I did"
  429. rows = db.list_sessions_rich(limit=1, order_by_last_active=True)
  430. session_id = rows[0].get("id") if rows else None
  431. if not session_id:
  432. print("No session found to export. Pass --session-id.")
  433. return 1
  434. from agent.trace_upload import TraceRedactionError, build_trace_jsonl, upload_session_trace
  435. redact_trace = not getattr(args, "no_redact", False)
  436. if getattr(args, "upload", False):
  437. if not session_id:
  438. print("--upload exports one session: pass --session-id (or drop filters to use the most recent).")
  439. return 1
  440. resolved = db.resolve_session_id(session_id)
  441. db.close()
  442. print(upload_session_trace(resolved, cwd="", redact=redact_trace, private=not getattr(args, "public", False)))
  443. return
  444. if session_id:
  445. ids = [db.resolve_session_id(session_id)]
  446. else:
  447. candidates = db.list_prune_candidates(**filters)
  448. if args.dry_run:
  449. return _print_dry_run_preview(candidates, filters)
  450. ids = [row["id"] for row in candidates]
  451. def _render_trace(sid):
  452. meta = db.get_session(sid) or {}
  453. messages = db.get_messages_as_conversation(sid)
  454. if not messages:
  455. return None
  456. return build_trace_jsonl(messages, session_id=sid, model=meta.get("model") or "", cwd="", redact=redact_trace)
  457. try:
  458. if len(ids) == 1:
  459. jsonl = _render_trace(ids[0])
  460. if not jsonl:
  461. print(f"No transcript to export for session '{ids[0]}'.")
  462. return 1
  463. args.output = _output_file_in_dir(args.output, f"{ids[0]}.trace.jsonl")
  464. _write_output(args.output, jsonl, f"Exported 1 session trace to {args.output}")
  465. else:
  466. out_dir = _export_dir(args.output)
  467. out_dir.mkdir(parents=True, exist_ok=True)
  468. exported = 0
  469. for sid in ids:
  470. jsonl = _render_trace(sid)
  471. if jsonl:
  472. (out_dir / f"{sid}.trace.jsonl").write_text(jsonl, encoding="utf-8")
  473. exported += 1
  474. print(f"Exported {exported} session trace(s) to {out_dir}")
  475. except TraceRedactionError:
  476. print("Redaction failed; refusing to export unredacted trace content.")
  477. return 1
  478. def _export_markdown(db, args, filters, redact):
  479. """Markdown / QMD export: one file per session plus a manifest entry."""
  480. from hermes_cli.session_export_md import append_manifest_entry, write_session_markdown
  481. if args.output == "-":
  482. print("Markdown/QMD export writes files; stdout (-) is only supported with --format jsonl.")
  483. return 1
  484. output_dir = _export_dir(args.output)
  485. def _export_one(session_id: str, *, include_lineage: bool = False):
  486. # The history the user sees, not only the live rows: in-place compaction archives earlier turns under
  487. # the same id, and --delete-after-verified removes every row of it.
  488. export = db.export_session_lineage if include_lineage else db.export_session
  489. raw_data = export(session_id, include_compacted=True)
  490. if not raw_data:
  491. return None, None, None
  492. snapshots = {
  493. segment["id"]: segment.get("messages") or []
  494. for segment in (raw_data.get("segments") or [raw_data]) if segment.get("id")
  495. }
  496. data = redact(raw_data)
  497. path = write_session_markdown(data, output_dir, fmt=args.format, force=args.force)
  498. append_manifest_entry(output_dir, data, path, fmt=args.format)
  499. return data, path, snapshots
  500. if args.delete_after_verified and not args.yes:
  501. print("--delete-after-verified requires --yes.")
  502. return 1
  503. if args.delete_after_verified and not args.session_id:
  504. print("--delete-after-verified is only supported with --session-id.")
  505. return 1
  506. lineage_is_logical = getattr(args, "lineage", "single") == "logical"
  507. if args.session_id:
  508. return _export_markdown_single(db, args, _export_one, output_dir, lineage_is_logical)
  509. if not filters:
  510. print("Refusing bulk export without a filter. Pass --session-id or "
  511. "at least one filter (e.g. --older-than 90, --source telegram).")
  512. return 1
  513. candidates = db.list_prune_candidates(**filters)
  514. if args.dry_run:
  515. return _print_dry_run_preview(candidates, filters)
  516. exported = 0
  517. for row in candidates:
  518. try:
  519. data, exported_path, _ = _export_one(row["id"], include_lineage=lineage_is_logical)
  520. except FileExistsError as e:
  521. print(f"Skipping existing export: {e}. Pass --force to overwrite.")
  522. continue
  523. if data and exported_path:
  524. exported += 1
  525. print(f"Exported {exported} session(s) to {output_dir}")
  526. def _export_markdown_single(db, args, export_one, output_dir, lineage_is_logical):
  527. """--session-id markdown export, optionally + verified delete of it and its delegates."""
  528. from hermes_cli.session_export_md import verify_export_file
  529. resolved_session_id = db.resolve_session_id(args.session_id)
  530. delete_target_ids = (
  531. db.get_session_delete_targets(resolved_session_id) if args.delete_after_verified else [resolved_session_id]
  532. )
  533. exported_items = []
  534. for target_id in delete_target_ids:
  535. try:
  536. data, exported_path, snapshots = export_one(
  537. target_id, include_lineage=(target_id == resolved_session_id and lineage_is_logical),
  538. )
  539. except FileExistsError as e:
  540. print(f"Export already exists: {e}. Pass --force to overwrite.")
  541. return 1
  542. if not data or not exported_path:
  543. print(f"Session '{target_id}' disappeared during export; nothing was deleted.")
  544. return 1
  545. exported_items.append((data, exported_path, snapshots))
  546. message_count = sum(len(data.get("messages") or []) for data, _path, _ in exported_items)
  547. n = len(exported_items)
  548. print(f"Exported {n} session{'' if n == 1 else 's'} ({message_count} message{'' if message_count == 1 else 's'}) "
  549. f"to {exported_items[0][1] if n == 1 else output_dir}")
  550. if not args.delete_after_verified:
  551. return
  552. # verify_export_file proves file == dict; store == dict is decided inside delete_session's transaction
  553. # (expected_display_messages), where no writer can slip between the check and the delete.
  554. expected_messages = {}
  555. for data, exported_path, snapshots in exported_items:
  556. ok, reason = verify_export_file(exported_path, data)
  557. if not ok:
  558. print(f"Export verification failed; not deleting session '{data.get('id')}': {reason}")
  559. return 1
  560. expected_messages.update(snapshots)
  561. try:
  562. if not db.delete_session(
  563. resolved_session_id, sessions_dir=_sessions_dir(), expected_delete_ids=delete_target_ids,
  564. expected_display_messages=expected_messages, exclude_active_write_guards=True,
  565. ):
  566. print(f"Exported, but session '{resolved_session_id}' was not deleted because its history or delegate set "
  567. "changed after export.")
  568. return 1
  569. except SessionActiveWriteGuardError as exc:
  570. print(f"Exported, but not deleted: {exc}")
  571. return 1
  572. delegates = len(delete_target_ids) - 1
  573. delegate_suffix = f" and {delegates} delegate session{'' if delegates == 1 else 's'}" if delegates else ""
  574. print(f"Deleted exported session '{resolved_session_id}'{delegate_suffix}.")
  575. # -- delete / prune / archive -------------------------------------------------
  576. def _cmd_delete(db, args):
  577. resolved_session_id = db.resolve_session_id(args.session_id)
  578. if not resolved_session_id:
  579. return _not_found(args.session_id)
  580. # The delete is honored (explicit id), but a pin is a "keep" flag: say so instead of silently destroying it.
  581. _pinned_note = " (this session is PINNED)" if (db.get_session(resolved_session_id) or {}).get("pinned") else ""
  582. if not args.yes:
  583. refused = _confirm_or_exit_code(f"Delete session '{resolved_session_id}'{_pinned_note} and all its messages? [y/N] ")
  584. if refused is not None:
  585. return refused
  586. elif _pinned_note:
  587. print(f"Warning: deleting a pinned session '{resolved_session_id}'.")
  588. from hermes_state_runtime import RuntimeStoreError
  589. try:
  590. if not db.delete_session(resolved_session_id, sessions_dir=_sessions_dir(), exclude_active_write_guards=True):
  591. return _not_found(args.session_id)
  592. except SessionActiveWriteGuardError as exc:
  593. print(f"Cannot delete active session: {exc}")
  594. return 1
  595. except RuntimeStoreError as exc:
  596. # The ledger refuses to delete a session with accepted, unfinished turns; say what to do.
  597. if exc.reason == 'unknown_execution':
  598. print(f"Cannot delete session '{resolved_session_id}': a turn was lost across a gateway restart. "
  599. f"Acknowledge it first with: hermes sessions discard {resolved_session_id}")
  600. elif exc.reason == 'session_busy':
  601. print(f"Cannot delete session '{resolved_session_id}': it has a queued or running turn. "
  602. "Wait for it to finish (or stop it), then retry.")
  603. else:
  604. print(f"Cannot delete session '{resolved_session_id}': {exc.reason}")
  605. return 1
  606. print(f"Deleted session '{resolved_session_id}'.")
  607. #: Age floor for `prune --never-active`; generous: a young never-active row may be a chat nobody replied to yet.
  608. _NEVER_ACTIVE_DEFAULT_DAYS = 30.0
  609. def _prune_never_active_keyed(db, args):
  610. """`prune --never-active`: drop keyed gateway rows opened and never used (mostly escaped test
  611. fixtures). Separate from the shared prune/archive selector, which is pinned to `ended_at IS NOT
  612. NULL` — never-closed rows sit outside it by construction.
  613. The population is dominated by escaped test fixtures (#82770), which the hermetic-isolation guard can
  614. only stop from being *created* — rows already written to a developer's state.db need a sweep to leave.
  615. """
  616. from hermes_cli.session_filters import format_epoch, parse_duration_seconds
  617. older_than = getattr(args, "older_than", None)
  618. days = _NEVER_ACTIVE_DEFAULT_DAYS
  619. if older_than is not None:
  620. seconds = parse_duration_seconds(str(older_than))
  621. if seconds is None:
  622. print(f"Error: --older-than '{older_than}' is not a duration. "
  623. "Use a bare number of days or a form like '2d' / '1w'.")
  624. return 1
  625. days = seconds / 86400.0
  626. candidates = db.list_never_active_keyed_sessions(older_than_days=days)
  627. if not candidates:
  628. print(f"No never-active keyed sessions older than {days:g} day(s).")
  629. return
  630. shown = candidates if args.dry_run else candidates[:15]
  631. print(f"{len(candidates)} never-active keyed session(s) older than {days:g} day(s) "
  632. "— no messages, tokens, tool calls or title:")
  633. for s in shown:
  634. print(f" {s['id']} {format_epoch(s.get('started_at')):<17} {(s.get('source') or '-'):<10} "
  635. f"{s.get('session_key') or '-'}")
  636. if len(candidates) > len(shown):
  637. print_truncated(len(candidates) - len(shown))
  638. if args.dry_run:
  639. print("Dry run — nothing deleted.")
  640. return
  641. if not args.yes and (refused := _confirm_or_exit_code(f"Delete {len(candidates)} session(s)? [y/N] ",
  642. declined="Aborted.")) is not None:
  643. return refused
  644. owner = getattr(args, "owner_endpoint", None)
  645. if owner is not None:
  646. from hermes_cli.gateway_client import GatewayClientError
  647. from hermes_cli.sessions_owner import owner_prune, report_owner_failure
  648. try:
  649. result = owner_prune(owner, never_active_days=days)
  650. except (GatewayClientError, OSError, TimeoutError) as exc:
  651. return report_owner_failure(exc)
  652. deleted, routing_deleted, skipped = result["deleted"], result["routing_deleted"], result["skipped"]
  653. else:
  654. deleted, routing_deleted, skipped = db.prune_never_active_keyed_sessions(
  655. older_than_days=days, sessions_dir=_sessions_dir()
  656. )
  657. print(f"Deleted {deleted} never-active session(s) and {routing_deleted} stale routing entr(ies).")
  658. if skipped:
  659. print(f"Skipped {skipped} session(s) with a live turn or compression lock.")
  660. def _note_pinned_skipped(db, filters, action):
  661. """Tell the user how many pinned rows bulk prune/archive spared (pin = durable keep; only
  662. `prune --include-pinned` opts in, archive always spares them)."""
  663. # Count matching pinned rows only: neither the unpinned ancestors a pinned tip spares nor the
  664. # unpinned continuations a pinned segment protects carry the pin.
  665. skipped = int(db.count_prune_matches(**filters, pinned_only=True))
  666. if not skipped:
  667. return
  668. suffix = "" if skipped == 1 else "s"
  669. if action == "prune":
  670. verb = "deleted"
  671. optin = "Pass --include-pinned to delete them anyway, or unpin first with `hermes sessions unpin <id>`."
  672. else:
  673. verb, optin = "archived", "Unpin first with `hermes sessions unpin <id>` to include them."
  674. print(f"Note: {skipped} pinned session{suffix} also match these filters but will NOT be {verb} "
  675. f"(pin is a keep flag). {optin}")
  676. def _cmd_prune_or_archive(db, args, action):
  677. prune = action == "prune"
  678. if prune and getattr(args, "never_active", False):
  679. return _prune_never_active_keyed(db, args)
  680. from hermes_cli.session_filters import build_prune_filters, describe_filters, format_epoch
  681. # Bare `prune` keeps the historical "older than 90 days" default. ANY filter — including --source —
  682. # suppresses the implicit cutoff (`prune --source cron` matches ALL cron sessions); the preview +
  683. # confirmation below is the safety net.
  684. if prune and not _any_filter_args(args):
  685. args.older_than = "90"
  686. try:
  687. filters = build_prune_filters(args)
  688. except ValueError as e:
  689. print(f"Error: {e}")
  690. return 1
  691. if not prune and not any(v for k, v in filters.items() if k != "older_than_days"):
  692. print("Refusing to archive every ended session: pass at least one "
  693. "filter (e.g. --newer-than 5h, --source cli, --title codex).")
  694. return 1
  695. # Prune skips archived rows unless --include-archived; archive only targets not-yet-archived rows.
  696. filters["archived"] = None if prune and getattr(args, "include_archived", False) else False
  697. filters["include_pinned"] = getattr(args, "include_pinned", False)
  698. # Archive flips a compression lineage as a unit, matched through its tip (an old ancestor alone
  699. # never qualifies); the preview must show the same rows the archive will touch.
  700. filters["lineage_tips_only"] = not prune
  701. # Desktop sessions never set ended_at, so the shared ended-only selector hides them from archive
  702. # entirely (#139597); --include-open opts in for archive only — pruning is not reversible.
  703. include_open = not prune and getattr(args, "include_open", False)
  704. if include_open:
  705. filters["include_open"] = True
  706. if not filters["include_pinned"]:
  707. _note_pinned_skipped(db, filters, action)
  708. # Prune deletes a compression lineage only as a unit; the preview must list the rows it deletes.
  709. candidates = db.list_prune_candidates(**filters, whole_lineages=prune)
  710. # Archive expands each matched tip to its compression lineage, so a direct-open count would
  711. # misdescribe its effect.
  712. skipped_open = db.count_open_prune_matches(**filters) if (prune or not include_open) else 0
  713. if skipped_open and prune:
  714. print(f"Note: {skipped_open} open session{'' if skipped_open == 1 else 's'} also match these filters but "
  715. "will be skipped because prune only deletes ended sessions. Use `hermes sessions delete <id>` "
  716. "to remove one explicitly.")
  717. elif skipped_open:
  718. print(f"Note: {skipped_open} matching session{'' if skipped_open == 1 else 's'} still open — "
  719. "skipped because archive defaults to ended sessions. Use --include-open to archive "
  720. "them too.")
  721. if not candidates:
  722. print(f"No sessions match ({describe_filters(filters)}).")
  723. return
  724. # Candidates are oldest-activity-first; show the span so a long-lived but recently used
  725. # conversation cannot look old merely by creation date.
  726. _span = (
  727. f"oldest activity {format_epoch(candidates[0].get('last_active'))}, "
  728. f"newest activity {format_epoch(candidates[-1].get('last_active'))}"
  729. )
  730. if args.dry_run or not args.yes:
  731. shown = candidates if args.dry_run else candidates[:15]
  732. print(f"{len(candidates)} session(s) match ({describe_filters(filters)}; {_span}):")
  733. for s in shown:
  734. model = (s.get("model") or "-").split("/")[-1][:24]
  735. print(f" {s['id']} {format_epoch(s.get('last_active')):<17} {s['source']:<10} {model:<24} "
  736. f"{s['message_count']:>4} msgs {(s.get('title') or '')[:36]}")
  737. if len(candidates) > len(shown):
  738. print_truncated(len(candidates) - len(shown))
  739. if args.dry_run:
  740. print(f"Dry run — nothing {'deleted' if prune else 'archived'}.")
  741. return
  742. verb = "Delete" if prune else "Archive"
  743. if not args.yes and (refused := _confirm_or_exit_code(
  744. f"{verb} these {len(candidates)} session(s) ({_span})? [y/N] ")) is not None:
  745. return refused
  746. if prune and getattr(args, "owner_endpoint", None) is not None:
  747. # The live gateway owns the store: it deletes, through the housekeeping retirement path.
  748. from hermes_cli.gateway_client import GatewayClientError
  749. from hermes_cli.sessions_owner import owner_prune, report_owner_failure
  750. try:
  751. print(f"Pruned {owner_prune(args.owner_endpoint, filters=filters)['deleted']} session(s).")
  752. except (GatewayClientError, OSError, TimeoutError) as exc:
  753. return report_owner_failure(exc)
  754. elif prune:
  755. print(f"Pruned {db.prune_sessions(sessions_dir=_sessions_dir(), exclude_active_write_guards=True, **filters)} session(s).")
  756. else:
  757. print(f"Archived {db.archive_sessions(**filters)} session(s). They're hidden from listings "
  758. "but fully recoverable (nothing was deleted).")
  759. # -- titles / pins -----------------------------------------------------------
  760. def _cmd_rename(db, args):
  761. resolved_session_id = db.resolve_session_id(args.session_id)
  762. if not resolved_session_id:
  763. return _not_found(args.session_id)
  764. title = " ".join(args.title)
  765. # Empty titles render as "—" and newlines corrupt the `list` table; length is validated in set_session_title.
  766. if not title.strip():
  767. print("Error: title cannot be empty or whitespace-only.")
  768. return 1
  769. if "\n" in title or "\r" in title:
  770. print("Error: title cannot contain newlines.")
  771. return 1
  772. try:
  773. if not db.set_session_title(resolved_session_id, title):
  774. return _not_found(args.session_id)
  775. except ValueError as e:
  776. print(f"Error: {e}")
  777. return 1
  778. print(f"Session '{resolved_session_id}' renamed to: {title}")
  779. def _cmd_pin(db, args, pinning):
  780. """Durable "keep" flag (exempt from sessions.auto_archive, always listed); every surface shares the store."""
  781. failures = 0
  782. # Pinned sessions are exempt from the sessions.auto_archive stale sweep and always surface in listings;
  783. # until now only the Desktop sidebar could write the flag. Inspired by Perplexity Computer's
  784. # conversational session management (pin/archive from any surface): pin state is operational
  785. # infrastructure, so every surface — GUI, TUI, CLI, scripts — needs read/write access to the same store.
  786. # See #52955.
  787. for raw_id in args.session_ids:
  788. resolved = db.resolve_session_id(raw_id)
  789. if resolved and db.set_session_pinned(resolved, pinning):
  790. title = db.get_session_title(resolved)
  791. print(f"{'Pinned' if pinning else 'Unpinned'} session '{resolved}'.{f' ({title})' if title else ''}")
  792. else:
  793. failures += _not_found(raw_id)
  794. return 1 if failures else None
  795. def _cmd_pinned(db, args):
  796. # limit=1 keeps the recency page minimal; include_pinned back-fills ALL pinned rows the page missed.
  797. rows = db.list_sessions_rich(limit=1, include_pinned=True, exclude_sources=_default_exclude(args))
  798. pinned_rows = [s for s in rows if s.get("pinned")]
  799. if getattr(args, "json", False):
  800. keys = ("title", "source", "last_active", "message_count")
  801. print(json.dumps([{"id": s["id"], **{k: s.get(k) for k in keys}} for s in pinned_rows], indent=2))
  802. return
  803. if not pinned_rows:
  804. print("No pinned sessions. Pin one with: hermes sessions pin <session_id>")
  805. return
  806. print(f"{'Title':<32} {'Last Active':<13} {'Src':<9} {'ID'}\n" + "─" * 100)
  807. for s in pinned_rows:
  808. title = (s.get("title") or s.get("preview", "") or "—")[:30]
  809. print(f"{title:<32} {_relative_time(s.get('last_active'), session_id=s['id']):<13} {(s.get('source') or '-'):<9} {s['id']}")
  810. def _cmd_retitle_skills(db, args):
  811. from agent.skill_commands import describe_skill_invocation
  812. from agent.title_generator import generate_title
  813. limit = max(1, int(getattr(args, "limit", 200) or 200))
  814. apply_changes = bool(getattr(args, "apply", False))
  815. candidates = db.list_skill_scaffolded_sessions(limit=limit)
  816. if not candidates:
  817. print("No sessions were titled from a /skill invocation.")
  818. return
  819. mode = "" if apply_changes else " (dry run — pass --apply to write)"
  820. print(f"{len(candidates)} session(s) opened with a /skill{mode}:")
  821. changed = 0
  822. for row in candidates:
  823. session_id = row["id"]
  824. typed = describe_skill_invocation(row["content"]) or ""
  825. new_title = generate_title(typed)
  826. if not new_title or new_title == row["title"]:
  827. continue
  828. if not new_title[0].isalnum():
  829. # Non-title: an auxiliary model occasionally answers the prompt instead of titling it
  830. # ('$ df -h /'). This is a REPAIR — never replace a serviceable title with that.
  831. print(f" {session_id}\n kept {row['title']!r} — got {new_title!r}")
  832. continue
  833. print(f" {session_id}\n {row['title']!r}\n → {new_title!r}")
  834. changed += 1
  835. if not apply_changes:
  836. continue
  837. try:
  838. db.set_session_title(session_id, new_title)
  839. except ValueError: # unique-title collision: dedupe like the live auto-titler (base #2, #3, ...)
  840. deduped = db.get_next_title_in_lineage(new_title)
  841. try:
  842. db.set_session_title(session_id, deduped)
  843. print(f" (renamed to {deduped!r} — title was taken)")
  844. except ValueError as e:
  845. print(f" skipped: {e}")
  846. changed -= 1
  847. if not changed:
  848. print(" every title already reflects the user's request.")
  849. elif apply_changes:
  850. print(f"✓ Re-titled {changed} session(s).")
  851. def _cmd_browse(db, args):
  852. limit = getattr(args, "limit", 500) or 500
  853. sessions = _surface_reader(db).list_sessions_rich(
  854. source=getattr(args, "source", None), exclude_sources=_default_exclude(args), limit=limit
  855. )
  856. if not sessions:
  857. db.close()
  858. print("No sessions found.")
  859. return
  860. try: # keep the DB open: the picker uses it for status tags and 'd' delete
  861. selected_id = _session_browse_picker(sessions, session_db=db)
  862. finally:
  863. db.close()
  864. if not selected_id:
  865. print("Cancelled.")
  866. return
  867. print(f"Resuming session: {selected_id}")
  868. from hermes_cli.relaunch import relaunch
  869. relaunch(["--resume", selected_id]) # won't return after execvp
  870. # -- storage maintenance -----------------------------------------------------
  871. def _print_size_change(db, before_mb, prefix=""):
  872. """Report before/after size, preferring SQLite's page accounting over stat(): in WAL mode a VACUUM's
  873. rewrite sits in the -wal file until a checkpoint (refused while a live gateway holds a read-mark),
  874. so the main file lags and stat() can even go negative."""
  875. logical_after = db.logical_size_bytes()
  876. after_mb = logical_after / (1024 * 1024) if logical_after is not None else _size_mb(db.db_path)
  877. delta = _size_delta_label(before_mb - after_mb)
  878. print(f"{prefix}Database size: {before_mb:.1f} MB -> {after_mb:.1f} MB ({delta})")
  879. def _cmd_optimize(db, args):
  880. before_mb = _size_mb(db.db_path)
  881. print("Optimizing session store (FTS merge + VACUUM)…")
  882. try:
  883. n = db.vacuum() # merges FTS5 segments then VACUUMs; returns indexes merged
  884. except Exception as e:
  885. print(f"Error: optimization failed: {e}")
  886. return 1
  887. print(f"Optimized {n} FTS index(es).")
  888. _print_size_change(db, before_mb)
  889. def _cmd_clean_markers(db, args):
  890. print(f"{'Dry run — scanning' if args.dry_run else 'Scanning'} for stale tool-call marker rows (#78148)…")
  891. report = db.purge_stale_tool_call_markers(dry_run=args.dry_run, backup=not args.no_backup)
  892. if report["rows_affected"] == 0:
  893. print("✓ No affected rows found — nothing to clean.")
  894. elif args.dry_run:
  895. print(f"Would clear {report['rows_affected']} row(s): ids {report['row_ids']}")
  896. else:
  897. if report["backup_path"]:
  898. print(f" backup: {report['backup_path']}")
  899. print(f"✓ Cleared {report['rows_affected']} row(s).")
  900. _BACKFILL_LABELS = {"backfill": "Rebuilding index", "backfill_cjk": "Building CJK index"}
  901. _COUNTED_PHASES = frozenset({*_BACKFILL_LABELS, "teardown"})
  902. def _optimize_progress_line(info) -> str:
  903. phase, pct = info.get("phase"), f"{info.get('percent', 0):3d}%"
  904. counts = f"({info.get('indexed', 0):,}/{info.get('total', 0):,}"
  905. paced = " — paced: another process is using the database" if info.get("paced") else ""
  906. if phase in _BACKFILL_LABELS:
  907. return f" {_BACKFILL_LABELS[phase]}: {pct} {counts} messages){paced}"
  908. if phase == "teardown":
  909. table = str(info.get("table", "")).removeprefix("fts_v22_trash_")
  910. return (f" Reclaiming old index: table {info.get('table_index', 0)}/{info.get('table_count', 0)} "
  911. f"({table}) {pct} {counts} rows){paced}")
  912. elapsed = int(info.get("elapsed", 0))
  913. return (f" Compacting database (VACUUM): {elapsed // 60}m {elapsed % 60:02d}s elapsed, "
  914. f"{info.get('size_bytes', 0) / 2**20:,.1f} MB → ~{info.get('estimated_bytes', 0) / 2**20:,.1f} MB")
  915. class _OptimizeProgress:
  916. """``optimize_fts_storage`` progress: one self-overwriting line per phase (and per old-index
  917. table), space-padded over the previous text (``ESC[K`` leaks under prompt_toolkit)."""
  918. def __init__(self):
  919. self._key, self._last, self._line = None, None, ""
  920. def __call__(self, info) -> None:
  921. phase = info.get("phase")
  922. key = (phase, info.get("table"))
  923. if key != self._key:
  924. # The phase or table moved on, so the previous one ran to completion.
  925. self.close(completed=True)
  926. self._key = key
  927. if phase == "done" or (phase in _COUNTED_PHASES and not info.get("total") and not info.get("table")):
  928. return
  929. self._last = info
  930. self._draw(_optimize_progress_line(info))
  931. def _draw(self, line: str) -> None:
  932. if line == self._line: # a table's final chunk, its DROP and the switch all report 100%
  933. return
  934. print(f"\r{line}{' ' * max(0, len(self._line) - len(line))}", end="", flush=True)
  935. self._line = line
  936. def close(self, completed: bool = False) -> None:
  937. last = self._last
  938. if completed and last and last.get("phase") in _COUNTED_PHASES:
  939. self._draw(_optimize_progress_line({**last, "percent": 100, "indexed": last.get("total", 0)}))
  940. if self._line:
  941. print(flush=True)
  942. self._last, self._line = None, ""
  943. def _cmd_optimize_storage(db, args):
  944. db_path = db.db_path
  945. if not db.fts_optimize_available():
  946. print("Search index is already on the compact layout — nothing to do.")
  947. return
  948. before_bytes = os.path.getsize(db_path) if db_path.exists() else 0
  949. before_mb = before_bytes / (1024 * 1024)
  950. # Disk preflight: the new index is built before the old is torn down, and VACUUM needs a full
  951. # second copy — require headroom ≈ current file size.
  952. do_vacuum = not getattr(args, "no_vacuum", False)
  953. try:
  954. free_bytes = shutil.disk_usage(db_path.parent).free
  955. except Exception:
  956. free_bytes = None
  957. need_bytes = before_bytes if do_vacuum else int(before_bytes * 0.3)
  958. print(f"Search-index optimization for {db_path}\n Current database size: {before_mb:.1f} MB")
  959. if free_bytes is not None:
  960. print(f" Free disk: {free_bytes / (1024*1024):.0f} MB "
  961. f"(need ~{need_bytes / (1024*1024):.0f} MB to complete{' incl. VACUUM' if do_vacuum else ''})")
  962. if free_bytes < need_bytes:
  963. print("\n⚠ Not enough free disk to complete safely. Free up space, or run with --no-vacuum "
  964. "(rebuilds the index but doesn't reclaim space until a later VACUUM).")
  965. return 1
  966. if before_mb > 500:
  967. print(" This may take a while on a large database. It runs in the foreground with progress below; "
  968. "safe to Ctrl-C and re-run (it resumes).")
  969. if not getattr(args, "yes", False) and (refused := _confirm_or_exit_code("Proceed? [y/N] ")) is not None:
  970. return refused
  971. # optimize_fts_storage re-scans for holders itself (--force past one, or a writer that opens the
  972. # store mid-run) and paces while one is there; the progress line says so.
  973. progress = _OptimizeProgress()
  974. print("Optimizing search-index storage…")
  975. try:
  976. result = db.optimize_fts_storage(progress_cb=progress, vacuum=do_vacuum)
  977. except KeyboardInterrupt:
  978. progress.close()
  979. print("Interrupted — no data was lost; re-run to resume.")
  980. return 130
  981. except Exception as e:
  982. progress.close()
  983. print(f"Error: optimization failed: {e}\nNo data was lost. Re-run to resume.")
  984. return 1
  985. progress.close()
  986. if not result.get("ok"):
  987. print(f"Could not optimize: {result.get('reason', 'unknown')}")
  988. return 1
  989. print("✓ Search index optimized.")
  990. _print_size_change(db, before_mb, prefix=" ")
  991. if result.get("vacuum_skipped") == "in_use":
  992. print(" (VACUUM skipped: another process is using the database. Re-run `hermes sessions optimize` "
  993. "with it closed to reclaim freed space.)")
  994. elif result.get("vacuumed") is False:
  995. print(" (VACUUM was skipped or failed — run `hermes sessions optimize` later to reclaim freed space.)")
  996. def _cmd_repair_routing(db, args):
  997. records = db.find_orphaned_gateway_sessions(max_gap_s=getattr(args, "max_gap_seconds", None))
  998. adoptable = [r for r in records if r["adoptable"]]
  999. for record in records:
  1000. print(f"{record['orphan_id']} ({record['source']}, {record['message_count']} messages)")
  1001. if record["adoptable"]:
  1002. print(f" → adopt into {record['session_key']} (from {record['donor_id']}, "
  1003. f"evidence: {record['evidence']})")
  1004. else:
  1005. print(f" ✗ not repairable — {record['reason']}")
  1006. if not records:
  1007. print("✓ No gateway sessions are missing their routing identity.")
  1008. return
  1009. if not adoptable:
  1010. print(f"\n{len(records)} orphaned session(s) found, none unambiguously repairable. Nothing to do.")
  1011. return
  1012. if not getattr(args, "apply", False):
  1013. print(f"\n{len(adoptable)} of {len(records)} orphaned session(s) can be repaired. "
  1014. "Re-run with --apply to perform them.")
  1015. return
  1016. print("\nStop the gateway before applying — a running gateway still holds the old routing mapping in memory.")
  1017. refused = _confirm_or_exit_code(f"Adopt {len(adoptable)} orphaned session(s)? [y/N] ",
  1018. declined="Aborted — nothing was changed.", unattended=None)
  1019. if refused is not None:
  1020. return refused
  1021. repaired = 0
  1022. for record in adoptable:
  1023. if db.adopt_orphaned_gateway_session(record["orphan_id"], record["donor_id"]):
  1024. repaired += 1
  1025. print(f"✓ {record['orphan_id']} now owns {record['session_key']}")
  1026. else:
  1027. print(f"✗ {record['orphan_id']} was not adopted (the row changed since it was reported)")
  1028. print(f"\nRepaired {repaired} of {len(adoptable)} session(s).")
  1029. def _repair_prompts_pin_names(row) -> list[str] | None:
  1030. """Resolve legacy name-list and current versioned tools[] pins to tool names.
  1031. Any malformed or unknown shape is unverifiable and therefore never eligible for automatic
  1032. repair. Current pins store full tool definitions in a versioned object; older rows may contain
  1033. a JSON list of names directly.
  1034. """
  1035. try:
  1036. pin = json.loads(row.get("tool_names") or "null")
  1037. except (TypeError, ValueError):
  1038. return None
  1039. tools = pin.get("tools") if isinstance(pin, dict) else pin
  1040. if not isinstance(tools, list):
  1041. return None
  1042. names: list[str] = []
  1043. for item in tools:
  1044. if isinstance(item, str):
  1045. name = item
  1046. elif isinstance(item, dict):
  1047. function = item.get("function")
  1048. name = function.get("name") if isinstance(function, dict) else None
  1049. else:
  1050. return None
  1051. if not isinstance(name, str) or not name:
  1052. return None
  1053. names.append(name)
  1054. return names
  1055. def _repair_prompts_lacks_skill_safety(row) -> bool:
  1056. # Only the skill_manage guidance is a reliable marker: <available_skills> is legitimately absent when no
  1057. # skills are installed, but the guidance is emitted whenever skill_manage is. A prompt stored before the
  1058. # Skill Safety Rule moved to compaction carries that heading, under whichever opening line it was built with.
  1059. from agent.context_compressor_tail import SKILL_SAFETY_HEADING
  1060. from agent.prompt_builder import SKILLS_GUIDANCE
  1061. prompt = (row.get("system_prompt") or "").strip()
  1062. return bool(prompt and SKILLS_GUIDANCE not in prompt and SKILL_SAFETY_HEADING not in prompt)
  1063. def _cmd_repair_prompts(db, args):
  1064. """Report (or clear) stored system prompts degraded to a reduced-toolset build (#122822).
  1065. Automatic repair requires positive tools[] evidence. Rows with missing/malformed pins are
  1066. reported as unverifiable and never changed by a scan. An explicit session_id remains the
  1067. operator escape hatch and clears that row regardless of detector evidence.
  1068. """
  1069. findings = []
  1070. unverifiable = []
  1071. target = getattr(args, "session_id", None)
  1072. if target:
  1073. session_id = db.resolve_session_id(target)
  1074. if not session_id:
  1075. print(f"No session matches {target!r}.")
  1076. return 1
  1077. row = db.get_session(session_id)
  1078. if row and row.get("system_prompt"):
  1079. findings.append({
  1080. "id": row["id"], "reason": "targeted clear", "prompt_chars": len(row["system_prompt"]),
  1081. })
  1082. else:
  1083. seen = set()
  1084. offset = 0
  1085. while True:
  1086. batch = db.list_sessions_rich(
  1087. limit=200, offset=offset, include_children=True,
  1088. include_archived=True, include_hidden=True, compact_rows=True,
  1089. )
  1090. if not batch:
  1091. break
  1092. offset += len(batch)
  1093. for summary in batch:
  1094. # OFFSET paging can re-serve a row when sessions are inserted mid-scan.
  1095. if summary["id"] in seen:
  1096. continue
  1097. seen.add(summary["id"])
  1098. row = db.get_session(summary["id"])
  1099. if not row or not _repair_prompts_lacks_skill_safety(row):
  1100. continue
  1101. pin = _repair_prompts_pin_names(row)
  1102. entry = {"id": row["id"], "prompt_chars": len(row["system_prompt"])}
  1103. if "skill_manage" in (pin or ()):
  1104. findings.append({
  1105. **entry,
  1106. "reason": "skill_manage guidance missing while the tools[] pin carries skill_manage",
  1107. })
  1108. elif pin is None:
  1109. unverifiable.append({
  1110. **entry,
  1111. "reason": "skills markers missing but the tools[] pin is unavailable or unreadable",
  1112. })
  1113. elif set(pin) == {"memory"}:
  1114. # Not proof: toolsets=[memory] is also a legitimate user config whose healthy
  1115. # prompt has no skills markers, so auto-clearing it would repeat every run.
  1116. unverifiable.append({
  1117. **entry,
  1118. "reason": "memory-only tools[] pin may be a user toolset; clear explicitly by SESSION_ID",
  1119. })
  1120. apply = bool(getattr(args, "apply", False))
  1121. as_json = bool(getattr(args, "json", False))
  1122. def _payload(cleared):
  1123. return {
  1124. "findings": findings,
  1125. "unverifiable": unverifiable,
  1126. "apply": apply,
  1127. "cleared": cleared,
  1128. }
  1129. if not findings:
  1130. if as_json:
  1131. print(json.dumps(_payload([]), indent=2))
  1132. elif target:
  1133. print(f"{session_id} already has no stored prompt; nothing to clear.")
  1134. else:
  1135. print("No degraded stored system prompts found.")
  1136. if unverifiable:
  1137. print(f"{len(unverifiable)} row(s) lacked enough tools[] evidence and were left unchanged.")
  1138. return 0
  1139. if not as_json:
  1140. for finding in findings:
  1141. print(f" {finding['id']} ({finding['prompt_chars']} chars) - {finding['reason']}")
  1142. if unverifiable:
  1143. print(f"\nSkipped {len(unverifiable)} unverifiable row(s) without enough tools[] evidence.")
  1144. if not apply:
  1145. if as_json:
  1146. print(json.dumps(_payload([]), indent=2))
  1147. else:
  1148. print(f"\n{len(findings)} stored prompt(s) can be repaired. Re-run with --apply to clear them; "
  1149. "the next turn rebuilds a healthy prompt (one prefix-cache break per session).")
  1150. return 0
  1151. # JSON mode is the non-interactive automation surface; --apply is the explicit mutation opt-in.
  1152. if not as_json and (refused := _confirm_or_exit_code(
  1153. f"Clear {len(findings)} stored prompt(s)? [y/N] ", declined="Aborted - nothing was changed.",
  1154. unattended="--json")) is not None:
  1155. return refused
  1156. cleared = []
  1157. for finding in findings:
  1158. db.update_system_prompt(finding["id"], None)
  1159. cleared.append(finding["id"])
  1160. if as_json:
  1161. print(json.dumps(_payload(cleared), indent=2))
  1162. else:
  1163. print(f"\nCleared {len(cleared)} stored prompt(s); the next turn for each rebuilds and persists "
  1164. "a healthy prompt.")
  1165. print("One 'Stored system prompt ... is null' warning per repaired session is expected on that rebuild.")
  1166. return 0
  1167. def _cmd_refresh_prompts(db, args):
  1168. """Ask continuing sessions to rebuild their stored system prompt once, on their next turn.
  1169. For operators who update SOUL.md, skills or context files under a running profile: the
  1170. request is a refresh epoch in this profile's state.db, so it works with the gateway running
  1171. and survives a restart. History and session ids are untouched.
  1172. """
  1173. target = getattr(args, "session", None)
  1174. session_id = None
  1175. if target:
  1176. session_id = db.resolve_session_id(target)
  1177. if not session_id:
  1178. print(f"No session matches {target!r}.")
  1179. return 1
  1180. # A compressed conversation continues on its tip; a request keyed on the ended root never fires.
  1181. session_id = db.get_compression_tip(session_id) or session_id
  1182. row = db.get_session(session_id) or {}
  1183. count = 1 if row.get("system_prompt") else 0
  1184. else:
  1185. count = db.count_sessions_with_stored_prompt()
  1186. epoch = db.request_prompt_refresh(session_id)
  1187. if getattr(args, "json", False):
  1188. print(json.dumps({"epoch": epoch, "session_id": session_id, "sessions": count}))
  1189. return 0
  1190. scope = session_id or "every session in this profile"
  1191. print(f"Requested a system prompt refresh for {scope} ({count} session(s) with a stored prompt).")
  1192. print("Each rebuilds its prompt from the current SOUL.md, skills and context files on its next turn "
  1193. "(one prompt-cache miss per session); conversation history is kept.")
  1194. return 0
  1195. def _cmd_stats(db, args):
  1196. reader = _surface_reader(db)
  1197. print(f"Total sessions: {db.session_count()}\nTotal messages: {db.message_count()}")
  1198. for src in ("cli", "telegram", "discord", "whatsapp", "slack"):
  1199. if (c := reader.session_count(source=src)) > 0:
  1200. print(f" {src}: {c} sessions")
  1201. if db.db_path.exists():
  1202. print(f"Database size: {_size_mb(db.db_path):.1f} MB")
  1203. # -- dispatch -----------------------------------------------------------------
  1204. def _cmd_repair_profiles(args):
  1205. from hermes_cli.sessions_cmd_repair_profiles import cmd_repair_profiles
  1206. return cmd_repair_profiles(args)
  1207. def _cmd_set_journal_mode(args):
  1208. from hermes_cli.sessions_cmd_journal_mode import cmd_set_journal_mode
  1209. return cmd_set_journal_mode(args)
  1210. def _cmd_discard(args):
  1211. from hermes_cli.sessions_discard import cmd_discard
  1212. return cmd_discard(args)
  1213. def _cmd_adopt(args):
  1214. from hermes_cli.sessions_adopt import cmd_adopt
  1215. return cmd_adopt(args)
  1216. _PRE_DB_HANDLERS = {
  1217. "repair": _cmd_repair, "recover": _cmd_recover, "import": _cmd_import,
  1218. "repair-profiles": _cmd_repair_profiles, # opens every profile's store itself
  1219. "set-journal-mode": _cmd_set_journal_mode, # offline: must not open the store it converts
  1220. "discard": _cmd_discard, # a gateway control (prompt.resolve_unknown), never a direct store write
  1221. "adopt": _cmd_adopt, # native resumes on the owner; reads its own store read-only
  1222. }
  1223. _OBSERVATIONAL_DB_ACTIONS = frozenset({"list", "stats", "pinned"})
  1224. _DB_HANDLERS = {
  1225. "list": _cmd_list, "export": _cmd_export, "delete": _cmd_delete, "rename": _cmd_rename, "pinned": _cmd_pinned,
  1226. "prune": partial(_cmd_prune_or_archive, action="prune"), "pin": partial(_cmd_pin, pinning=True),
  1227. "archive": partial(_cmd_prune_or_archive, action="archive"), "unpin": partial(_cmd_pin, pinning=False),
  1228. "retitle-skills": _cmd_retitle_skills, "browse": _cmd_browse, "optimize": _cmd_optimize,
  1229. "clean-markers": _cmd_clean_markers, "optimize-storage": _cmd_optimize_storage,
  1230. "repair-routing": _cmd_repair_routing, "repair-prompts": _cmd_repair_prompts, "stats": _cmd_stats,
  1231. "refresh-prompts": _cmd_refresh_prompts,
  1232. }
  1233. def _print_empty_store(action: str, args) -> None:
  1234. """A profile that never created state.db: report empty instead of opening a writer that creates it."""
  1235. if action == "stats":
  1236. print("Total sessions: 0\nTotal messages: 0")
  1237. elif action == "pinned":
  1238. print("[]" if getattr(args, "json", False) else "No pinned sessions. Pin one with: hermes sessions pin <session_id>")
  1239. else:
  1240. print("No sessions found.")
  1241. # VACUUM, the FTS-layout rebuild and bulk deletes rewrite the store; underneath a live gateway/Desktop/cron
  1242. # writer that is the second-writer class behind the retired-WAL refusal (#110054). `--force` is the override.
  1243. _HELD_STORE_ACTIONS = frozenset({"optimize", "optimize-storage", "prune"})
  1244. def cmd_sessions(args, sessions_parser=None):
  1245. action = args.sessions_action
  1246. pre = _PRE_DB_HANDLERS.get(action)
  1247. if pre is not None:
  1248. return pre(args)
  1249. from hermes_state import SessionDB
  1250. from hermes_constants import get_hermes_home
  1251. # Verified deletion is an explicit mutation, not a read-only export.
  1252. deleting_export = (
  1253. action == "export" and getattr(args, "delete_after_verified", False)
  1254. and getattr(args, "yes", False) and getattr(args, "session_id", None)
  1255. and getattr(args, "format", None) in ("md", "qmd")
  1256. )
  1257. observational = action in _OBSERVATIONAL_DB_ACTIONS or (action == "export" and not deleting_export)
  1258. if action == "prune":
  1259. # The always-on gateway owns the store: this process only reads the preview, the owner
  1260. # deletes. No gateway: the local prune below, behind the holder scan, as before.
  1261. from hermes_cli.sessions_owner import live_owner
  1262. args.owner_endpoint = live_owner()
  1263. observational = args.owner_endpoint is not None
  1264. # A served-profile process has no single default home: pass the store path explicitly.
  1265. path = get_hermes_home() / "state.db"
  1266. try:
  1267. db = SessionDB(db_path=path, read_only=observational)
  1268. except Exception as e:
  1269. # mode=ro cannot create the store; a reader on a fresh profile reports empty rather than failing.
  1270. if observational and not path.exists():
  1271. return _print_empty_store(action, args)
  1272. print("Could not open your session history database. "
  1273. "Run: hermes sessions repair to fix it (a backup is made first).")
  1274. print(f"Details: {e}")
  1275. return 1
  1276. try:
  1277. handler = _DB_HANDLERS.get(action)
  1278. if handler is None:
  1279. sessions_parser.print_help()
  1280. return
  1281. if (action in _HELD_STORE_ACTIONS and not getattr(args, "dry_run", False) and not getattr(args, "force", False)
  1282. and getattr(args, "owner_endpoint", None) is None):
  1283. from hermes_state_holders import held_store_refusal
  1284. # Same path the SessionDB above opened, so the scan never depends on the db object.
  1285. refusal = held_store_refusal(path, command=action)
  1286. if refusal:
  1287. print(refusal)
  1288. return 1
  1289. try:
  1290. return handler(db, args)
  1291. except sqlite3.OperationalError as e:
  1292. from hermes_state_repair import _schema_not_built
  1293. if not observational or not _schema_not_built(e):
  1294. raise
  1295. # A read-only opener skips schema migration, so a store from an older release can lack a column.
  1296. print(f"Error: session database needs migration — run any writing hermes command first ({e})")
  1297. return 1
  1298. finally:
  1299. db.close()