profiles.py 56 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164
  1. """Profiles dashboard routes.
  2. Two routers because route order matters: ``sessions_router`` (/api/profiles/sessions*,
  3. projects/tree, pull-requests) was registered long before the generic
  4. ``/api/profiles/{name}`` routes on ``router``; the original global registration order is
  5. preserved rather than relying on Starlette's literal-before-param matching.
  6. Shared helpers are reached via the late-binding seam in :mod:`hermes_cli.web_deps`
  7. so a test's ``monkeypatch.setattr(<owning module>, "_helper", ...)`` keeps working.
  8. """
  9. import asyncio
  10. import contextlib
  11. import copy
  12. import functools
  13. from hermes_cli.web_read_coalescing import coalesced_read
  14. import inspect
  15. import json
  16. import logging
  17. import re
  18. import subprocess
  19. import sys
  20. import threading
  21. import time
  22. from collections import OrderedDict
  23. from pathlib import Path
  24. from typing import Any, Callable, Dict, List, Optional, Tuple
  25. from fastapi import APIRouter, HTTPException, Query
  26. from hermes_cli.session_listing import subagent_listing_scope
  27. from hermes_cli.web_deps import late
  28. from hermes_cli.config import get_process_hermes_home
  29. from hermes_cli.profiles import ProfileIdentitySettlementPending
  30. from hermes_cli.web_server_config import (
  31. _apply_main_model_assignment, _normalize_main_model_assignment, _validated_main_model_selection,
  32. )
  33. from hermes_cli.web_server_gateway import _strip_session_list_rows
  34. from hermes_cli.web_routers._common import _CONFIG_MUTATION_LOCK
  35. from hermes_cli.web_server_profiles import (
  36. _fallback_profile_dicts, _hub_action_name, _write_profile_mcp_servers,
  37. )
  38. from hermes_cli.web_server_sessions import _open_session_db_at_path
  39. from hermes_state_health import STORAGE_CORRUPT, note_storage_error, storage_state
  40. from starlette.concurrency import run_in_threadpool
  41. from hermes_cli.web_models import (
  42. ProfileCreate, ProfileActiveUpdate, ProfileExport, ProfileImport, ProfileRename,
  43. ProfileSoulUpdate, ProfileDescriptionUpdate, ProfileModelUpdate, ProfileDescribeAuto,
  44. SessionPrScanBody)
  45. from hermes_cli.web_server_profiles import _config_profile_scope, _hermes_home_scope
  46. # Same logger the handlers used before extraction (identical logger object).
  47. _log = logging.getLogger("hermes_cli.web_server")
  48. # A per-profile read failure is not an empty session list. The sidebar slice for
  49. # that profile is a failed load (``failed`` + ``retry``) so Desktop can offer Retry
  50. # instead of "No sessions yet". A successful read of zero rows still returns
  51. # ``sessions: []``. Warn once per (profile, message) per process so a persistent
  52. # failure is loud in errors.log without turning every sidebar poll into spam.
  53. _profile_read_warned: set = set()
  54. def _warn_profile_read_error(profile: str, exc: Exception) -> None:
  55. key = (profile, str(exc))
  56. if key in _profile_read_warned:
  57. return
  58. _profile_read_warned.add(key)
  59. _log.warning("profile session read failed for %r (reported only in the response "
  60. "errors array): %s", profile, exc)
  61. sessions_router = APIRouter()
  62. router = APIRouter()
  63. # Late-bound web_server helpers (resolved at call time; cycle-safe, monkeypatch-transparent).
  64. _cron_profile_home = late("_cron_profile_home", "hermes_cli.web_server_cron")
  65. _resolve_profile_dir = late("_resolve_profile_dir", "hermes_cli.web_server_profiles")
  66. _spawn_hermes_action = late("_spawn_hermes_action", "hermes_cli.web_server_gateway")
  67. # ---------------------------------------------------------------------------
  68. # Profile management endpoints (minimal — list/create/rename/delete + SOUL.md)
  69. # ---------------------------------------------------------------------------
  70. def _profile_to_dict(info) -> dict[str, Any]:
  71. attr = functools.partial(getattr, info)
  72. return {
  73. "name": attr("name", ""), "path": str(attr("path", "")),
  74. "is_default": bool(attr("is_default", False)),
  75. "model": attr("model", None), "provider": attr("provider", None),
  76. "has_env": bool(attr("has_env", False)),
  77. "skill_count": int(attr("skill_count", 0) or 0),
  78. "gateway_running": bool(attr("gateway_running", False)),
  79. "description": attr("description", "") or "",
  80. "description_auto": bool(attr("description_auto", False)),
  81. "display_name": attr("display_name", "") or "",
  82. "bot_title": attr("bot_title", "") or "",
  83. "distribution_name": attr("distribution_name", None),
  84. "distribution_version": attr("distribution_version", None),
  85. "distribution_source": attr("distribution_source", None),
  86. "has_alias": attr("alias_path", None) is not None}
  87. def _profile_setup_command(name: str) -> str:
  88. """Return the shell command used to configure a profile in the CLI."""
  89. _resolve_profile_dir(name)
  90. return "hermes setup" if name == "default" else f"{name} setup"
  91. def _scope_profile_name(path: Path) -> Optional[str]:
  92. """Map a profile directory onto the query name ``_config_profile_scope`` expects: None for
  93. the process home (current-profile semantics: launch secret scope, no home override),
  94. ``"default"`` for the default root (its basename -- ``.hermes`` or a custom root -- is not a
  95. profile name; launched from ``profiles/<name>`` the root is a *different* profile), the
  96. directory name for ``profiles/<name>``."""
  97. from hermes_constants import get_default_hermes_root
  98. resolved = path.resolve()
  99. if resolved == get_process_hermes_home().resolve():
  100. return None
  101. if resolved == get_default_hermes_root().resolve():
  102. return "default"
  103. return path.name
  104. def _write_profile_model(profile_dir: Path, provider: str, model: str, validate_in: Optional[Path] = None,
  105. base_url: str = "") -> None:
  106. """Write the main model assignment into ``profile_dir``'s config.yaml (HERMES_HOME-scoped)
  107. through the same validated /model shape as ``POST /api/model/set``.
  108. ``validate_in`` is the home whose ``providers:``/``.env``/catalog vouch for the pick (default:
  109. ``profile_dir`` itself). Profile-create passes the dashboard's own home: the picker that offered
  110. the model read THAT catalog, and a just-created profile has no credentials yet, so validating
  111. in the empty profile rejected every non-env provider (anthropic, ollama, custom).
  112. Both spans enter ``_config_profile_scope`` (home + secret scope), matching ``/api/model/set``:
  113. once the dashboard has served a secondary profile, ``switch_model``'s ``key_env`` probe goes
  114. through ``get_secret``, which fails closed without a scope and reports the provider as
  115. unconnected (UnscopedSecretError class, #114676).
  116. ``base_url`` is the endpoint a bare ``custom``/``local`` pick binds to (a fresh profile's config
  117. names none); other providers ignore it."""
  118. from hermes_cli.config import load_config, save_config
  119. from hermes_cli.config_backend import refusing_locked_omissions
  120. with _config_profile_scope(_scope_profile_name(validate_in or profile_dir)):
  121. provider, model = _normalize_main_model_assignment(provider, model)
  122. result = _validated_main_model_selection(load_config(), provider, model, base_url)
  123. with _config_profile_scope(_scope_profile_name(profile_dir)), _CONFIG_MUTATION_LOCK: # RMW span
  124. cfg = load_config()
  125. cfg["model"] = _apply_main_model_assignment(cfg.get("model", {}), result)
  126. with refusing_locked_omissions("model"):
  127. save_config(cfg)
  128. def _disable_unselected_skills(profile_dir: Path, keep: list[str]) -> int:
  129. """Disable every installed skill in ``profile_dir`` not in ``keep``; returns how many were
  130. newly disabled. Profiles manage activation via a *disabled* list (everything installed is
  131. active by default); the builder's skill step has "replace" semantics. Hub skills are
  132. installed separately via subprocess and are active on install."""
  133. from hermes_cli.config import load_config
  134. from hermes_cli.skills_config import get_disabled_skills, save_disabled_skills
  135. keep_set = {s.strip() for s in keep if s and s.strip()}
  136. with _hermes_home_scope(profile_dir), _CONFIG_MUTATION_LOCK: # RMW span
  137. skills_root = profile_dir / "skills"
  138. installed = ([md.parent.name for md in skills_root.rglob("SKILL.md")]
  139. if skills_root.is_dir() else [])
  140. cfg = load_config()
  141. disabled = get_disabled_skills(cfg)
  142. newly = 0
  143. for name in installed:
  144. if name not in keep_set and name not in disabled:
  145. disabled.add(name)
  146. newly += 1
  147. if newly:
  148. save_disabled_skills(cfg, disabled)
  149. return newly
  150. # Returned by the offloaded file readers below to mean "the file is not there", which a plain
  151. # ``None`` cannot express: ``desktop.json`` may legitimately hold the document ``null``.
  152. _MISSING = object()
  153. @contextlib.contextmanager
  154. def _profile_errors(log_msg: str, *args, not_found=(FileNotFoundError,),
  155. bad_request=(ValueError,)):
  156. """Map hermes_cli.profiles exceptions to HTTP: ``not_found`` -> 404, ``bad_request`` -> 400
  157. (in that order), anything else is logged with ``log_msg`` -> 500. HTTPException passes, and so
  158. does ``ProfileIdentitySettlementPending`` — a typed partial success the calling endpoint (the
  159. delete route) owns; it must not flatten into the generic 500."""
  160. try:
  161. yield
  162. except HTTPException:
  163. raise
  164. except not_found as e:
  165. raise HTTPException(status_code=404, detail=str(e))
  166. except bad_request as e:
  167. raise HTTPException(status_code=400, detail=str(e))
  168. except ProfileIdentitySettlementPending:
  169. raise
  170. except Exception as e:
  171. _log.exception(log_msg, *args)
  172. raise HTTPException(status_code=500, detail=str(e))
  173. async def _read_off_loop(read, label: str, errors):
  174. """``read()`` on a worker thread; ``errors`` become ``500 "Could not read <label>: e"``."""
  175. try:
  176. return await run_in_threadpool(read)
  177. except errors as e:
  178. raise HTTPException(status_code=500, detail=f"Could not read {label}: {e}")
  179. def _best_effort(log_msg: str, *args, fn, default=None):
  180. """Run ``fn()``; on failure log ``log_msg`` with traceback and return ``default`` (the
  181. parent operation already succeeded, so never 500)."""
  182. try:
  183. return fn()
  184. except Exception:
  185. _log.exception(log_msg, *args)
  186. return default
  187. def _profile_targets(log_label: str) -> list[tuple[str, Path]]:
  188. """(name, home) for every profile, falling back to ``default`` alone. Uses
  189. ``profiles_to_serve`` (pure directory read) instead of ``list_profiles``, which parses
  190. config/meta and probes gateways per profile — every caller here is a polled sidebar
  191. fan-out that only needs name/path (#114041)."""
  192. from hermes_cli import profiles as profiles_mod
  193. try:
  194. targets = list(profiles_mod.profiles_to_serve(multiplex=True, include_standalone=True, include_parked=True))
  195. except Exception:
  196. _log.exception("%s: profile enumeration failed", log_label)
  197. targets = []
  198. if not targets:
  199. targets.append(("default", profiles_mod.get_profile_dir("default")))
  200. return targets
  201. def _scoped_profile_targets(log_label: str, profile: Optional[str]) -> list[tuple[str, Path]]:
  202. """Every profile, or only ``profile``: a native grant may read just the profile it names,
  203. so the Desktop assembles the all-profiles view from one scoped read per profile."""
  204. scope = (profile or "all").strip() or "all"
  205. targets = _profile_targets(log_label)
  206. return targets if scope == "all" else [(name, home) for name, home in targets if name == scope]
  207. def _tag_rows(rows: list[dict[str, Any]], name: str, now: float) -> list[dict[str, Any]]:
  208. """Stamp session rows with their owning profile and the 300s active heuristic; SQLite
  209. stores flags as 0/1 and the sidebar needs booleans."""
  210. for s in rows:
  211. s["profile"] = name
  212. s["is_default_profile"] = name == "default"
  213. s["is_active"] = (
  214. s.get("ended_at") is None and (now - s.get("last_active", s.get("started_at", 0))) < 300
  215. )
  216. s["archived"] = bool(s.get("archived"))
  217. s["pinned"] = bool(s.get("pinned"))
  218. return rows
  219. def _pinned_window(rows: list[dict[str, Any]], offset: int, cap: int) -> list[dict[str, Any]]:
  220. """``rows[offset:offset+cap]`` plus every pinned row past it: the per-profile queries
  221. back-fill pinned rows past their LIMIT, so truncating on recency alone would drop them."""
  222. window = rows[offset:offset + cap]
  223. if len(rows) > offset + cap:
  224. seen = {id(s) for s in window}
  225. window.extend(s for s in rows[offset + cap:] if s.get("pinned") and id(s) not in seen)
  226. return window
  227. def _recency(s: dict[str, Any]) -> Any:
  228. return s.get("last_active") or s.get("started_at") or 0
  229. def _read_profile_db(name: str, home, errors: Optional[list[dict[str, str]]],
  230. fn: Callable[[Any], Any]) -> Any:
  231. """``fn(db)`` against the profile's read-only state.db; None when the file is missing,
  232. the open fails or ``fn`` raises (warned once, recorded in ``errors`` when given).
  233. Read-only on the healthy path: this runs on every sidebar refresh, so it must not
  234. routinely DDL/write-lock another profile's live DB. A store that predates a schema addition
  235. gets the missing declared tables/columns ONCE from the open helper, and only while no gateway
  236. owns it; an owned store is reported in ``errors`` with the restart remedy (#140315)."""
  237. db_path = Path(home) / "state.db"
  238. if not db_path.exists():
  239. return None
  240. db = None
  241. try:
  242. db = _open_session_db_at_path(db_path, read_only=True)
  243. return fn(db)
  244. except Exception as exc:
  245. # An open that dies on a damaged file never reaches SessionDB's read helpers.
  246. note_storage_error(db_path, exc)
  247. _warn_profile_read_error(name, exc)
  248. if errors is not None:
  249. errors.append({"profile": name, "error": str(exc)})
  250. return None
  251. finally:
  252. if db is not None:
  253. db.close()
  254. def _corrupt_profile_stores(targets) -> dict[str, str]:
  255. """``{profile: "corrupt"}`` for every scanned profile whose state.db this process has latched
  256. as structurally corrupt (``hermes_state_health``). Lets Desktop tell an empty or partial list
  257. from a damaged store, including when some reads still succeed (#72046)."""
  258. return {name: STORAGE_CORRUPT for name, home in targets
  259. if storage_state(Path(home) / "state.db") == STORAGE_CORRUPT}
  260. # Sidebar scan cache TTL: short enough that the UI never shows meaningfully stale data, long
  261. # enough to coalesce the desktop's reconnect/focus/change poll bursts into one scan.
  262. _SIDEBAR_CACHE_TTL_SECONDS = 5.0
  263. _SIDEBAR_CACHE_MAX_ENTRIES = 32
  264. _SIDEBAR_PROFILE_CACHE_MAX_ENTRIES = 256
  265. _SIDEBAR_PROFILE_CACHE = OrderedDict()
  266. _SIDEBAR_PROFILE_CACHE_LOCK = threading.Lock()
  267. def _stat_fingerprint(path: Path):
  268. """Return identity + mutation metadata without opening the file."""
  269. try:
  270. stat = path.stat()
  271. except OSError:
  272. return None
  273. return (stat.st_dev, stat.st_ino, stat.st_size, stat.st_mtime_ns)
  274. def _sidebar_db_fingerprint(db_path: Path):
  275. """Track SQLite content changes through the main DB and its WAL."""
  276. return (_stat_fingerprint(db_path), _stat_fingerprint(Path(f"{db_path}-wal")))
  277. def _sidebar_profile_cache_get(key):
  278. with _SIDEBAR_PROFILE_CACHE_LOCK:
  279. value = _SIDEBAR_PROFILE_CACHE.get(key)
  280. if value is None:
  281. return None
  282. _SIDEBAR_PROFILE_CACHE.move_to_end(key)
  283. return copy.deepcopy(value)
  284. def _sidebar_profile_cache_put(key, value):
  285. db_path, fingerprint = key[:2]
  286. snapshot = copy.deepcopy(value)
  287. with _SIDEBAR_PROFILE_CACHE_LOCK:
  288. # A changed DB/WAL obsoletes every older parameter variant for that profile; drop
  289. # them eagerly rather than waiting for LRU pressure.
  290. for existing in [k for k in _SIDEBAR_PROFILE_CACHE
  291. if k[0] == db_path and k[1] != fingerprint]:
  292. _SIDEBAR_PROFILE_CACHE.pop(existing, None)
  293. _SIDEBAR_PROFILE_CACHE[key] = snapshot
  294. _SIDEBAR_PROFILE_CACHE.move_to_end(key)
  295. while len(_SIDEBAR_PROFILE_CACHE) > _SIDEBAR_PROFILE_CACHE_MAX_ENTRIES:
  296. _SIDEBAR_PROFILE_CACHE.popitem(last=False)
  297. def _sidebar_profile_cache_clear():
  298. with _SIDEBAR_PROFILE_CACHE_LOCK:
  299. _SIDEBAR_PROFILE_CACHE.clear()
  300. def _profile_state_db(home) -> Path:
  301. return Path(home) / "state.db"
  302. def _slice_has_rows(slices: dict[str, Any]) -> bool:
  303. return any(slices.get(key) for key in ("recents", "cron", "messaging"))
  304. def _retryable_profile_errors(errors: list[dict[str, str]], scanned) -> list[dict[str, str]]:
  305. """Scan failures Retry can re-attempt. A latched corrupt store has its own notice."""
  306. corrupt = set(_corrupt_profile_stores(scanned))
  307. return [dict(err) for err in errors if err.get("profile") not in corrupt]
  308. def _failed_load_slice(errors: list[dict[str, str]], **extra) -> dict[str, Any]:
  309. """Failed load: no ``sessions`` key. An empty list would read as data loss."""
  310. return {"failed": True, "retry": True, "errors": [dict(err) for err in errors], **extra}
  311. def _profiles_failed(errors: list[dict[str, str]]) -> dict[str, dict[str, Any]]:
  312. return {
  313. err["profile"]: {"failed": True, "retry": True, "error": err.get("error", "")}
  314. for err in errors if err.get("profile")
  315. }
  316. def _sidebar_singleflight_cache(func):
  317. """Coalesce concurrent sidebar scans and briefly reuse their response.
  318. Every uncached refresh opens every profile database; desktop poll bursts overlap identical
  319. scans in AnyIO worker threads, starving the uvicorn loop for the GIL. The TTL bounds UI
  320. staleness; the single-flight lock guarantees one expensive scan at a time. Cached values
  321. are copied on store and hit so serialization or a caller cannot mutate shared state.
  322. """
  323. signature = inspect.signature(func)
  324. cache = OrderedDict()
  325. cache_lock = threading.Lock()
  326. refresh_lock = threading.Lock()
  327. miss = object()
  328. def _lookup(key):
  329. now = time.monotonic()
  330. with cache_lock:
  331. item = cache.get(key)
  332. if item is None or now >= item[0]:
  333. cache.pop(key, None)
  334. return miss
  335. cache.move_to_end(key)
  336. return copy.deepcopy(item[1])
  337. @functools.wraps(func)
  338. def wrapped(*args, **kwargs):
  339. ttl = _SIDEBAR_CACHE_TTL_SECONDS
  340. if ttl <= 0:
  341. return func(*args, **kwargs)
  342. bound = signature.bind(*args, **kwargs)
  343. bound.apply_defaults()
  344. key = tuple(bound.arguments.items())
  345. cached = _lookup(key)
  346. if cached is not miss:
  347. return cached
  348. # A plain Lock is intentional: FastAPI executes this sync handler in the AnyIO
  349. # worker pool, so contenders sleep without holding the GIL.
  350. with refresh_lock:
  351. cached = _lookup(key)
  352. if cached is not miss:
  353. return cached
  354. result = func(*args, **kwargs)
  355. # A 200 carrying errors[] is a FAILED profile scan, not a successful empty page.
  356. # Caching it would hold the empty recents in front of a store that has already
  357. # recovered, for the whole TTL.
  358. if isinstance(result, dict) and result.get("errors"):
  359. return result
  360. try:
  361. snapshot = copy.deepcopy(result)
  362. except Exception:
  363. _log.exception("sidebar response could not be cached")
  364. return result
  365. with cache_lock:
  366. cache[key] = (time.monotonic() + ttl, snapshot)
  367. cache.move_to_end(key)
  368. while len(cache) > _SIDEBAR_CACHE_MAX_ENTRIES:
  369. cache.popitem(last=False)
  370. return result
  371. return wrapped
  372. def _csv_list(value: Optional[str]) -> list[str]:
  373. return [s.strip() for s in (value or "").split(",") if s.strip()]
  374. @sessions_router.get("/api/profiles/sessions")
  375. def get_profiles_sessions(
  376. # ``le=500`` caps the page size — this endpoint fans out across EVERY profile's state.db.
  377. # 500 (not 100) because desktop callers use limit=200 and the electron remote-merge
  378. # over-fetches ``limit + offset``.
  379. limit: int = Query(20, ge=0, le=500), offset: int = Query(0, ge=0), min_messages: int = 0,
  380. archived: str = "exclude", order: str = "recent", profile: str = "all",
  381. source: str | None = None, sources: str | None = None, exclude_sources: str | None = None, full: bool = False):
  382. """Unified, read-only session list aggregated across ALL profiles: opens each profile's
  383. ``state.db`` directly (no dashboard backend per profile) and tags rows with their owning
  384. ``profile``. Rows omit ``system_prompt`` / ``model_config`` unless ``full=1`` — same
  385. projection as ``/api/sessions``."""
  386. if archived not in ("exclude", "only", "include"):
  387. raise HTTPException(status_code=400, detail="archived must be one of: exclude, only, include")
  388. if order not in ("created", "recent"):
  389. raise HTTPException(status_code=400, detail="order must be one of: created, recent")
  390. targets = ([_cron_profile_home(profile)] if profile and profile != "all"
  391. else _profile_targets("GET /api/profiles/sessions"))
  392. # Source scoping (see /api/sessions): recents pass exclude_sources=cron, the cron-jobs
  393. # section source=cron — two independent lists so cron sessions can't starve recents.
  394. filters = dict(
  395. source=source or None, sources=_csv_list(sources) or None,
  396. exclude_sources=_csv_list(exclude_sources) or None, min_message_count=max(0, min_messages),
  397. include_archived=archived == "include", archived_only=archived == "only")
  398. # Over-fetch per profile so the merged+sorted window is correct for the requested page.
  399. # ``limit`` is already bounded to 500 by FastAPI; the offset is caller-controlled
  400. # pagination state, so include it instead of capping the source window at 500.
  401. # Otherwise page 3 of a 577-row profile is permanently empty even though ``total``
  402. # reports the remaining rows.
  403. per_profile = limit + offset
  404. merged: list[dict[str, Any]] = []
  405. totals: dict[str, int] = {}
  406. errors: list[dict[str, str]] = []
  407. now = time.time()
  408. for name, home in targets:
  409. def _read(db, name=name, home=home):
  410. include_subagents, exclude = subagent_listing_scope(
  411. home, source=filters["source"], sources=filters["sources"],
  412. exclude_sources=filters["exclude_sources"])
  413. scoped = {**filters, "exclude_sources": exclude, "include_subagents": include_subagents}
  414. rows = db.list_sessions_rich(
  415. limit=per_profile, offset=0, order_by_last_active=order == "recent",
  416. # Same SQL-level blob skip as /api/sessions.
  417. compact_rows=not full, include_pinned=True, **scoped)
  418. totals[name] = db.session_count(exclude_children=True, **scoped)
  419. merged.extend(_tag_rows(rows, name, now))
  420. _read_profile_db(name, home, errors, _read)
  421. sort_key = "last_active" if order == "recent" else "started_at"
  422. merged.sort(key=lambda s: s.get(sort_key) or s.get("started_at") or 0, reverse=True)
  423. if archived == "only":
  424. # Pinned live chats back-fill this view, but cannot consume positions
  425. # in its archived-only cursor (whose total counts only archived rows).
  426. window = _pinned_window([s for s in merged if s.get("archived")], offset, limit)
  427. # Keep backfill after the window: clients retain only limit rows plus pins.
  428. window.extend(s for s in merged if s.get("pinned") and not s.get("archived"))
  429. else:
  430. window = _pinned_window(merged, offset, limit)
  431. if not full:
  432. _strip_session_list_rows(window)
  433. return {"sessions": window, "total": sum(totals.values()), "profile_totals": totals,
  434. "limit": limit, "offset": offset, "errors": errors,
  435. "storage": _corrupt_profile_stores(targets)}
  436. @sessions_router.get("/api/profiles/sessions/sidebar")
  437. @_sidebar_singleflight_cache
  438. def get_profiles_sessions_sidebar(
  439. recents_profile: str = "all", recents_limit: int = 20, recents_exclude: str | None = None,
  440. cron_limit: int = 50, messaging_limit: int = 100, messaging_exclude: str | None = None):
  441. """Batched sidebar session slices (recents / cron / messaging) — one profile-DB open per
  442. refresh instead of three ``/api/profiles/sessions`` calls. Same row projection and 300s
  443. active heuristic as the per-slice endpoint; all slices use ``min_messages=1`` /
  444. ``archived=exclude`` / recency order.
  445. ``recents_profile`` scopes the WHOLE payload, not just recents — the sidebar has one
  446. scope, so a concrete profile must never show another profile's Telegram threads or
  447. cronjobs; ``all`` asks for everything.
  448. See #42651, #65710, #70629.
  449. """
  450. targets = _profile_targets("GET /api/profiles/sessions/sidebar")
  451. recents_scope = (recents_profile or "all").strip() or "all"
  452. recents_exclude_list = [s for s in (recents_exclude or "").split(",") if s.strip()]
  453. messaging_exclude_list = [s for s in (messaging_exclude or "").split(",") if s.strip()]
  454. # (source, exclude) per slice; ``source=cron`` is the implicit cron taxonomy.
  455. slice_scope = {"recents": (None, recents_exclude_list), "cron": ("cron", None),
  456. "messaging": (None, messaging_exclude_list)}
  457. cap = {"recents": min(max(recents_limit, 1), 500), "cron": min(max(cron_limit, 1), 500),
  458. "messaging": min(max(messaging_limit, 1), 500)}
  459. rows: dict[str, list[dict[str, Any]]] = {k: [] for k in slice_scope}
  460. recents_truncated: dict[str, bool] = {}
  461. profile_totals: dict[str, dict[str, float]] = {}
  462. errors: list[dict[str, str]] = []
  463. now = time.time()
  464. def _slice(db, key, recents_subagents=(False, None)):
  465. source, exclude = slice_scope[key]
  466. # Only recents takes subagent runs (sessions.show_subagents); cron/messaging keep shape.
  467. include_subagents, exclude = recents_subagents if key == "recents" else (False, exclude)
  468. # include_pinned: a pinned conversation must reach the sidebar even when it has aged
  469. # past the window, or its Pinned row renders empty.
  470. return db.list_sessions_rich(
  471. source=source, exclude_sources=exclude or None, limit=cap[key], offset=0,
  472. min_message_count=1, include_archived=False, archived_only=False,
  473. order_by_last_active=True, compact_rows=True, include_pinned=True,
  474. include_subagents=include_subagents)
  475. def _build_slices(db, cache_key, recents_subagents):
  476. # ``usage`` is aggregated in SQL rather than over the recents window: the window is a
  477. # page, and a total that shrank when you scrolled would be worse than no total at all.
  478. slices = {"recents": _slice(db, "recents", recents_subagents), "usage": db.usage_totals(),
  479. "cron": _slice(db, "cron"), "messaging": _slice(db, "messaging")}
  480. _sidebar_profile_cache_put(cache_key, slices)
  481. return slices
  482. scanned = []
  483. contributed: set = set()
  484. for name, home in targets:
  485. if recents_scope != "all" and name != recents_scope:
  486. continue
  487. scanned.append((name, home))
  488. db_path = _profile_state_db(home)
  489. if not db_path.exists():
  490. continue
  491. recents_subagents = subagent_listing_scope(home, exclude_sources=recents_exclude_list or None)
  492. profile_cache_key = (str(db_path), _sidebar_db_fingerprint(db_path), cap["recents"],
  493. tuple(recents_exclude_list), cap["cron"], cap["messaging"],
  494. tuple(messaging_exclude_list), recents_subagents[0])
  495. slices = _sidebar_profile_cache_get(profile_cache_key)
  496. if slices is None:
  497. slices = _read_profile_db(
  498. name, home, errors,
  499. lambda db: _build_slices(db, profile_cache_key, recents_subagents))
  500. if slices is None:
  501. continue
  502. if _slice_has_rows(slices):
  503. contributed.add(name)
  504. # A full window means more rows remain on disk — all "load more" needs, at no cost
  505. # beyond the rows already read. Pinned rows count: they occupy LIMIT slots, and a
  506. # short list has nothing past the page for the pin back-fill to add, so pins cannot
  507. # fake a full page (#81484).
  508. recents_truncated[name] = len(slices["recents"]) >= cap["recents"]
  509. profile_totals[name] = slices["usage"]
  510. for key in slice_scope:
  511. rows[key].extend(_tag_rows(slices[key], name, now))
  512. def _window(key: str) -> list[dict[str, Any]]:
  513. rows[key].sort(key=_recency, reverse=True)
  514. win = _pinned_window(rows[key], 0, cap[key])
  515. _strip_session_list_rows(win)
  516. return win
  517. storage = _corrupt_profile_stores(scanned)
  518. retryable = _retryable_profile_errors(errors, scanned)
  519. failed_names = {err["profile"] for err in retryable if err.get("profile")}
  520. corrupt = set(storage)
  521. live = [name for name, _home in scanned if name not in corrupt]
  522. scoped_failed = (
  523. recents_scope != "all"
  524. and recents_scope in failed_names
  525. and recents_scope not in contributed
  526. )
  527. all_failed = (
  528. recents_scope == "all"
  529. and bool(live)
  530. and not contributed
  531. and all(name in failed_names for name in live)
  532. )
  533. if scoped_failed or all_failed:
  534. # The whole answer is this profile's (or every profile's) failed scan.
  535. # Do not include ``sessions``: an empty list is a successful read.
  536. return {
  537. "recents": _failed_load_slice(
  538. retryable, profiles_truncated={}, profiles_usage={}),
  539. "cron": _failed_load_slice(retryable),
  540. "messaging": _failed_load_slice(retryable, total=0),
  541. "errors": errors, "storage": storage}
  542. body = {
  543. "recents": {"sessions": _window("recents"), "profiles_truncated": recents_truncated,
  544. "profiles_usage": profile_totals},
  545. "cron": {"sessions": _window("cron")},
  546. "messaging": {"sessions": _window("messaging"), "total": len(rows["messaging"])},
  547. "errors": errors, "storage": storage}
  548. # A sibling profile still listed does not make the failed profile's absence
  549. # a successful empty slice. Stamp that profile as a failed load with Retry.
  550. failed = _profiles_failed(retryable)
  551. if failed:
  552. body["profiles_failed"] = failed
  553. for key in ("recents", "cron", "messaging"):
  554. body[key]["profiles_failed"] = failed
  555. body[key]["errors"] = [dict(err) for err in retryable]
  556. return body
  557. def _merge_by_id(into: dict[str, dict[str, Any]], entries: list[dict[str, Any]], child_key: str) -> None:
  558. """Fold ``entries`` into ``into`` by id, recursing through one child list (repos merge
  559. their lanes, lanes merge their sessions). Counts add up; everything else is
  560. first-writer, since the entries describe the same path either way."""
  561. for entry in entries:
  562. existing = into.get(entry["id"])
  563. if existing is None:
  564. into[entry["id"]] = entry
  565. continue
  566. if child_key == "sessions":
  567. existing["sessions"].extend(entry.get("sessions") or [])
  568. else:
  569. children: dict[str, dict[str, Any]] = {c["id"]: c for c in existing.get(child_key) or []}
  570. _merge_by_id(children, entry.get(child_key) or [], "sessions")
  571. existing[child_key] = list(children.values())
  572. if "sessionCount" in existing:
  573. existing["sessionCount"] = (existing.get("sessionCount") or 0) + (entry.get("sessionCount") or 0)
  574. def _merge_profile_tree(
  575. merged: dict[str, dict[str, Any]], projects: list[dict[str, Any]], profile: str,
  576. preview_limit: int) -> None:
  577. """Fold one profile's projects into the shared tree, keyed by folder: the same checkout
  578. in two profiles is one group, as is ``__no_project__`` (else one "Home" per profile), and
  579. a declared project (``p_<hash>``) folds with another profile's auto entry for the same
  580. folder. Sessions carry the owning profile; a group header never claims a single owner."""
  581. for project in projects:
  582. lane_sessions = (s for r in project.get("repos") or []
  583. for lane in r.get("groups") or []
  584. for s in lane.get("sessions") or [])
  585. for session in [*lane_sessions, *(project.get("previewSessions") or [])]:
  586. session["profile"] = profile
  587. session["is_default_profile"] = profile == "default"
  588. # Same folder-identity notion the per-profile tree builder uses (``_path_key``):
  589. # shape-derived — Windows paths case-fold on any host, separators unify, NFC —
  590. # so the cross-profile merge agrees by construction with the trees it merges.
  591. from tui_gateway.project_tree import _path_key
  592. key = _path_key(project.get("path") or project["id"])
  593. # A per-profile read is merged again by its caller, which cannot compute this key.
  594. project["mergeKey"] = key
  595. existing = merged.get(key)
  596. if existing is None:
  597. merged[key] = project
  598. continue
  599. # A declared project carries the label, color and icon the user chose, so it wins
  600. # the identity when it meets another profile's auto entry.
  601. if existing.get("isAuto") and not project.get("isAuto"):
  602. existing, project = project, existing
  603. merged[key] = existing
  604. repos: dict[str, dict[str, Any]] = {r["id"]: r for r in existing.get("repos") or []}
  605. _merge_by_id(repos, project.get("repos") or [], "groups")
  606. existing["repos"] = list(repos.values())
  607. for total_key in ("sessionCount", "totalTokens", "totalCostUsd"):
  608. existing[total_key] = (existing.get(total_key) or 0) + (project.get(total_key) or 0)
  609. existing["lastActive"] = max(existing.get("lastActive") or 0, project.get("lastActive") or 0)
  610. previews = (existing.get("previewSessions") or []) + (project.get("previewSessions") or [])
  611. previews.sort(key=_recency, reverse=True)
  612. existing["previewSessions"] = previews[:preview_limit]
  613. @sessions_router.get("/api/profiles/projects/tree")
  614. @_sidebar_singleflight_cache
  615. def get_profiles_projects_tree(preview_limit: int = 3, session_limit: int = 2000, profile: Optional[str] = None):
  616. """Project tree for every profile at once, for the all-profiles sidebar.
  617. ``projects.tree`` over JSON-RPC answers for the backend's own profile only; this runs the
  618. same builder once per profile against its ``state.db``, scoping the other inputs
  619. (projects.db, repo-scan policy, junk filters) through the home override. Discovery is
  620. off: a repo with zero sessions is the same repo in every profile (the disk scan would
  621. multiply empty lanes by the profile count), and discovery is the one part of the builder
  622. that writes (policy reconciliation), which a read-only fan-out must not do.
  623. ``profile`` limits the scan to that one profile: a native grant may read only its own, so
  624. the Desktop merges one such read per profile by each project's ``mergeKey``.
  625. """
  626. from tui_gateway import server as gateway_server
  627. merged: dict[str, dict[str, Any]] = {}
  628. scoped_session_ids: list[str] = []
  629. errors: list[dict[str, str]] = []
  630. for name, home in _scoped_profile_targets("GET /api/profiles/projects/tree", profile):
  631. def _read(db, name=name, home=home):
  632. with _hermes_home_scope(home):
  633. tree, _active_id = gateway_server._build_project_tree(
  634. db, preview_limit=preview_limit, hydrate=False,
  635. session_limit=session_limit, include_discovered=False)
  636. _merge_profile_tree(merged, tree["projects"], name, preview_limit)
  637. scoped_session_ids.extend(tree["scoped_session_ids"])
  638. _read_profile_db(name, home, errors, _read)
  639. # active_id is None: ownership is per profile, so no project is "the active one" here.
  640. projects = sorted(merged.values(), key=lambda p: p.get("lastActive") or 0, reverse=True)
  641. return {"projects": projects, "active_id": None, "scoped_session_ids": scoped_session_ids,
  642. "errors": errors}
  643. # `gh pr create` prints the PR url and nothing else, so a tool result whose whole output IS a
  644. # PR url means this session opened that PR; a url inside prose is a session TALKING about one.
  645. _PR_URL_RE = re.compile(r"^https://github\.com/[\w.-]+/[\w.-]+/pull/(\d+)/?$")
  646. def _pr_url_from_tool_output(content: str) -> Optional[tuple[int, str]]:
  647. """The (number, url) a tool result announces, or None."""
  648. try:
  649. output = (json.loads(content) or {}).get("output")
  650. except (json.JSONDecodeError, TypeError, AttributeError):
  651. return None
  652. if not isinstance(output, str):
  653. return None
  654. match = _PR_URL_RE.match(output.strip())
  655. return (int(match.group(1)), match.group(0)) if match else None
  656. @sessions_router.post("/api/profiles/sessions/pull-requests")
  657. def post_profiles_sessions_pull_requests(body: SessionPrScanBody, profile: Optional[str] = None):
  658. """The PR each of these sessions opened, recovered from its own transcript: a session
  659. that starts in the main checkout and works in a worktree has no branch of its own, so
  660. its PR is invisible to the branch join — but ``gh pr create`` ran in the conversation
  661. (see ``_pr_url_from_tool_output``). Read-only across every profile."""
  662. wanted = list(dict.fromkeys(s for s in (body.ids or []) if s))[:2000]
  663. if not wanted:
  664. return {"pull_requests": {}, "scanned": []}
  665. found: dict[str, dict[str, Any]] = {}
  666. def _read(db):
  667. for pr in db.find_pr_url_messages(wanted):
  668. parsed = _pr_url_from_tool_output(pr["content"])
  669. if parsed:
  670. # Oldest-first, so a later `gh pr create` (the replacement PR) wins.
  671. found[pr["session_id"]] = {"number": parsed[0], "url": parsed[1]}
  672. for name, home in _scoped_profile_targets("POST /api/profiles/sessions/pull-requests", profile):
  673. _read_profile_db(name, home, None, _read)
  674. # ``scanned``: every id looked at, so the caller can remember "nothing there".
  675. return {"pull_requests": found, "scanned": wanted}
  676. @functools.partial(coalesced_read, thread_runner=lambda func: run_in_threadpool(func))
  677. def _read_profiles():
  678. from hermes_cli import profiles as profiles_mod
  679. try:
  680. # Polled by the Desktop on every focus/roster tick: never walk skill trees in-request.
  681. profiles = profiles_mod.list_profiles(lazy_skill_count=True)
  682. return {"profiles": [_profile_to_dict(p) for p in profiles]}
  683. except Exception:
  684. _log.exception("GET /api/profiles failed; falling back to profile directory scan")
  685. return {"profiles": _fallback_profile_dicts(profiles_mod)}
  686. @router.get("/api/profiles")
  687. async def list_profiles_endpoint():
  688. return await _read_profiles()
  689. @router.post("/api/profiles")
  690. async def create_profile_endpoint(body: ProfileCreate):
  691. from hermes_cli import profiles as profiles_mod
  692. explicit_source = (body.clone_from or "").strip()
  693. if explicit_source:
  694. # Clone config/skills/SOUL (or full state when clone_all) from the named source.
  695. clone, clone_from, clone_config = True, explicit_source, not body.clone_all
  696. elif body.clone_all:
  697. # Historical dashboard behavior: clone-all with no explicit source copies default.
  698. clone, clone_from, clone_config = True, "default", False
  699. else:
  700. clone = body.clone_from_default
  701. clone_from = "default" if clone else None
  702. clone_config = clone
  703. with _profile_errors("POST /api/profiles failed", not_found=(),
  704. bad_request=(ValueError, FileExistsError, FileNotFoundError)):
  705. # Off the loop: creation asks a live multiplexer to serve the profile now over its control
  706. # socket, and on the gateway's own listener (the Webapp) that socket answers on this loop.
  707. path = await asyncio.to_thread(
  708. profiles_mod.create_profile,
  709. name=body.name, clone_from=clone_from, clone_all=body.clone_all,
  710. clone_config=clone_config, no_skills=body.no_skills, description=body.description,
  711. clone_channels=body.clone_channels, **({"soul": body.soul} if body.soul is not None else {}))
  712. # Match the CLI flow: fresh named profiles get the bundled skills (cloning already
  713. # copied the source's; no_skills wrote the opt-out marker so seeding no-ops) and a
  714. # ~/.local/bin wrapper when the alias is safe.
  715. if not clone:
  716. profiles_mod.seed_profile_skills(path, quiet=True)
  717. if not profiles_mod.check_alias_collision(body.name):
  718. profiles_mod.create_wrapper_script(body.name)
  719. # Everything below is best-effort: the profile already exists, so a hiccup must not 500
  720. # the whole create — the user can fix it from the dashboard or `<profile> setup`.
  721. provider = (body.provider or "").strip()
  722. model = (body.model or "").strip()
  723. # Validate against THIS dashboard's home (the catalog the picker offered), not the empty
  724. # new profile; the write still lands in the new profile. A rejection is reported (not just
  725. # logged) so the dialog can say WHY the model was not set.
  726. model_error = ""
  727. def _set_model() -> bool:
  728. nonlocal model_error
  729. try:
  730. _write_profile_model(path, provider, model, validate_in=get_process_hermes_home())
  731. except HTTPException as exc:
  732. model_error = str(exc.detail)
  733. return False
  734. return True
  735. model_set = bool(provider and model) and _best_effort(
  736. "Setting model for new profile %s failed", body.name, fn=_set_model, default=False)
  737. mcp_written = _best_effort(
  738. "Writing MCP servers for new profile %s failed", body.name, default=0,
  739. fn=lambda: _write_profile_mcp_servers(path, body.mcp_servers)) if body.mcp_servers else 0
  740. # "keep" has replace semantics; skipped when empty (legacy: keep the bundle).
  741. skills_disabled = _best_effort(
  742. "Applying skill selection for new profile %s failed", body.name, default=0,
  743. fn=lambda: _disable_unselected_skills(path, body.keep_skills)) if body.keep_skills else 0
  744. # Hub installs spawn async, scoped via `-p <name>` (a fresh subprocess re-binds
  745. # skills_hub.SKILLS_DIR at import). PIDs go back for the UI to poll.
  746. def _spawn_install(ident: str):
  747. return _spawn_hermes_action(["-p", body.name, "skills", "install", ident, "--yes"],
  748. _hub_action_name("install", ident)).pid
  749. hub_installs: list[dict[str, Any]] = [
  750. {"identifier": ident, "pid": _best_effort(
  751. "Spawning hub-skill install %s for new profile %s failed", ident, body.name,
  752. fn=lambda: _spawn_install(ident))}
  753. for ident in ((i or "").strip() for i in body.hub_skills) if ident]
  754. return {"ok": True, "name": body.name, "path": str(path), "model_set": model_set, "model_error": model_error,
  755. "mcp_written": mcp_written, "skills_disabled": skills_disabled,
  756. "hub_installs": hub_installs, "soul_set": body.soul is not None}
  757. @router.get("/api/profiles/active")
  758. async def get_active_profile_endpoint():
  759. """``active`` is the sticky default written by ``hermes profile use`` (what new CLI
  760. invocations pick up); ``current`` is the profile this running dashboard is scoped to."""
  761. from hermes_cli import profiles as profiles_mod
  762. def _run():
  763. # Both reads touch the filesystem; one hop so sidebar polling costs one round-trip.
  764. def _or_default(fn, on_error="default"):
  765. try:
  766. return fn() or "default"
  767. except Exception:
  768. return on_error
  769. # A dashboard that cannot name its own home must not read as the machine
  770. # dashboard: "default" is exactly what lets the SPA adopt the sticky profile.
  771. return {"active": _or_default(profiles_mod.get_active_profile),
  772. "current": _or_default(profiles_mod.get_active_profile_name, on_error="custom")}
  773. return await run_in_threadpool(_run)
  774. @router.post("/api/profiles/active")
  775. async def set_active_profile_endpoint(body: ProfileActiveUpdate):
  776. """Set the sticky active profile (mirrors ``hermes profile use``); does not retarget the
  777. running dashboard, only subsequent CLI commands and gateways."""
  778. from hermes_cli import profiles as profiles_mod
  779. with _profile_errors("POST /api/profiles/active failed"):
  780. # Stats the target, creates the state directory, writes via temp file + replace.
  781. await run_in_threadpool(profiles_mod.set_active_profile, body.name)
  782. return {"ok": True, "active": profiles_mod.normalize_profile_name(body.name)}
  783. @router.get("/api/profiles/{name}/setup-command")
  784. async def get_profile_setup_command(name: str):
  785. return {"command": _profile_setup_command(name)}
  786. # (executable, flag): None = takes one quoted `sh -lc '…'` string after -e; "" = argv follows
  787. # the executable directly (kitty).
  788. _LINUX_TERMINALS = (
  789. ("x-terminal-emulator", "-e"), ("gnome-terminal", "--"), ("konsole", "-e"),
  790. ("xfce4-terminal", None), ("mate-terminal", None), ("lxterminal", None),
  791. ("tilix", "-e"), ("alacritty", "-e"), ("kitty", ""), ("xterm", "-e"))
  792. def _linux_terminal_commands(command: str) -> list:
  793. sh = ["sh", "-lc", command]
  794. quoted = f"sh -lc '{command}'"
  795. return [
  796. (exe, [exe, "-e", quoted] if flag is None else [exe, *([flag] if flag else []), *sh])
  797. for exe, flag in _LINUX_TERMINALS]
  798. @router.post("/api/profiles/{name}/open-terminal")
  799. async def open_profile_terminal_endpoint(name: str):
  800. with _profile_errors("POST /api/profiles/%s/open-terminal failed", name):
  801. command = _profile_setup_command(name)
  802. if sys.platform.startswith("win"):
  803. subprocess.Popen(["cmd.exe", "/c", "start", "", command]) # noqa: ASYNC220 -- fire-and-forget spawn; Popen returns immediately and callers need the Popen object
  804. elif sys.platform == "darwin":
  805. escaped = command.replace("\\", "\\\\").replace('"', '\\"')
  806. subprocess.Popen(["osascript", "-e", # noqa: ASYNC220 -- fire-and-forget spawn; Popen returns immediately and callers need the Popen object
  807. f'tell application "Terminal"\nactivate\ndo script "{escaped}"\nend tell'])
  808. else:
  809. for executable, popen_args in _linux_terminal_commands(command):
  810. if await asyncio.to_thread(subprocess.call, ["which", executable], stdout=subprocess.DEVNULL,
  811. stderr=subprocess.DEVNULL) == 0:
  812. subprocess.Popen(popen_args) # noqa: ASYNC220 -- fire-and-forget spawn; Popen returns immediately and callers need the Popen object
  813. break
  814. else:
  815. raise HTTPException(status_code=400, detail="No supported terminal emulator found")
  816. return {"ok": True, "command": command}
  817. @router.patch("/api/profiles/{name}")
  818. async def rename_profile_endpoint(name: str, body: ProfileRename):
  819. from hermes_cli import profiles as profiles_mod
  820. with _profile_errors("PATCH /api/profiles/%s failed", name,
  821. bad_request=(ValueError, FileExistsError)):
  822. # Stops a running gateway (10 s poll), renames the directory, rewrites the Honcho
  823. # host blocks and regenerates the wrapper script.
  824. path = await run_in_threadpool(profiles_mod.rename_profile, name, body.new_name)
  825. # For the default profile the rename lands as a presentation-only display_name; the
  826. # canonical id ("default") is always returned so callers keying on `name` stay correct.
  827. try:
  828. is_default = profiles_mod.normalize_profile_name(name) == "default"
  829. except ValueError:
  830. is_default = False
  831. if is_default:
  832. return {"ok": True, "name": "default", "display_name": body.new_name.strip(), "path": str(path)}
  833. return {"ok": True, "name": profiles_mod.normalize_profile_name(body.new_name), "path": str(path)}
  834. @router.delete("/api/profiles/{name}")
  835. async def delete_profile_endpoint(name: str):
  836. """The dashboard collects the user's confirmation in its own dialog, so ``yes=True``
  837. always skips the CLI's interactive prompt.
  838. A delete whose identity settlement stays pending answers ``ok`` with ``settlement_pending``
  839. and the retry command: the profile directory is already gone, and folding that state into
  840. the generic 500 made a dashboard client read a completed delete as a failure (its retry
  841. then 404'd)."""
  842. from hermes_cli import profiles as profiles_mod
  843. try:
  844. with _profile_errors("DELETE /api/profiles/%s failed", name):
  845. # Polls a running gateway's PID for up to 10 s, then rmtree()s the directory; on the
  846. # loop that parks every request past the desktop's 10 s WebSocket ready-probe.
  847. path = await run_in_threadpool(profiles_mod.delete_profile, name, yes=True)
  848. except ProfileIdentitySettlementPending as exc:
  849. return {"ok": True, "path": str(exc.path), "identity_settled": False,
  850. "settlement_pending": True, "retry_command": exc.retry_command}
  851. return {"ok": True, "path": str(path)}
  852. @router.get("/api/profiles/{name}/soul")
  853. async def get_profile_soul(name: str):
  854. soul_path = _resolve_profile_dir(name) / "SOUL.md"
  855. def _run():
  856. # Probe and read in one hop (two round-trips would widen the check/read window).
  857. if not soul_path.exists():
  858. return _MISSING
  859. return soul_path.read_text(encoding="utf-8-sig")
  860. content = await _read_off_loop(_run, "SOUL.md", OSError)
  861. if content is _MISSING:
  862. return {"content": "", "exists": False}
  863. return {"content": content, "exists": True}
  864. @router.put("/api/profiles/{name}/soul")
  865. async def update_profile_soul(name: str, body: ProfileSoulUpdate):
  866. soul_path = _resolve_profile_dir(name) / "SOUL.md"
  867. def _run():
  868. from utils import atomic_write_text
  869. # Atomic: a bare write_text() truncates SOUL.md before the new body lands, and the
  870. # paired GET reports an unreadable file as "never set" — so an interrupted save would
  871. # make the editor's next Save persist an empty document. preserve_mode keeps an
  872. # existing file's mode/owner; create_mode=0o644 covers the first save (profiles
  873. # chmods only .env to 0600 and SOUL.md is not a secret).
  874. atomic_write_text(soul_path, body.content, preserve_mode=True, create_mode=0o644)
  875. try:
  876. # Temp file + fsync + replace blocks for as long as the filesystem takes to commit.
  877. await run_in_threadpool(_run)
  878. except OSError as e:
  879. _log.exception("PUT /api/profiles/%s/soul failed", name)
  880. raise HTTPException(status_code=500, detail=f"Could not write SOUL.md: {e}")
  881. return {"ok": True}
  882. @router.put("/api/profiles/{name}/description")
  883. async def update_profile_description_endpoint(name: str, body: ProfileDescriptionUpdate):
  884. """Set or clear a profile's role description (kanban routing signal), stored as
  885. user-authored (``description_auto: false``) so the auto-describer won't overwrite it."""
  886. from hermes_cli import profiles as profiles_mod
  887. profile_dir = _resolve_profile_dir(name)
  888. text = (body.description or "").strip()
  889. with _profile_errors("PUT /api/profiles/%s/description failed", name,
  890. not_found=(), bad_request=()):
  891. await run_in_threadpool(
  892. profiles_mod.write_profile_meta, profile_dir, description=text, description_auto=False)
  893. return {"ok": True, "description": text, "description_auto": False}
  894. @router.put("/api/profiles/{name}/model")
  895. async def update_profile_model_endpoint(name: str, body: ProfileModelUpdate):
  896. """Set the main model for a specific profile's config.yaml without touching the dashboard's
  897. own profile — ``POST /api/model/set`` (main scope) via the HERMES_HOME override."""
  898. profile_dir = _resolve_profile_dir(name)
  899. provider = (body.provider or "").strip()
  900. model = (body.model or "").strip()
  901. if not provider or not model:
  902. raise HTTPException(status_code=400, detail="provider and model are required")
  903. with _profile_errors("PUT /api/profiles/%s/model failed", name,
  904. not_found=(), bad_request=()):
  905. await run_in_threadpool(_write_profile_model, profile_dir, provider, model)
  906. return {"ok": True, "provider": provider, "model": model}
  907. @router.post("/api/profiles/{name}/describe-auto")
  908. async def describe_profile_auto_endpoint(name: str, body: ProfileDescribeAuto):
  909. """Auto-generate a profile's description via the auxiliary LLM (mirrors ``hermes profile
  910. describe <name> --auto``). A failed generation is ``ok: false`` with a reason rather than
  911. an HTTP error so the UI can surface it inline and let the operator retry."""
  912. # Resolution stays on the loop: it owns the 400/404 mapping the 500 fallback would flatten.
  913. _resolve_profile_dir(name)
  914. def _run():
  915. from hermes_cli import profile_describer
  916. return profile_describer.describe_profile(name, overwrite=bool(body.overwrite))
  917. with _profile_errors("POST /api/profiles/%s/describe-auto failed", name,
  918. not_found=(), bad_request=()):
  919. # A synchronous LLM round-trip with a 60 s ceiling; on the loop it stalls everything.
  920. outcome = await run_in_threadpool(_run)
  921. # description_auto mirrors ok: a failed sweep leaves any existing description untouched.
  922. return {"ok": bool(outcome.ok), "reason": outcome.reason, "description": outcome.description,
  923. "description_auto": bool(outcome.ok)}
  924. # ── Export / Import ── wraps hermes_cli.profiles.export_profile / import_profile. Paths are
  925. # exchanged, not bytes — the desktop backends share the filesystem with the native dialogs.
  926. def _read_desktop_overlay(profile_dir: Path) -> Any:
  927. """The desktop appearance overlay bundled with an imported profile
  928. (``desktop.json`` at the profile root); raises when unreadable."""
  929. return json.loads((profile_dir / "desktop.json").read_text(encoding="utf-8-sig"))
  930. @router.post("/api/profiles/{name}/export")
  931. async def export_profile_endpoint(name: str, body: ProfileExport):
  932. from hermes_cli import profiles as profiles_mod
  933. output = (body.output or "").strip()
  934. if not output:
  935. try:
  936. output = str(profiles_mod.get_profile_export_path(name))
  937. except ValueError as exc:
  938. raise HTTPException(status_code=400, detail=str(exc))
  939. except OSError as exc:
  940. raise HTTPException(status_code=500, detail=f"Could not create export directory: {exc}")
  941. with _profile_errors("POST /api/profiles/%s/export failed", name):
  942. result = await run_in_threadpool(
  943. profiles_mod.export_profile, name, output, extra_files=body.extra_files or None)
  944. return {"ok": True, "archive": str(result)}
  945. @router.post("/api/profiles/import")
  946. async def import_profile_endpoint(body: ProfileImport):
  947. from hermes_cli import profiles as profiles_mod
  948. archive = (body.archive or "").strip()
  949. if not archive:
  950. raise HTTPException(status_code=400, detail="archive path is required")
  951. with _profile_errors("POST /api/profiles/import failed",
  952. bad_request=(ValueError, FileExistsError)):
  953. profile_dir = await run_in_threadpool(
  954. profiles_mod.import_profile, archive, name=(body.name or "").strip() or None)
  955. imported = profile_dir.name
  956. # Match the CLI import flow: create the wrapper alias when it's safe.
  957. _best_effort("Creating wrapper for imported profile %s failed", imported,
  958. fn=lambda: (profiles_mod.check_alias_collision(imported)
  959. or profiles_mod.create_wrapper_script(imported)))
  960. # Bundled desktop appearance overlay, so the desktop needn't make another round-trip.
  961. desktop_overlay = None
  962. overlay_path = profile_dir / "desktop.json"
  963. if overlay_path.is_file():
  964. desktop_overlay = _best_effort(
  965. "Reading desktop.json from imported profile %s failed", imported,
  966. fn=lambda: _read_desktop_overlay(profile_dir))
  967. return {"ok": True, "name": imported, "path": str(profile_dir), "desktop": desktop_overlay}
  968. @router.get("/api/profiles/{name}/desktop-overlay")
  969. async def get_profile_desktop_overlay(name: str):
  970. """The desktop appearance/interface overlay bundled with an imported profile
  971. (``desktop.json`` at the profile root), or ``exists: false``."""
  972. profile_dir = _resolve_profile_dir(name)
  973. def _run():
  974. # Probe and read in one hop; _MISSING because desktop.json may hold ``null``.
  975. if not (profile_dir / "desktop.json").is_file():
  976. return _MISSING
  977. return _read_desktop_overlay(profile_dir)
  978. overlay = await _read_off_loop(_run, "desktop.json", Exception)
  979. if overlay is _MISSING:
  980. return {"exists": False, "desktop": None}
  981. return {"exists": True, "desktop": overlay}