feat(title): heuristic session title generation for instant titles

[DavidMetcalfe]

Summary

Adds a synchronous regex-based heuristic title extractor that runs before the existing LLM title generation call. The heuristic sets an instant placeholder title (~0ms), then the LLM overwrites it when it returns.

Closes #55201.

What changed

Before

first exchange → LLM call (2-5s) → title appears
                → if LLM fails, session stays untitled

After

first exchange → heuristic extracts title (~0ms) → title appears instantly
               → LLM call runs in background → overwrites heuristic title
               → if LLM fails, heuristic title remains

New files

• agent/title_heuristic.py (~325 lines) — standalone regex-based title extractor with no external dependencies
• tests/agent/test_title_heuristic.py (35 tests) — comprehensive test suite

Modified files

• agent/title_generator.py — wired heuristic into maybe_auto_title
• tests/agent/test_title_generator.py — updated tests for new behavior, added race-condition tests

How the heuristic works

Uses pattern matching inspired by RAKE (Rapid Automatic Keyword Extraction):

1. Prefix stripping — removes conversational prefixes ("Can you", "Hey, I need help", "Let's", etc.) iteratively
2. Action verb patterns — matches imperative verbs (fix, add, review, refactor, etc.) and preserves the original verb (no normalization — "patch" stays "patch", "adjust" stays "adjust")
3. Question patterns — "how does X work?" → "How X works", "what is the difference between X and Y?" → "Difference between X and Y"
4. Progressive length guard — if aggressive clause stripping produces < 3 words, retries with less aggressive cleanup
5. RAKE-inspired keyphrase fallback — when no pattern matches, splits at constituent boundaries (conjunctions, relative pronouns) and scores phrases by word frequency × position × length bonus

Example outputs:

"Fix the dropdown menu closing when you hover"
  → "Fix dropdown menu closing"

"Can you review PR #3979 on radix-ui/primitives?"
  → "Review PR #3979"

"How does the auxiliary client fallback chain work?"
  → "How the auxiliary client fallback chain works"

Race-condition protection

The LLM thread only overwrites the title if the current title still matches the heuristic placeholder. This protects user-set titles that arrive in the interim window between the heuristic set and the LLM completion.

# In auto_title_session:
if heuristic_placeholder is not None:
    current = session_db.get_session_title(session_id)
    if current and current != heuristic_placeholder:
        return  # user renamed, don't overwrite

