Skip to content

The agent that grows with you

fix(plugins): fire on_session_delete on every session-deletion path

finn763ee3ce9a4d96d
diff --git a/gateway/platforms/api_server.py b/gateway/platforms/api_server.py
index 9e8096c3233..f50c17616db 100644
--- a/gateway/platforms/api_server.py
+++ b/gateway/platforms/api_server.py
@@ -3122,6 +3122,8 @@ class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):
try:
db._resolve_title_conflict(conn, session_id, clean_title)
except ValueError as exc: # the DB's uniqueness rule; undo the INSERT
+ # No ``on_session_delete`` here: this rolls back the row inserted in the
+ # same transaction, so the session never existed — firing would double-count it.
conn.execute("DELETE FROM sessions WHERE id = ?", (session_id,))
return None, f"title:{exc}"
conn.execute("UPDATE sessions SET title = ? WHERE id = ?", (clean_title, session_id))
diff --git a/hermes_cli/hooks.py b/hermes_cli/hooks.py
index 32a15326340..1f2df15c24f 100644
--- a/hermes_cli/hooks.py
+++ b/hermes_cli/hooks.py
@@ -127,6 +127,7 @@ _DEFAULT_PAYLOADS = {
},
"on_session_finalize": {"session_id": "test-session"},
"on_session_reset": {"session_id": "test-session"},
+ "on_session_delete": {"session_id": "test-session"},
"pre_api_request": {
"session_id": "test-session", "task_id": "test-task", "platform": "cli",
"model": "claude-sonnet-4-6", "provider": "anthropic",
diff --git a/hermes_cli/lifecycle.py b/hermes_cli/lifecycle.py
index 6ff300d729b..6bee3b15412 100644
--- a/hermes_cli/lifecycle.py
+++ b/hermes_cli/lifecycle.py
@@ -95,3 +95,22 @@ def finalize_session(**kwargs: Any) -> list[Any]:
logger.warning("Core Relay session finalization failed", exc_info=True)
return _plugin_hooks("on_session_finalize", **kwargs)
+
+
+def notify_session_deleted(session_id: str, **kwargs: Any) -> list[Any]:
+ """Fire the ``on_session_delete`` post-commit observer (#124511).
+
+ Call only after the delete transaction commits and only when a row was
+ actually removed. Observer-only: returns ignored, failures fail open
+ (logged, never raised) so a slow/broken plugin cannot break deletion.
+ Unbounded/caller-thread like ``on_session_finalize`` — cleanup work
+ ("close a handle, unlink a directory") must not be abandoned mid-way.
+ # ponytail: single process-local fan-out; per-surface reason/platform
+ # enrichment stays with callers, add a queue here only if a callback
+ # measurably blocks a delete path.
+ """
+ try:
+ return invoke_hook("on_session_delete", session_id=session_id, **kwargs)
+ except Exception:
+ logger.warning("on_session_delete dispatch failed", exc_info=True)
+ return []
diff --git a/hermes_cli/plugins.py b/hermes_cli/plugins.py
index c7fad5e387d..52cfd2d5175 100644
--- a/hermes_cli/plugins.py
+++ b/hermes_cli/plugins.py
@@ -128,7 +128,7 @@ VALID_HOOKS: set[str] = {
# Run-all-then-pick-first (see get_plugin_error_classification). Privacy: error_message/
# error_body may be unredacted.
"transform_api_error_classification", "on_session_start", "on_session_end",
- "on_session_finalize", "on_session_reset",
+ "on_session_finalize", "on_session_reset", "on_session_delete",
# on_skill_lifecycle: successful skill lifecycle facts (local skill name visible to plugins).
"on_skill_lifecycle", "subagent_start", "subagent_stop",
# pre_gateway_dispatch: once per incoming MessageEvent, after the internal-event guard, BEFORE
diff --git a/hermes_state_common.py b/hermes_state_common.py
index c3b0a08cc7b..1546cba0686 100644
--- a/hermes_state_common.py
+++ b/hermes_state_common.py
@@ -392,6 +392,36 @@ def _id_chunks(ids, size: int = _SQL_IN_CHUNK):
yield ids[start:start + size]
+def emit_session_deleted(deleted_ids=None, *, reason=None, sessions_dir=None):
+ """Fire the ``on_session_delete`` post-commit observer for committed deletes (#124511).
+
+ Late-bound seam: the state layer must not import ``hermes_cli`` at module
+ top level, so the dispatch resolves inside the call and fails open — a
+ missing/broken plugin stack never breaks deletion. Call only after the
+ write transaction commits, with the ids actually removed. One invocation
+ per delete operation; ``deleted_ids`` rides along only when the count
+ differs from 1.
+ """
+ ids = sorted({sid for sid in (deleted_ids or ()) if isinstance(sid, str) and sid})
+ if not ids:
+ return
+ try:
+ from hermes_cli.lifecycle import notify_session_deleted
+ except Exception:
+ return
+ payload: dict = {"session_id": ids[0]}
+ if len(ids) > 1:
+ payload["deleted_ids"] = ids
+ if reason is not None:
+ payload["reason"] = reason
+ if sessions_dir is not None:
+ payload["sessions_dir"] = str(sessions_dir)
+ try:
+ notify_session_deleted(**payload)
+ except Exception:
+ logger.warning("on_session_delete dispatch failed", exc_info=True)
+
+
_FTS_TRIGGERS = ("messages_fts_insert", "messages_fts_delete", "messages_fts_update",
"messages_fts_trigram_insert", "messages_fts_trigram_delete", "messages_fts_trigram_update")
diff --git a/hermes_state_maintenance.py b/hermes_state_maintenance.py
index d37556a004c..6fd0cc5f5f8 100644
--- a/hermes_state_maintenance.py
+++ b/hermes_state_maintenance.py
@@ -9,7 +9,7 @@ from typing import Any, Dict, Iterable, List, Optional, Tuple
from hermes_state_common import (
AUTO_VACUUM_MIN_FREELIST_RATIO, _id_chunks, _non_continuation_child_sql, _placeholders, _sql_session_last_active,
- escape_like as _escape_like
+ escape_like as _escape_like, emit_session_deleted,
)
from hermes_startup_watchdog import report_startup_progress
@@ -136,6 +136,8 @@ class SessionMaintenanceMixin:
collect_retired_media(self)
for sid in removed_ids if sessions_dir else ():
self._remove_session_files(sessions_dir, sid)
+ if removed_ids:
+ emit_session_deleted(removed_ids, reason="ghost_prune", sessions_dir=sessions_dir)
return len(removed_ids)
def _guarded_ids(self, conn, ids: Iterable[str]) -> set:
@@ -373,6 +375,8 @@ class SessionMaintenanceMixin:
self._remove_session_files(sessions_dir, sid)
if deleted_ids is not None:
deleted_ids.extend(removed_ids)
+ if count:
+ emit_session_deleted(removed_ids, reason="prune", sessions_dir=sessions_dir)
return count
def _page_pragmas(self, names: tuple[str, ...], fail_msg: str) -> Optional[list]:
diff --git a/hermes_state_profile_repair.py b/hermes_state_profile_repair.py
index 716f1a14946..0ebb6e2b463 100644
--- a/hermes_state_profile_repair.py
+++ b/hermes_state_profile_repair.py
@@ -24,7 +24,11 @@ from __future__ import annotations
import logging
from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
-from hermes_state_common import _id_chunks, _placeholders as _session_ids_placeholders
+from hermes_state_common import (
+ _id_chunks,
+ _placeholders as _session_ids_placeholders,
+ emit_session_deleted,
+)
logger = logging.getLogger(__name__)
@@ -284,7 +288,10 @@ class SessionProfileRepairMixin:
conn.execute("DELETE FROM sessions WHERE id = ?", (session_id,))
self._delete_unreferenced_system_prompts(conn)
return True
- return bool(self._execute_write(_do))
+ deleted = self._execute_write(_do)
+ if deleted:
+ emit_session_deleted([session_id], reason="profile_repair")
+ return bool(deleted)
# ── routing index ─────────────────────────────────────────────────────────
diff --git a/hermes_state_sessions.py b/hermes_state_sessions.py
index 28b7cf60121..68eb98df26e 100644
--- a/hermes_state_sessions.py
+++ b/hermes_state_sessions.py
@@ -22,7 +22,7 @@ from hermes_state_common import (
_shape_preview, _sql_preview_raw, QUEUED_PROMPT_METADATA_KEY,
_sql_in_window, _sql_json_extract, _sql_session_last_active, _sql_session_last_active_by_id,
escape_like as _escape_like, _SQL_IN_CHUNK, _id_chunks, _placeholders as _session_ids_placeholders,
- _source_match_clause,
+ _source_match_clause, emit_session_deleted,
)
from hermes_state_compression import _CHAIN_CAP
@@ -1757,6 +1757,8 @@ class SessionSessionsMixin:
collect_retired_media(self)
for sid in removed_ids:
self._remove_session_files(sessions_dir, sid)
+ if deleted:
+ emit_session_deleted(removed_ids, sessions_dir=sessions_dir)
return bool(deleted)
def discard_unadmitted_session(self, session_id: str) -> bool:
@@ -1817,6 +1819,7 @@ class SessionSessionsMixin:
collect_retired_media(self)
if deleted:
self._remove_session_files(sessions_dir, session_id)
+ emit_session_deleted([session_id], sessions_dir=sessions_dir)
return deleted
def delete_sessions(
@@ -1904,6 +1907,8 @@ class SessionSessionsMixin:
collect_retired_media(self)
for sid in removed_ids:
self._remove_session_files(sessions_dir, sid)
+ if count:
+ emit_session_deleted(removed_ids, sessions_dir=sessions_dir)
return count
# Shared by count_empty_sessions / delete_empty_sessions so badge and sweep agree. message_count
@@ -1946,6 +1951,8 @@ class SessionSessionsMixin:
collect_retired_media(self)
for sid in removed_ids:
self._remove_session_files(sessions_dir, sid)
+ if count:
+ emit_session_deleted(removed_ids, reason="empty_sweep", sessions_dir=sessions_dir)
return count
def archive_sessions(
diff --git a/tests/hermes_state/test_session_delete_hook.py b/tests/hermes_state/test_session_delete_hook.py
new file mode 100644
index 00000000000..639e9624eed
--- /dev/null
+++ b/tests/hermes_state/test_session_delete_hook.py
@@ -0,0 +1,121 @@
+"""on_session_delete post-commit observer (#124511).
+
+Delete paths must notify plugins after the commit so per-session on-disk
+state can be cleaned up without polling the store. Failing observers fail
+open — deletion itself never breaks.
+"""
+
+import pytest
+
+from hermes_cli import lifecycle
+from hermes_cli.plugins import VALID_HOOKS
+from hermes_state import SessionDB
+
+
+def db(tmp_path):
+ session_db = SessionDB(db_path=tmp_path / "test_state.db")
+ yield session_db
+ session_db.close()
+
+
[email protected](autouse=True)
+def _no_fts_rebuild_throttle(monkeypatch):
+ monkeypatch.setattr(SessionDB, "_FTS_REBUILD_MIN_PAUSE", 0.0)
+ monkeypatch.setattr(SessionDB, "_FTS_REBUILD_DUTY_FACTOR", 0.0)
+
+
+def fired(monkeypatch):
+ calls = []
+
+ def _spy(**kwargs):
+ calls.append(kwargs)
+ return []
+
+ monkeypatch.setattr(lifecycle, "notify_session_deleted", _spy)
+ return calls
+
+
+def test_hook_is_registered():
+ assert "on_session_delete" in VALID_HOOKS
+
+
+def test_delete_session_fires_once(db, fired):
+ db.create_session(session_id="s1", source="cli")
+ db.append_message("s1", role="user", content="hi")
+
+ assert db.delete_session("s1") is True
+
+ assert len(fired) == 1
+ assert fired[0]["session_id"] == "s1"
+ assert "deleted_ids" not in fired[0]
+
+
+def test_delete_session_unknown_id_does_not_fire(db, fired):
+ assert db.delete_session("missing") is False
+ assert fired == []
+
+
+def test_delete_sessions_bulk_fires_once_with_ids(db, fired):
+ db.create_session(session_id="s1", source="cli")
+ db.create_session(session_id="s2", source="cli")
+ db.create_session(session_id="keep", source="cli")
+
+ assert db.delete_sessions(["s1", "s2", "missing"]) == 2
+
+ assert len(fired) == 1
+ assert fired[0]["session_id"] == "s1"
+ assert fired[0]["deleted_ids"] == ["s1", "s2"]
+
+
+def test_delete_empty_sessions_carries_reason(db, fired):
+ db.create_session(session_id="empty", source="cli")
+ db.end_session("empty", "done")
+
+ assert db.delete_empty_sessions() == 1
+
+ assert len(fired) == 1
+ assert fired[0]["session_id"] == "empty"
+ assert fired[0]["reason"] == "empty_sweep"
+
+
+def test_delete_moved_session_fires_with_reason(db, fired):
+ db.create_session(session_id="moved1", source="cli")
+
+ assert db.delete_moved_session("moved1") is True
+
+ assert len(fired) == 1
+ assert fired[0]["session_id"] == "moved1"
+ assert fired[0]["reason"] == "profile_repair"
+
+
+def test_delete_moved_session_unknown_id_does_not_fire(db, fired):
+ assert db.delete_moved_session("missing") is False
+ assert fired == []
+
+
+def test_failing_observer_does_not_break_delete(db, monkeypatch):
+ def _boom(**kwargs):
+ raise RuntimeError("plugin down")
+
+ monkeypatch.setattr(lifecycle, "notify_session_deleted", _boom)
+ db.create_session(session_id="s1", source="cli")
+
+ assert db.delete_session("s1") is True
+ assert db.get_session("s1") is None
+
+
+def test_notify_dispatches_hook_and_fails_open(monkeypatch):
+ seen = []
+ monkeypatch.setattr(
+ lifecycle, "invoke_hook", lambda name, **kw: seen.append((name, kw)) or []
+ )
+ lifecycle.notify_session_deleted("s1", reason="prune")
+ assert seen == [("on_session_delete", {"session_id": "s1", "reason": "prune"})]
+
+ def _boom(name, **kw):
+ raise RuntimeError("dispatch down")
+
+ monkeypatch.setattr(lifecycle, "invoke_hook", _boom)
+ assert lifecycle.notify_session_deleted("s1") == []
diff --git a/website/docs/developer-guide/plugins/index.md b/website/docs/developer-guide/plugins/index.md
index 7e2fc1ccd63..4d5ab02f1f0 100644
--- a/website/docs/developer-guide/plugins/index.md
+++ b/website/docs/developer-guide/plugins/index.md
@@ -1352,6 +1352,7 @@ Each hook is documented in full on the **[Event Hooks reference](../../user-guid
| [`on_session_end`](../../user-guide/features/hooks.md#on_session_end) | End of every `run_conversation` call + CLI exit | `session_id: str, completed: bool, interrupted: bool, model: str, platform: str` | ignored |
| [`on_session_finalize`](../../user-guide/features/hooks.md#on_session_finalize) | CLI/gateway tears down an active session | `session_id: str \| None, platform: str` | ignored |
| [`on_session_reset`](../../user-guide/features/hooks.md#on_session_reset) | Gateway swaps in a new session key (`/new`, `/reset`) | `session_id: str, platform: str` | ignored |
+| [`on_session_delete`](../../user-guide/features/hooks.md#on_session_delete) | A session row delete commits (single, bulk, sweep, prune) | `session_id: str`, optional `deleted_ids: list[str]`, `reason: str`, `sessions_dir: str` | ignored |
| [`gateway_platform_event`](../../user-guide/features/hooks.md#gateway_platform_event) | An authorized platform-native event is normalized at the gateway boundary (Telegram reactions currently) | `platform: str, event_type: str, payload: dict` | ignored |
| `kanban_task_claimed` | A kanban task is claimed (dispatcher process, before the worker spawns) | `task_id: str, board: str \| None, assignee: str \| None, run_id: int \| None, profile_name: str` | ignored |
| `kanban_task_completed` | A kanban task completes (worker process) | `task_id, board, assignee, run_id, profile_name, summary: str \| None` | ignored |
diff --git a/website/docs/user-guide/features/hooks.md b/website/docs/user-guide/features/hooks.md
index 0c42653be2d..725ac2888a4 100644
--- a/website/docs/user-guide/features/hooks.md
+++ b/website/docs/user-guide/features/hooks.md
@@ -471,6 +471,7 @@ Payload fields below are the exact event-specific fields supplied by each call s
| `on_session_end` | Observer | Canonically at each turn finalization; CLI/TUI exits have additional reduced legacy shapes. Return ignored. | Canonical: `session_id`, `task_id`, `turn_id`, `completed`, `failed`, `interrupted`, `turn_exit_reason`, `model`, `platform`; exit paths may add `reason`/`api_request_id` and omit fields. | IDs, model/platform, and outcome; canonical payload has no message body. |
| `on_session_finalize` | Observer | CLI/TUI/gateway teardown through `finalize_session`; gateway shutdown may finalize without a reset. Return ignored. | Surface-dependent `session_id`, `platform`, optionally `reason`, `old_session_id`, `new_session_id` | Session and routing identifiers. |
| `on_session_reset` | Observer | CLI/TUI session boundary and gateway after the replacement session exists; return ignored. | CLI: `session_id`, `platform`, `reason`; TUI: `session_id`, `platform`; gateway: those plus `reason`, `old_session_id`, `new_session_id` | Session and routing identifiers. |
+| `on_session_delete` | Observer | After a session row delete commits (single, bulk, empty-sweep, prune, ghost prune); return ignored. | `session_id`, optional `deleted_ids` (full set when the count differs from 1), `reason`, `sessions_dir` | Session identifiers only; no message content. |
| `agent_loop_stopped` | Observer | Immediately after a real running agent is interrupted — gateway `_interrupt_and_clear_session` or TUI/desktop `session.interrupt`; return ignored. | `session_key`, `platform`, `reason`, `invalidation_reason` | Session/routing identifiers and interruption reasons; no message body. |
| `on_skill_lifecycle` | Observer | After an authoritative skill-usage state change; return ignored. | `action`, `skill_name`, `provenance`, `task_id`, `session_id`, `use_count`, `reused`, `reuse_after_patch` | Exposes the local skill name and provenance. |
| `subagent_start` | Observer | Child constructed and about to run; return ignored. | `parent_session_id`, `parent_turn_id`, `parent_subagent_id`, `child_session_id`, `child_subagent_id`, `child_role`, `child_goal` | Child goal may contain user/project content. |
@@ -1081,6 +1082,31 @@ def my_callback(session_id: str, platform: str, **kwargs):
---
+### `on_session_delete`
+
+Fires **once per delete operation after the transaction commits**, when a session row was actually removed — covering single deletes, bulk deletes, the empty-session sweep, retention prunes, and ghost-prune maintenance. This lets plugins that keep per-session on-disk state clean up without polling the session store.
+
+**Callback signature:**
+
+```python
+def my_callback(session_id: str, **kwargs):
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `session_id` | `str` | The session that was deleted. Always present. |
+| `deleted_ids` | `list[str]`, optional | Full set removed by the operation, including cascade-deleted delegate children and every row in a bulk delete. Present when the count differs from 1. |
+| `reason` | `str`, optional | Why the delete happened (`"prune"`, `"ghost_prune"`, `"empty_sweep"`, …). |
+| `sessions_dir` | `str`, optional | Absolute path of the profile's `sessions/` dir, so a plugin does not have to re-derive the per-profile home. |
+
+**Fires:** Post-commit only, and only when the delete actually happened (unknown ids in a bulk delete are skipped silently). Return ignored; a failing callback is logged and skipped like every other observer. The payload carries no message content — only ids, the reason, and the directory.
+
+**Return value:** Ignored.
+
+**Use cases:** Delete a per-session sidecar database or cache directory, emit "session deleted" analytics, release per-session external resources.
+
+---
+
See the **[Build a Plugin guide](../../developer-guide/plugins/index.md)** for the full walkthrough including tool schemas, handlers, and advanced hook patterns.
---
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md
index 486ec4e8c91..2182a9ca4b6 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md
@@ -552,6 +552,7 @@ def register(ctx):
| [`on_session_end`](../../user-guide/features/hooks.md#on_session_end) | 每次 `run_conversation` 调用结束 + CLI 退出 | `session_id: str, completed: bool, interrupted: bool, model: str, platform: str` | 忽略 |
| [`on_session_finalize`](../../user-guide/features/hooks.md#on_session_finalize) | CLI/网关销毁活跃会话 | `session_id: str \| None, platform: str` | 忽略 |
| [`on_session_reset`](../../user-guide/features/hooks.md#on_session_reset) | 网关切换新会话键(`/new`、`/reset`) | `session_id: str, platform: str` | 忽略 |
+| [`on_session_delete`](../../user-guide/features/hooks.md#on_session_delete) | 会话行删除提交后(单删、批量、sweep、prune) | `session_id: str`,可选 `deleted_ids: list[str]`、`reason: str`、`sessions_dir: str` | 忽略 |
大多数钩子是即发即忘的观察者——其返回值被忽略。例外是 `pre_llm_call`,它可以向对话中注入上下文。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
index dc590b39381..515221f21d3 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
@@ -393,6 +393,7 @@ def register(ctx):
| `on_session_end` | 观察者 | Canonical 路径在每轮 finalize;CLI/TUI 退出还有精简 legacy shape。 | Canonical:`session_id`, `task_id`, `turn_id`, `completed`, `failed`, `interrupted`, `turn_exit_reason`, `model`, `platform`;退出路径可能增加 `reason`/`api_request_id` 并省略字段。 | ID、model/platform 和结果;canonical payload 无消息正文。 |
| `on_session_finalize` | 观察者 | CLI/TUI/gateway 通过 `finalize_session` teardown;gateway 关闭时可只 finalize 而不 reset。忽略返回值。 | 按 surface:`session_id`, `platform`,可选 `reason`, `old_session_id`, `new_session_id` | Session 和 routing 标识。 |
| `on_session_reset` | 观察者 | CLI/TUI session boundary,或 gateway 创建替代 session 后;忽略返回值。 | CLI:`session_id`, `platform`, `reason`;TUI:`session_id`, `platform`;gateway:另有 `reason`, `old_session_id`, `new_session_id` | Session 和 routing 标识。 |
+| `on_session_delete` | 观察者 | 会话行删除提交后(单删、批量、empty-sweep、prune、ghost prune);忽略返回值。 | `session_id`,可选 `deleted_ids`(删除数不为 1 时为全集)、`reason`、`sessions_dir` | 仅 session 标识;无消息内容。 |
| `on_skill_lifecycle` | 观察者 | 权威 skill 使用状态变更后;忽略返回值。 | `action`, `skill_name`, `provenance`, `task_id`, `session_id`, `use_count`, `reused`, `reuse_after_patch` | 暴露本地 skill 名和 provenance。 |
| `subagent_start` | 观察者 | 子 agent 已构造、即将运行;忽略返回值。 | `parent_session_id`, `parent_turn_id`, `parent_subagent_id`, `child_session_id`, `child_subagent_id`, `child_role`, `child_goal` | Child goal 可能含用户/项目内容。 |
| `subagent_stop` | 观察者 | 子 agent 退出;忽略返回值。 | `parent_session_id`, `parent_turn_id`, `child_session_id`, `child_role`, `child_summary`, `child_status`, `tool_call_history`, `duration_ms` | Summary 和已脱敏 tool-history metadata 仍可能暴露项目结构。 |