title_generator.py 41 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800
  1. """Auto-generate short session titles from the user's opening message.
  2. Two stages, both off the critical path: an **instant** deterministic title (written before the model
  3. is called, cannot fail), then an **upgrade** from one small-model call (cheap tier, thinking off,
  4. JSON-constrained). Storage enforces provenance ``derived < llm < user``: stage 2 only replaces stage 1
  5. and neither replaces a name the user typed."""
  6. import json
  7. import logging
  8. import os
  9. import re
  10. import threading
  11. import time
  12. import weakref
  13. from contextlib import suppress
  14. from typing import Any, Callable, Optional
  15. from agent.auxiliary_client import call_llm
  16. from agent.context_compressor import LEGACY_SUMMARY_PREFIX
  17. from agent.delegation_context import is_dispatcher_owned_worker_context
  18. from agent.message_content import flatten_message_text
  19. logger = logging.getLogger(__name__)
  20. # In-flight stage-2 upgrade threads. They bill their aux usage to the session from a daemon thread,
  21. # so a process that reads the ledger right before exit (``-z --usage-file``) must be able to join
  22. # them (bounded) instead of racing the write (#112848).
  23. _UPGRADE_THREADS: weakref.WeakSet[threading.Thread] = weakref.WeakSet()
  24. def wait_for_title_upgrades(timeout: float = 10.0) -> None:
  25. """Bounded join of the auto-title threads still running; never raises."""
  26. deadline = time.monotonic() + timeout
  27. for thread in list(_UPGRADE_THREADS):
  28. thread.join(max(0.0, deadline - time.monotonic()))
  29. # (task_name, exception) -> None; surfaces auxiliary failures so silent drops don't pile up as NULL titles.
  30. FailureCallback = Callable[[str, BaseException], None]
  31. # (title, source) -> None; source is the persisted provenance (``derived`` / ``llm``). Consumers paying a
  32. # rate-limited remote rename per title (Discord thread, Telegram topic) should act on ``llm`` only.
  33. TitleCallback = Callable[[str, str], None]
  34. # () -> bool, called right before the LLM request; False skips (e.g. the user switched models and
  35. # the request would reload one the runtime already evicted).
  36. # Validation callback: () -> bool. See #19027.
  37. RuntimeValidator = Callable[[], bool]
  38. # Text budget handed to the model (Claude Code / OpenClaw converged on 1000).
  39. MAX_TITLE_INPUT_CHARS = 1000
  40. _PASTE_PREVIEW_LABEL = "\n\nPasted content:\n"
  41. _ATTACHMENT_REF_RE = re.compile(r"@(?:file|folder):\S+")
  42. # Footers the @-reference expander appends below the typed text (agent/context_references.py).
  43. _CONTEXT_FOOTER_RE = re.compile(r"\n+--- (?:Context Warnings|Attached Context) ---\n.*", re.DOTALL)
  44. # Cap on the instant derived title; a raw fragment reads worse the longer it runs.
  45. MAX_DERIVED_TITLE_CHARS = 48
  46. # Answer-shaped guard: a tiny model sometimes answers instead of titling; longer is rejected, not truncated.
  47. # Upper bound on accepted title word count. Titling is a 3-7 word task; a small tiny-model sometimes ignores
  48. # the task and answers the user's message instead — that answer must never become the session title (see the
  49. # answer-shaped output guard in generate_title; port of can1357/oh-my-pi#7306). 12 leaves headroom for
  50. # legitimate wordy titles while excluding full-sentence answers.
  51. _MAX_TITLE_WORDS = 12
  52. # Output budget for the title call: room for a fenced/prefixed JSON reply and for a reasoning model that
  53. # thinks despite the thinking-disabled request, without letting a runaway reply burn minutes.
  54. TITLE_MAX_TOKENS = 512
  55. # The example titles shown to the model in the prompt, and the echo-guard
  56. # set: when the opening message carries little topical signal, a small model
  57. # sometimes takes the cheapest schema-valid answer and parrots one of these
  58. # back verbatim — most visibly "Fix login button on mobile" naming sessions
  59. # that have nothing to do with a login button. The prompt's example lines are
  60. # rendered from these constants so the guard set and the prompt cannot drift
  61. # apart. Port of QwenLM/qwen-code#9709.
  62. _PROMPT_GOOD_EXAMPLES = (
  63. "Fix login button on mobile",
  64. "Postgres connection pool exhaustion",
  65. "Friendly greeting",
  66. )
  67. _PROMPT_VAGUE_EXAMPLE = "Code changes"
  68. # "Friendly greeting" is deliberately NOT in the reject set: the prompt
  69. # instructs the model to produce it for bare greetings, so it is a legitimate
  70. # output, not an echo failure. The too-vague example is rejected too — a model
  71. # repeating the counter-example says nothing about the session, and the
  72. # derived title the guard falls back to is strictly more informative.
  73. _EXAMPLE_ECHO_REJECT = frozenset(
  74. t.lower() for t in _PROMPT_GOOD_EXAMPLES if t != "Friendly greeting"
  75. ) | {_PROMPT_VAGUE_EXAMPLE.lower()}
  76. # "Friendly greeting" is what the prompt asks for when the opener has no topic yet, so
  77. # it is the one model title that must NOT settle the session: it is persisted at
  78. # ``derived`` authority (a placeholder, like the instant title) and the next substantive
  79. # turn upgrades it. Kept as a prompt example on purpose — a predictable placeholder is
  80. # detectable, an improvised one ("Casual check-in chat") would lock the title as ``llm``.
  81. _PROVISIONAL_GREETING_TITLE = "friendly greeting"
  82. _TITLE_PROMPT_TEMPLATE = (
  83. "You name chat sessions. Given the user's opening message, write a title "
  84. "that lets them find this conversation again in a list.\n\n"
  85. "Rules:\n"
  86. "- 3 to 7 words, sentence case (capitalize only the first word and proper nouns).\n"
  87. "- Name what the user wants DONE, not that they asked a question.\n"
  88. "- Keep technical terms, filenames, numbers, and error codes exact.\n"
  89. "- Drop filler words: the, this, my, a, an.\n"
  90. "- No trailing punctuation, no quotes, no tool names, no 'Title:' prefix.\n"
  91. "- Never answer the message. Name it.\n"
  92. "- Always produce something, even for a bare greeting.\n"
  93. "__LANGUAGE_RULE__\n"
  94. + "".join(f'Good: {{"title": "{t}"}}\n' for t in _PROMPT_GOOD_EXAMPLES)
  95. + f'Too vague: {{"title": "{_PROMPT_VAGUE_EXAMPLE}"}}\n'
  96. 'Too long: {"title": "Investigate and fix the issue where the login button '
  97. 'does not respond on mobile devices"}\n\n'
  98. 'Reply with JSON only: {"title": "..."}'
  99. )
  100. _LANGUAGE_RULE_MATCH_USER = "- Write the title in the same language as the user's message."
  101. _LANGUAGE_RULE_PINNED = "- Write the title in {language}."
  102. # Constrains the response to a single title field ("model answered instead of titling" failure class).
  103. _TITLE_RESPONSE_FORMAT = {
  104. "type": "json_schema",
  105. "json_schema": {"name": "session_title", "strict": True, "schema": {
  106. "type": "object", "properties": {"title": {"type": "string"}}, "required": ["title"], "additionalProperties": False}},
  107. }
  108. # Control-tag wrappers around machine-authored content inside a nominal "user" message (Codex CLI's
  109. # RECOGNIZED_CONTROL_WRAPPERS): stripped, titling continues on what remains.
  110. _CONTROL_WRAPPERS = tuple(
  111. (f"<{tag}>", f"</{tag}>")
  112. for tag in ("command-message", "command-name", "command-args", "local-command-caveat", "local-command-stderr",
  113. "local-command-stdout", "task-notification", "system-reminder", "ide_opened_file", "ide_selection")
  114. )
  115. # Hermes' own machine-authored openers: a compaction handoff or resumed session must not be titled after them.
  116. _MACHINE_PREFIXES = (
  117. "[CONTEXT COMPACTION", LEGACY_SUMMARY_PREFIX, "[Runtime note:", "[System note:", "[SYSTEM]",
  118. # tui_gateway.server._MODEL_SWITCH_MARKER_PREFIX (keep in sync); persisted as role="user" because
  119. # strict providers reject a non-first system message.
  120. # Model-switch marker from tui_gateway.server._append_model_switch_marker. It is persisted with
  121. # role="user" (strict OpenAI-compatible providers reject a system message that is not first — #48338),
  122. # so without this entry it looks like a real opening turn: switching models before the first real
  123. # message titled the session "[System: The active model for this chat has…" instead of the user's actual
  124. # question.
  125. "[System: The active model for this chat has changed to ",
  126. )
  127. def _title_config() -> dict:
  128. """``auxiliary.title_generation`` (lazy read-only import: no hermes_cli cycle, no migration writes)."""
  129. from hermes_cli.config import load_config_readonly
  130. return ((load_config_readonly() or {}).get("auxiliary") or {}).get("title_generation") or {}
  131. def _title_language() -> str:
  132. """Configured title language, or "" to match the user."""
  133. try:
  134. return str(_title_config().get("language", "")).strip()
  135. except Exception:
  136. return ""
  137. def _auto_title_enabled() -> bool:
  138. try:
  139. from utils import is_truthy_value
  140. return is_truthy_value(_title_config().get("enabled"), default=True)
  141. except Exception:
  142. logger.debug("Failed to read title_generation.enabled", exc_info=True)
  143. return True
  144. def _model_title_upgrade_enabled() -> bool:
  145. """Distinct from ``enabled``: keep the instant derived title, skip the background model call (#85194)."""
  146. try:
  147. from utils import is_truthy_value
  148. return is_truthy_value(_title_config().get("model_upgrade_enabled"), default=True)
  149. except Exception:
  150. logger.debug("Failed to read title_generation.model_upgrade_enabled", exc_info=True)
  151. return True
  152. def title_upgrade_must_wait_for_turn(main_runtime: Optional[dict]) -> bool:
  153. """True when the model title call would hit the SAME self-hosted endpoint as the turn's own request.
  154. A self-hosted main route (``_is_self_hosted_provider``: custom, lmstudio, local and their aliases)
  155. whose ``auxiliary.title_generation`` is not pinned elsewhere (a pin naming the same custom route —
  156. ``custom:<name>``, bare ``<name>`` or its display name — is not "elsewhere", #120558)
  157. shares one local server between the streaming main request and the
  158. concurrent ``response_format: json_schema`` title request. Single-slot servers then serve the
  159. title grammar/completion into the main turn: the user's reply arrives as ``{"title": ...}``, is
  160. persisted as a genuine assistant row and replayed, and the model adopts the format (#117296).
  161. Running the title call after the turn settles keeps the two requests off the wire at once.
  162. Hosted providers multiplex requests independently and keep the turn-start timing.
  163. """
  164. provider = str((main_runtime or {}).get("provider") or "").strip().lower()
  165. if not _is_self_hosted_provider(provider):
  166. return False
  167. try:
  168. cfg = _title_config()
  169. pinned_provider = str(cfg.get("provider") or "").strip().lower()
  170. main_base_url = str((main_runtime or {}).get("base_url") or "").strip().rstrip("/")
  171. if pinned_provider not in ("", "auto") and not _title_pin_may_share_endpoint(
  172. pinned_provider, provider, main_base_url):
  173. return False
  174. except Exception:
  175. return True
  176. pinned_base_url = str(cfg.get("base_url") or "").strip().rstrip("/")
  177. return not pinned_base_url or pinned_base_url == main_base_url
  178. def _is_self_hosted_provider(provider: str) -> bool:
  179. """``custom``, a named ``custom:<name>`` route, LM Studio or ``local`` (vllm/llama.cpp): one local server per route.
  180. Normalised here so the main route and the title pin resolve aliases (``ollama``, ``lm-studio``…) the same way.
  181. """
  182. from hermes_cli.providers import normalize_provider
  183. provider = normalize_provider(provider)
  184. return provider in ("custom", "lmstudio", "local") or provider.startswith("custom:")
  185. def _title_pin_may_share_endpoint(pinned_provider: str, main_provider: str, main_base_url: str) -> bool:
  186. """A title pin that can land on the turn's own self-hosted server (only its ``base_url`` can prove otherwise).
  187. Hosted pins (``openrouter``…) multiplex and never share the slot. A pin to ``custom``/``lmstudio``/``local``/any
  188. ``custom:<name>`` is assumed to share until the caller compares ``base_url``, and a bare ``<name>`` /
  189. display-name pin is the same endpoint when it aliases the main ``custom:<name>`` route
  190. (``hermes_cli.providers.custom_provider_aliases`` — the resolver's own identity set) or resolves to a
  191. configured custom entry serving ``main_base_url`` (a keyed ``providers:`` entry's display name does not
  192. alias its ``custom:<key>`` id).
  193. """
  194. from hermes_cli.config import get_compatible_custom_providers, load_config_readonly
  195. from hermes_cli.providers import custom_provider_aliases, resolve_custom_provider
  196. if _is_self_hosted_provider(pinned_provider):
  197. return True
  198. if custom_provider_aliases(pinned_provider) & custom_provider_aliases(main_provider):
  199. return True
  200. pdef = resolve_custom_provider(pinned_provider, get_compatible_custom_providers(load_config_readonly()))
  201. return bool(pdef and main_base_url and pdef.base_url.strip().rstrip("/") == main_base_url)
  202. def start_title_upgrade(upgrade: Optional[threading.Thread]) -> None:
  203. """Start a (deferred) title upgrade thread; joinable via ``wait_for_title_upgrades`` only once started."""
  204. if upgrade is None or upgrade.ident is not None:
  205. return
  206. _UPGRADE_THREADS.add(upgrade)
  207. upgrade.start()
  208. def strip_control_wrappers(text: str) -> str:
  209. """Remove leading control wrappers (nested too) so a slash-command turn reduces to the prose the user typed."""
  210. current = (text or "").strip()
  211. for _ in range(len(_CONTROL_WRAPPERS) * 2): # bounded: each pass must remove a wrapper or we stop
  212. stripped = _strip_one_wrapper(current)
  213. if stripped == current:
  214. break
  215. current = stripped
  216. return current
  217. def _strip_one_wrapper(text: str) -> str:
  218. lowered = text.lower()
  219. for open_tag, close_tag in _CONTROL_WRAPPERS:
  220. if not lowered.startswith(open_tag):
  221. continue
  222. end = lowered.find(close_tag)
  223. if end == -1: # unterminated wrapper: drop the opening tag and keep the body
  224. return text[len(open_tag):].strip()
  225. # Prefer trailing prose; otherwise the wrapper body is all we have.
  226. return (text[end + len(close_tag):].strip() or text[len(open_tag):end].strip()).strip()
  227. return text
  228. # Matches an ``@file:``/``@folder:`` context reference the way the canonical
  229. # ``agent.context_references`` reference pattern does: an unquoted ``\S+``
  230. # value, or a backtick/double/single-quoted value (a space-bearing path is
  231. # written backtick-quoted). Kept local so the titler doesn't import the
  232. # context-reference machinery (circularity / startup cost) just to detect the
  233. # attachment-only shape (#92068).
  234. _QUOTED = r"(?:`[^`\n]+`|\"[^\"\n]+\"|'[^'\n]+')"
  235. # Mirrors the canonical agent.context_references value shape: a quoted
  236. # (space-bearing) path may carry a ``:start[-end]`` line-range suffix, and a
  237. # bare path swallows its own range via ``\S+``.
  238. _CONTEXT_REFERENCE_TOKEN_RE = re.compile(
  239. rf"(?<![\w/])@(?:file|folder):(?:{_QUOTED}(?::\d+(?:-\d+)?)?|\S+)"
  240. )
  241. def _attachment_only_opener(message: str) -> bool:
  242. """True when nothing but context references (and their expansion footer)
  243. remain — a manual-attach opener with no typed request and no paste
  244. preview has no topic of its own to title (#92068)."""
  245. residual = _CONTEXT_REFERENCE_TOKEN_RE.sub("", _CONTEXT_FOOTER_RE.sub("", message))
  246. return not residual.strip()
  247. def _summarize_user_message(user_message: str) -> str:
  248. """Text worth titling: describe a ``/skill`` invocation (it embeds the whole skill body), then strip wrappers."""
  249. if not user_message:
  250. return ""
  251. described = None
  252. try:
  253. from agent.skill_commands import describe_skill_invocation
  254. described = describe_skill_invocation(user_message)
  255. except Exception:
  256. logger.debug("Skill-scaffolding summary failed; titling raw", exc_info=True)
  257. return strip_control_wrappers(user_message if described is None else described)
  258. def build_title_input(user_message: str, title_preview: str | None = None) -> str:
  259. """Combine the opening text with a bounded Desktop-generated paste preview.
  260. ``title_preview`` is deliberately an explicit, auxiliary-only value: ordinary
  261. attachments never populate it, and it is never returned to the main turn.
  262. Keep enough of a separately typed request to preserve a useful instruction,
  263. then spend the remaining title budget on the beginning of the pasted topic.
  264. """
  265. message = _summarize_user_message(user_message)
  266. preview = title_preview.strip() if isinstance(title_preview, str) else ""
  267. if not preview:
  268. return message[:MAX_TITLE_INPUT_CHARS]
  269. # The titler sees the message AFTER @-reference expansion, so the generated ref drags a
  270. # warnings/attached-context footer along; the preview already carries the topic, so drop it.
  271. message = _CONTEXT_FOOTER_RE.sub("", message).strip()
  272. # A paste-only opener is just the generated `@file:` ref: the preview IS the topic, so it
  273. # leads (derive_title takes the first line, and a file path is not a title).
  274. if not _ATTACHMENT_REF_RE.sub("", message).strip():
  275. return preview[:MAX_TITLE_INPUT_CHARS]
  276. message_budget = min(len(message), MAX_TITLE_INPUT_CHARS // 2)
  277. preview_budget = MAX_TITLE_INPUT_CHARS - message_budget - len(_PASTE_PREVIEW_LABEL)
  278. if preview_budget <= 0:
  279. return message[:MAX_TITLE_INPUT_CHARS]
  280. return message[:message_budget] + _PASTE_PREVIEW_LABEL + preview[:preview_budget]
  281. def is_titleable_user_message(user_message: str) -> bool:
  282. """False for machine-authored openers and turns that reduce to nothing once scaffolding is stripped."""
  283. return (isinstance(user_message, str) and bool(user_message.strip()) and not user_message.lstrip().startswith(_MACHINE_PREFIXES)
  284. and bool(_summarize_user_message(user_message).strip())
  285. # An attachment-only opener (manual attach, no paste preview) is a
  286. # file drop, not a request: deriving its "title" from the message
  287. # names the session after the truncated file path (#92068).
  288. and not _attachment_only_opener(user_message))
  289. def derive_title(user_message: str, title_preview: str | None = None) -> Optional[str]:
  290. """Instant title: first meaningful line trimmed to a word boundary. No model, never fails."""
  291. # Attachment-only opener, no paste preview: a file drop has no topic —
  292. # refuse rather than name the session after the truncated path (#92068).
  293. if not title_preview and _attachment_only_opener(user_message):
  294. return None
  295. line = " ".join(_first_line(build_title_input(user_message, title_preview)).split())
  296. if len(line) > MAX_DERIVED_TITLE_CHARS:
  297. cut = line[:MAX_DERIVED_TITLE_CHARS]
  298. space = cut.rfind(" ")
  299. line = (cut[:space] if space > MAX_DERIVED_TITLE_CHARS // 2 else cut).rstrip(" ,.;:—-") + "…"
  300. return line or None
  301. def _strip_title_prefix(text: str) -> str:
  302. return text[6:].strip() if text.lower().startswith("title:") else text
  303. def _first_line(text: str) -> str:
  304. return next((ln.strip() for ln in text.splitlines() if ln.strip()), "")
  305. def _extract_json_title(raw: str) -> Optional[str]:
  306. """Title from a ``{"title": ...}`` payload — strict parse, then a loose ``"title": "..."`` scan; None when absent."""
  307. try:
  308. parsed = json.loads(raw)
  309. if isinstance(parsed, dict) and isinstance(parsed.get("title"), str):
  310. return parsed["title"].strip()
  311. except (ValueError, TypeError):
  312. pass
  313. match = re.search(r'"title\"\s*:\s*"((?:[^"\\]|\\.)*)"', raw)
  314. if match:
  315. with suppress(ValueError):
  316. return json.loads(f'"{match.group(1)}"').strip()
  317. return match.group(1).strip()
  318. return None
  319. def _is_truncated_structured_output(raw: str) -> bool:
  320. """Structured output the token cap cut before its closing quote/brace/fence (``{"title``, a bare fence opener).
  321. Checked only after the JSON paths failed, and on structure alone (a JSON-shaped opener, a fence
  322. opener that is never closed) so quoted, *emphasized* or ``[WIP]``-prefixed prose titles are
  323. untouched (#83903)."""
  324. return raw.startswith(('{"', '["', "[{")) or (raw.startswith("```") and raw.count("```") % 2 == 1)
  325. def _extract_title_text(content: str) -> str:
  326. """Strict JSON, then a loose JSON scan, then first-line prose (a provider ignoring ``response_format`` still titles).
  327. A truncated structured payload is dropped rather than handed to the prose fallback: the fragment
  328. would otherwise be persisted as the session title."""
  329. if not content:
  330. return ""
  331. raw = content.strip()
  332. fenced = re.match(r"^```(?:json)?\s*(.*?)\s*```$", raw, re.DOTALL)
  333. if fenced:
  334. raw = fenced.group(1).strip()
  335. title = _extract_json_title(raw)
  336. if title is not None:
  337. return title
  338. if _is_truncated_structured_output(raw):
  339. return ""
  340. # Prose fallback: scrub <think> blocks so reasoning can't leak into a title.
  341. try:
  342. from agent.agent_runtime_helpers import strip_think_blocks
  343. raw = strip_think_blocks(None, raw).strip()
  344. except Exception:
  345. logger.debug("strip_think_blocks unavailable for title output", exc_info=True)
  346. return _strip_title_prefix(_first_line(raw)).strip("\"'").strip()
  347. def _title_from_reasoning(message: Any) -> str:
  348. """The ``{"title": ...}`` payload when a reasoning model put it in ``reasoning_content`` / ``reasoning``
  349. and left ``content`` empty (glm-5 / minimax under ``json_schema``, #82291). Structured extraction only:
  350. chain-of-thought prose is never a title, so there is no prose fallback here."""
  351. for field in ("reasoning_content", "reasoning"):
  352. text = getattr(message, field, None)
  353. if isinstance(text, str) and text.strip():
  354. title = _extract_json_title(text.strip())
  355. if title:
  356. return title
  357. return ""
  358. def _clean_title(text: str) -> Optional[str]:
  359. """Normalize a model-produced title, or None when nothing usable remains."""
  360. title = _strip_title_prefix(" ".join((text or "").split()).strip("\"'").strip()).rstrip(".!,;:")
  361. if len(title) > 80:
  362. title = title[:77].rstrip() + "..."
  363. return title or None
  364. def _safe_callback(callback: Optional[Callable], args: tuple, log_fmt: str, label: str) -> None:
  365. """Invoke an optional consumer callback, never raising."""
  366. try:
  367. if callback is not None:
  368. callback(*args)
  369. except Exception:
  370. logger.debug(log_fmt, label, exc_info=True)
  371. def _report_failure(failure_callback: Optional[FailureCallback], exc: BaseException, label: str) -> None:
  372. _safe_callback(failure_callback, ("title generation", exc), "%s failure_callback raised", label)
  373. def _notify_title(title_callback: Optional[TitleCallback], title: str, source: str, label: str) -> None:
  374. _safe_callback(title_callback, (title, source), "%s callback failed", label)
  375. def _is_provisional_greeting_title(title: str) -> bool:
  376. """The prompt's greeting placeholder (also "Friendly greeting in chat" and quoted/bracketed variants)."""
  377. normalized = re.sub(r"^[\W_]+|[\W_]+$", "", title.strip(), flags=re.UNICODE).lower()
  378. return normalized in (_PROVISIONAL_GREETING_TITLE, _PROVISIONAL_GREETING_TITLE + " in chat")
  379. def _is_prompt_example_echo(title: str) -> bool:
  380. """Return True when *title* is one of the prompt's own example titles.
  381. Comparison is case-insensitive after stripping any leading/trailing run of
  382. non-letter/non-digit characters, so bracket/quote wrappers cannot bypass
  383. the guard — while ``_clean_title`` keeps brackets for real titles like
  384. "(WIP) Fix build". Unicode-aware so full-width wrappers are covered too.
  385. """
  386. normalized = re.sub(r"^[\W_]+|[\W_]+$", "", title.strip(), flags=re.UNICODE).lower()
  387. return normalized in _EXAMPLE_ECHO_REJECT
  388. def generate_title(
  389. user_message: str,
  390. timeout: Optional[float] = None,
  391. failure_callback: Optional[FailureCallback] = None,
  392. main_runtime: dict | None = None,
  393. runtime_validator: Optional[RuntimeValidator] = None,
  394. title_preview: str | None = None,
  395. ) -> Optional[str]:
  396. """Title from the opening message alone (waiting for the assistant made this slow and bought
  397. nothing). ``runtime_validator`` runs right before the request; False skips silently.
  398. If it returns False (e.g. the user's model was switched since the background thread captured its runtime
  399. snapshot), the call is skipped silently — no request is sent, so a stale title request can't reload a
  400. model the runtime already unloaded (#19027).
  401. """
  402. if not _auto_title_enabled():
  403. logger.debug("Auto-title skipped: auxiliary.title_generation.enabled=false")
  404. return None
  405. try:
  406. if runtime_validator is not None and not runtime_validator():
  407. logger.debug("Title generation skipped: runtime validator returned False")
  408. return None
  409. except Exception: # fail open: a broken validator must not disable titling
  410. logger.debug("Title runtime validator raised; proceeding", exc_info=True)
  411. user_snippet = build_title_input(user_message, title_preview)
  412. if not user_snippet.strip() or (
  413. # An attachment-only opener (manual attach, no paste preview) reaches
  414. # here via auto_title_session, which lacks the instant-title guard:
  415. # refuse it rather than titling the session after the file path (#92068).
  416. not title_preview and _attachment_only_opener(user_snippet)
  417. ):
  418. return None
  419. language = _title_language()
  420. # str.replace, not str.format: the prompt embeds literal JSON braces.
  421. prompt = _TITLE_PROMPT_TEMPLATE.replace(
  422. "__LANGUAGE_RULE__", _LANGUAGE_RULE_PINNED.format(language=language) if language else _LANGUAGE_RULE_MATCH_USER,
  423. )
  424. try:
  425. # Use the provider's default temperature instead of forcing 0.3.
  426. # Some models (e.g. GPT-5.6) only accept their server-side default
  427. # and reject explicit temperature values, causing the daemon title
  428. # thread to fail with "Unsupported value: 'temperature'".
  429. # See: #72351, #51083, #51157
  430. response = call_llm(
  431. task="title_generation",
  432. messages=[{"role": "system", "content": prompt}, {"role": "user", "content": user_snippet}],
  433. # A title is a handful of tokens, but 64 was cut mid-JSON by fenced/prefixed replies and by
  434. # reasoning models whose thinking survives the disable below (#83903, #82291). A model that
  435. # honours the JSON contract stops after ~15 tokens regardless, so the ceiling only costs on
  436. # replies that would have been garbage anyway. temperature=None: omitted from the wire so
  437. # default-only reasoning models accept the first request (#72351).
  438. max_tokens=TITLE_MAX_TOKENS, temperature=None, timeout=timeout, main_runtime=main_runtime,
  439. extra_body={"response_format": _TITLE_RESPONSE_FORMAT},
  440. # The module contract above promises thinking-disabled operation,
  441. # but nothing enforced it: with the aux default reasoning_effort
  442. # "" (provider default), Gemini enables internal thinking and
  443. # bills thought tokens against max_tokens=64 — the JSON payload
  444. # never lands, and the prose fallback stores the opening fence
  445. # ("```json") as the session title (#91927).
  446. reasoning_config={"enabled": False},
  447. )
  448. message = response.choices[0].message
  449. title = _clean_title(_extract_title_text(message.content or "") or _title_from_reasoning(message))
  450. # Answer-shaped output guard: titling is a 3-7 word task, so a title with many words is a model that
  451. # ignored the task and answered the user's message instead ("I don't have context on X — that's not
  452. # something I recognize..."). Truncating would store half an assistant blob as the session title,
  453. # which is still an assistant blob — reject instead so the caller retries on the next exchange
  454. # (maybe_auto_title retries a placeholder title through the third exchange). Port of can1357/oh-my-pi#7306.
  455. if title is not None and len(title.split()) > _MAX_TITLE_WORDS:
  456. # Answer-shaped output: reject (not truncate) so the caller retries next exchange.
  457. logger.debug("Rejecting answer-shaped title output (%d words > %d)", len(title.split()), _MAX_TITLE_WORDS)
  458. return None
  459. # Example-echo guard: a title that parrots one of the prompt's own
  460. # examples back verbatim says nothing about the session — reject it so
  461. # the instant derived title (a slice of the user's actual words)
  462. # survives instead. Exact match after wrapper-stripping, deliberately
  463. # not fuzzy, so a genuinely topical title that merely resembles an
  464. # example still passes. Wrappers are stripped for the comparison only
  465. # ("(Fix login button on mobile)" is the same canned echo as the bare
  466. # example). Port of QwenLM/qwen-code#9709.
  467. if title is not None and _is_prompt_example_echo(title):
  468. logger.debug("Rejecting prompt-example echo title: %r", title)
  469. return None
  470. return title
  471. except Exception as e:
  472. # WARNING so it shows in agent.log without debug mode; stack at debug.
  473. logger.warning("Title generation failed: %s", e)
  474. logger.debug("Title generation traceback", exc_info=True)
  475. _report_failure(failure_callback, e, "Title generation")
  476. return None
  477. def _has_upgraded_title(session_db, session_id: str) -> bool:
  478. """True when the session already carries an ``llm``/``user`` title (or the check fails)."""
  479. try:
  480. source_fn = getattr(session_db, "get_session_title_source", None)
  481. if source_fn is not None:
  482. return source_fn(session_id) not in (None, "derived")
  483. return bool(session_db.get_session_title(session_id))
  484. except Exception:
  485. return True
  486. def _persist_session_title(session_db, session_id, title, *, source, dedupe=True):
  487. """Persist at *source* authority via ``set_auto_title`` (precedence check + write in one
  488. transaction, so a manual ``/title`` is never overwritten); None when a higher authority held the row.
  489. ``ValueError`` = unique-title index collision → append ``#N`` via ``get_next_title_in_lineage``;
  490. ``dedupe=False`` re-raises instead (the derived title is on the critical path, collides constantly
  491. on "hi", and the model replaces it a second later anyway).
  492. ``ValueError`` means the name is taken by an unrelated session (the unique-title index); rather than
  493. leave the session untitled (#50537), append a ``#N`` suffix via ``get_next_title_in_lineage``.
  494. """
  495. auto_fn = getattr(session_db, "set_auto_title", None)
  496. def _set(candidate):
  497. if auto_fn is not None:
  498. if auto_fn(session_id, candidate, source=source):
  499. return candidate
  500. logger.debug("Skipping %s title: a higher-authority title already holds session %s", source, session_id)
  501. return None
  502. legacy_fn = getattr(session_db, "set_auto_title_if_empty", None) # older store without provenance
  503. if legacy_fn is not None:
  504. return candidate if legacy_fn(session_id, candidate) else None
  505. if session_db.set_session_title(session_id, candidate) is False:
  506. raise RuntimeError(f"session {session_id} not found when storing title")
  507. return candidate
  508. try:
  509. return _set(title)
  510. except ValueError:
  511. next_title_fn = getattr(session_db, "get_next_title_in_lineage", None)
  512. deduped = next_title_fn(title) if dedupe and next_title_fn is not None else None
  513. if not deduped or deduped == title:
  514. raise
  515. return _set(deduped)
  516. def apply_subagent_title(session_db, session_id: str, goal: str) -> Optional[str]:
  517. """Title a delegate run ``Subagent: <goal's first line>`` at ``derived`` authority. No model call:
  518. runs fan out in bulk, and the prefix alone is what tells them apart from conversations wherever
  519. ``sessions.show_subagents`` lists them (#97202). Collisions get ``#N``. Never raises."""
  520. try:
  521. derived = derive_title(goal) if is_titleable_user_message(goal) else None
  522. return _persist_session_title(session_db, session_id, f"Subagent: {derived}", source="derived") if derived else None
  523. except Exception:
  524. logger.debug("Subagent title failed for %s", session_id, exc_info=True)
  525. return None
  526. def apply_instant_title(
  527. session_db, session_id: str, user_message: str, title_callback: Optional[TitleCallback] = None,
  528. title_preview: str | None = None,
  529. ) -> Optional[str]:
  530. """Write the derived title inline. Returns it, or None (no usable text, or a ``derived``+ title exists). Never raises.
  531. ``title_preview`` must reach this stage too: the model upgrade's own ``derive_title`` fallback writes
  532. ``derived`` provenance, which never replaces the ``derived`` title written here."""
  533. if not session_db or not session_id:
  534. return None
  535. try:
  536. title = derive_title(user_message, title_preview) if is_titleable_user_message(user_message) else None
  537. persisted = _persist_session_title(session_db, session_id, title, source="derived", dedupe=False) if title else None
  538. if persisted:
  539. _notify_title(title_callback, persisted, "derived", "Instant-title")
  540. return persisted
  541. except Exception:
  542. logger.debug("Instant title failed", exc_info=True)
  543. return None
  544. def auto_title_session(
  545. session_db,
  546. session_id: str,
  547. user_message: str,
  548. failure_callback: Optional[FailureCallback] = None,
  549. main_runtime: dict | None = None,
  550. title_callback: Optional[TitleCallback] = None,
  551. runtime_validator: Optional[RuntimeValidator] = None,
  552. title_preview: str | None = None,
  553. ) -> None:
  554. """Generate and store the model title (daemon-thread target); skips sessions already carrying an
  555. ``llm``/``user`` title (a ``derived`` one is expected — upgrading it is the point). Never lets an
  556. exception escape (the threading excepthook would spray a traceback into the terminal); the canonical
  557. trigger is the post-``hermes update`` window where lazy imports read NEW source against OLD modules."""
  558. try:
  559. if not session_db or not session_id or _has_upgraded_title(session_db, session_id):
  560. return
  561. # This thread starts AFTER the turn's ambient context was reset; republish it so the call carries
  562. # the same Portal ``conversation=`` tag (root-of-lineage) and bills usage to this session.
  563. from agent.aux_accounting import set_accounting_context
  564. from agent.portal_tags import set_conversation_context
  565. conversation_id = session_id
  566. with suppress(Exception):
  567. conversation_id = session_db.get_conversation_root(session_id) or session_id
  568. set_conversation_context(conversation_id)
  569. # Same for the accounting context, so the title call's token usage is recorded against this session
  570. # (task='title_generation', #23270).
  571. set_accounting_context(session_db, session_id)
  572. title, source = generate_title(
  573. user_message, failure_callback=failure_callback, main_runtime=main_runtime,
  574. runtime_validator=runtime_validator, title_preview=title_preview,
  575. ), "llm"
  576. if title and _is_provisional_greeting_title(title):
  577. source = "derived"
  578. if not title: # the inline attempt declined collisions; off the critical path the lineage scan is affordable
  579. title, source = derive_title(user_message, title_preview), "derived"
  580. if not title:
  581. return
  582. try:
  583. persisted = _persist_session_title(session_db, session_id, title, source=source)
  584. except Exception as e:
  585. logger.debug("Failed to set auto-generated title: %s", e)
  586. return
  587. if persisted is not None:
  588. logger.debug("Auto-generated session title: %s", persisted)
  589. _notify_title(title_callback, persisted, source, "Auto-title")
  590. except Exception as e:
  591. # WARNING so operators see it in agent.log; names the likely cause.
  592. logger.warning("Auto-title failed (harmless; if this started after an update, restart the running Hermes process): %s", e)
  593. logger.debug("Auto-title traceback", exc_info=True)
  594. _report_failure(failure_callback, e, "Auto-title")
  595. def _is_real_user_turn(message: Any) -> bool:
  596. """A question a person actually asked (Hermes persists machinery under ``role="user"``)."""
  597. if not isinstance(message, dict) or message.get("role") != "user":
  598. return False
  599. content = message.get("content")
  600. return is_titleable_user_message(content if isinstance(content, str) else flatten_message_text(content))
  601. def _session_is_untitled(session_db, session_id: str) -> bool:
  602. """No title of any provenance; False when it can't tell (no model call per turn for an unreadable title)."""
  603. getter = getattr(session_db, "get_session_title", None)
  604. try:
  605. return callable(getter) and not str(getter(session_id) or "").strip()
  606. except Exception:
  607. logger.debug("Untitled check failed for %s", session_id, exc_info=True)
  608. return False
  609. def _kanban_task_title() -> Optional[str]:
  610. """Kanban worker: the card's title, or ``Kanban task <id>`` when the board can't be read; None elsewhere
  611. (including delegate_task children of the worker, which inherit the env var but are not the card)."""
  612. task_id = (os.environ.get("HERMES_KANBAN_TASK") or "").strip()
  613. if not task_id or not is_dispatcher_owned_worker_context():
  614. return None
  615. try:
  616. from hermes_cli import kanban_db, kanban_db_connect
  617. from hermes_state import SessionDB
  618. with kanban_db_connect.connect_closing() as conn:
  619. task = kanban_db.get_task(conn, task_id)
  620. title = " ".join((task.title or "").split()) if task is not None else ""
  621. # Cards have no length cap; the title store rejects past MAX_TITLE_LENGTH (and the ``#N``
  622. # retry suffix needs room), which would leave the worker nameless.
  623. cap = SessionDB.MAX_TITLE_LENGTH - 4
  624. if len(title) > cap:
  625. title = title[: cap - 1].rstrip() + "…"
  626. except Exception:
  627. logger.debug("Kanban task %s unreadable; naming the session after its id", task_id, exc_info=True)
  628. title = ""
  629. return title or f"Kanban task {task_id}"
  630. def maybe_auto_title(
  631. session_db,
  632. session_id: str,
  633. user_message: str,
  634. conversation_history: Optional[list] = None,
  635. failure_callback: Optional[FailureCallback] = None,
  636. main_runtime: dict | None = None,
  637. title_callback: Optional[TitleCallback] = None,
  638. runtime_validator: Optional[RuntimeValidator] = None,
  639. title_preview: str | None = None,
  640. ) -> Optional[threading.Thread]:
  641. """Instant inline title, then a daemon-thread upgrade. Call at the START of a turn, before the model.
  642. Returns the upgrade thread: already started, or — when ``title_upgrade_must_wait_for_turn`` — left
  643. UNSTARTED for the caller to hand to ``start_title_upgrade`` once the turn's model request settled."""
  644. if not session_db or not session_id or not user_message:
  645. return None
  646. # History may be pre- or post-message. Past the opening turn, skip once the session holds an
  647. # ``llm``/``user`` name: count alone left a machinery-opened session nameless, and a ``derived``
  648. # name is still a placeholder (instant slice, or the model's greeting title for a bare "hi") that
  649. # the first substantive turn should replace. Untitled sessions always get another shot; a
  650. # placeholder gets turns 2-3, so a failing title model costs at most three calls, not one per turn.
  651. user_msg_count = sum(1 for m in (conversation_history or []) if _is_real_user_turn(m))
  652. if user_msg_count > 1 and (
  653. _has_upgraded_title(session_db, session_id)
  654. or (user_msg_count > 3 and not _session_is_untitled(session_db, session_id))
  655. ):
  656. return None
  657. kanban_title = _kanban_task_title()
  658. if kanban_title:
  659. # The card already carries a human-written name; an auxiliary model call per spawned worker
  660. # only competes with the worker for capacity (#111166). Final (``llm``) authority: nothing
  661. # upgrades it later, and a manual ``/title`` still wins inside ``set_auto_title``.
  662. with suppress(Exception):
  663. persisted = _persist_session_title(session_db, session_id, kanban_title, source="llm")
  664. if persisted:
  665. _notify_title(title_callback, persisted, "llm", "Kanban task title")
  666. return None
  667. if not is_titleable_user_message(user_message):
  668. return None
  669. if not _auto_title_enabled(): # config read after the cheap guards so the file isn't touched every turn
  670. logger.debug("Auto-title skipped: auxiliary.title_generation.enabled=false")
  671. return None
  672. apply_instant_title(session_db, session_id, user_message, title_callback, title_preview=title_preview)
  673. if not _model_title_upgrade_enabled():
  674. logger.debug("Instant title persisted; model upgrade disabled by auxiliary.title_generation.model_upgrade_enabled=false")
  675. return None
  676. # The thread must resolve auxiliary.title_generation (config, provider key, language) for the
  677. # profile whose turn this is: a bare Thread starts with an empty context and lands on the launch
  678. # profile under multiplex, titling X's session with the default profile's model and billing its key.
  679. from agent.memory_provider import spawn_context_thread
  680. upgrade_kwargs = dict(failure_callback=failure_callback, main_runtime=main_runtime, title_callback=title_callback,
  681. runtime_validator=runtime_validator)
  682. if isinstance(title_preview, str) and title_preview.strip():
  683. upgrade_kwargs["title_preview"] = title_preview
  684. upgrade = spawn_context_thread(
  685. auto_title_session, name="auto-title",
  686. args=(session_db, session_id, user_message),
  687. kwargs=upgrade_kwargs,
  688. )
  689. if title_upgrade_must_wait_for_turn(main_runtime):
  690. logger.debug("Auto-title upgrade deferred past the turn: shares the self-hosted endpoint with the main request")
  691. return upgrade
  692. start_title_upgrade(upgrade)
  693. return upgrade