Phase 2 (follow-up PR, outlined in #55201)

Enhance the LLM title generation prompt with examples from the user's past manual renames via a title_source column on the sessions table. Depends on this PR but ships separately.

Testing

• 57 tests pass (35 heuristic + 22 title generator)
• All 15 TUI gateway title tests pass
• Pre-existing ACP test failures (missing pytest-asyncio) are unrelated

[rodriguez46p-ui]

Hermes Agent review: blocking race regression

Thanks for the PR — the heuristic itself is nicely isolated and the focused tests pass locally. I found one behavioral regression in the LLM worker guard that should be fixed before merge.

Blocking

• agent/title_generator.py: when auto_title_session(..., heuristic_placeholder=None) is used, the new code now unconditionally overwrites any existing title after generate_title() returns. On main, auto_title_session always checks get_session_title() first and returns if a user/manual title already exists. The PR even adds test_overwrites_when_no_placeholder to lock in the new behavior as “legacy behavior”, but it is the opposite of the current behavior.

Why this matters: heuristic_placeholder=None is still a valid path for direct callers and for edge cases where no heuristic placeholder exists. In that path, a user-set title that arrives before the background LLM worker runs can be overwritten by the LLM title, regressing the existing user-title protection.

Reproducer I ran in the PR worktree:

from unittest.mock import MagicMock, patch
from agent.title_generator import auto_title_session

db = MagicMock()
db.get_session_title.return_value = "User Custom Title"
with patch("agent.title_generator.generate_title", return_value="LLM Title"):
    auto_title_session(db, "sess", "hi", "hello", heuristic_placeholder=None)
print(db.set_session_title.call_args_list)

Actual on this PR:

[call('sess', 'LLM Title')]

Expected, matching origin/main: no set_session_title call.

Suggested fix: preserve the old “skip if any title exists” behavior when there is no heuristic placeholder, and keep the new placeholder-specific overwrite only when the current title still equals the heuristic placeholder. A test should assert that heuristic_placeholder=None does not overwrite an existing user title.

Local checks run

• git diff --check origin/main...HEAD — passed
• /c/Users/yolop/.hermes/hermes-agent/venv/Scripts/python.exe -m pytest tests/agent/test_title_heuristic.py tests/agent/test_title_generator.py -q — 57 passed in 2.64s

Hosted CI was still in progress when checked; completed lints/e2e/supply-chain/contributor checks were green, Python slices and Docker jobs were still running.

[DavidMetcalfe]

@rodriguez46p-ui Good catch — confirmed as a BLOCKER via Gemini Pro review.

Root cause: when heuristic_placeholder=None, the new code unconditionally overwrites any existing title, regressing the existing user-title protection from main.

Fix (pushed): restored the existing-title guard. When heuristic_placeholder is set, the placeholder-matching logic applies (only overwrite if the current title still matches). When heuristic_placeholder is None, the legacy "skip if any title exists" behavior is preserved.

Reproducer verified: your exact reproducer now correctly skips — no set_session_title call when a user title already exists and heuristic_placeholder=None.

from unittest.mock import MagicMock, patch
from agent.title_generator import auto_title_session

db = MagicMock()
db.get_session_title.return_value = "User Custom Title"
with patch("agent.title_generator.generate_title", return_value="LLM Title"):
    auto_title_session(db, "sess", "hi", "hello", heuristic_placeholder=None)
# Now correctly: no set_session_title call

57 tests pass. The test_skips_when_no_placeholder_and_title_exists test now locks in the correct legacy behavior.

[tonydwb]

Code Review Summary

Verdict: LGTM

Well-designed heuristic session title generation. The approach is clean: a synchronous heuristic sets an instant placeholder title before the LLM call runs in a background thread. The LLM result overwrites the heuristic only if the title still matches the placeholder, protecting user-set titles that arrived in the interim.

Correctness: Race-condition guard is well-thought-out — only overwrites if the current title matches the heuristic placeholder.
Code Quality: Clean separation between heuristic and LLM title paths.

---

Reviewed by Hermes Agent

[tonydwb]

Code Review Summary

Verdict: LGTM

Adds synchronous regex-based heuristic title extractor that runs before LLM title generation. Sets an instant placeholder title (~0ms), then LLM result overwrites it when available.

• Clean separation of heuristic vs LLM paths
• Good fallback behavior when LLM fails
• Well-scoped: 4 files, 608 additions

Reviewed 4 files, 608 additions. Approved.

[teknium1]

Thanks for the focused fallback implementation. The instant-title premise still holds on current main: agent/title_generator.py:193-204 starts a background worker, whose LLM call precedes the title write at :148-155.

Problems

• The placeholder check in this PR happens before generate_title() (agent/title_generator.py:149-170), but the write is later at :174-175. A manual /title during the LLM call can still be overwritten; hermes_state.py:2988-2993 supplies only an unconditional update.
• The new heuristic callback at agent/title_generator.py:230-232 runs before the existing final callback. Gateway sends that callback to Discord thread renaming (gateway/run.py:19142-19147), which accepts only the original thread name (gateway/run.py:13686-13692; plugins/platforms/discord/adapter.py:5432-5437). A placeholder rename can therefore prevent the final LLM title from reaching the thread.

Suggested changes

• Use a post-LLM conditional update keyed to the heuristic placeholder, with a test that injects a manual rename during generation.
• Distinguish placeholder UI updates from final external rename callbacks, and cover the two-title Discord sequence.

Automated hermes-sweeper review.

[teknium1]

This comparison is before generate_title(), while the title write is after it. A user rename during the LLM call can still be overwritten; re-check atomically immediately before the write (preferably with a conditional SessionDB update) and add a test that mutates the title from generate_title's side effect.

[teknium1]

This sends the same callback twice per session. Gateway maps it to Discord semantic-thread renaming, whose only_if_current_name guard accepts only the original thread name; after this placeholder rename succeeds, the final LLM callback can be rejected. Keep placeholder UI notification separate from final external rename behavior, or make the callback stage-aware.

[DavidMetcalfe]

Thanks @rodriguez46p-ui — fixed in commit 4cef8a123.

What I changed

Restored the existing guard so the legacy "skip if any title already exists" behavior is preserved when heuristic_placeholder=None, while keeping the new race-condition protection for the heuristic_placeholder=<set> path (agent/title_generator.py:148-166):

try:
    existing = session_db.get_session_title(session_id)
    if existing:
        if heuristic_placeholder is not None:
            # Race-condition guard: only overwrite if the current title
            # still matches the heuristic placeholder.
            if existing != heuristic_placeholder:
                logger.debug(
                    "Title changed from heuristic placeholder (%r -> %r), skipping LLM overwrite",
                    heuristic_placeholder, existing,
                )
                return
            # Title matches placeholder — proceed to overwrite with LLM
        else:
            # Legacy path: any existing title means skip
            return
except Exception:
    return

Verifying against your reproducer

Running your exact reproducer against the fix:

generate_title calls: []
set_session_title calls: []

No overwrite. The guard correctly returns when heuristic_placeholder=None and any non-empty title already exists.

Updated test coverage

Renamed test_overwrites_when_no_placeholder → test_skips_when_no_placeholder_and_title_exists and inverted it to lock in the legacy behavior:

db.get_session_title.return_value = "User Custom Title"
with patch("agent.title_generator.generate_title", return_value="LLM Title") as gen:
    auto_title_session(db, "sess-1", "hi", "hello",
                       heuristic_placeholder=None)
    gen.assert_not_called()
    db.set_session_title.assert_not_called()

All four quadrants are now covered:

heuristic_placeholder	Existing title	Behavior
None	empty	Overwrite (legacy)
None	non-empty	Skip (legacy, restored by this fix)
set, matches existing	set	Overwrite (race-safe)
set, differs from existing	set	Skip (race-safe)

Test results

pytest tests/agent/test_title_generator.py tests/agent/test_title_heuristic.py -q → 57 passed in 1.47s.

The fix was cross-vendor reviewed (Flash + GPT-OSS); both reviewers confirmed the quadrant logic and matched legacy semantics for the "" empty-string edge case (treated as "no title", unchanged from main).

[OutThisLife]

This shipped on main in f726090 — derive_title() + apply_instant_title() in agent/title_generator.py write a title from the first meaningful line synchronously, before the model call is forked onto its thread, and the model's version replaces it when it lands. Same two-phase shape you proposed here, down to the heuristic surviving when the LLM call fails.

Closing as already implemented. The LLM-failure gap you called out in #55201 is finished off in #82390: an opener that no heuristic can name (an image with no caption, a compaction handoff) now gets reconsidered on a later turn instead of staying NULL for the life of the session.

#55201 stays open for phase 2 — the title generator still learns nothing from past titles or manual renames.