Skip to content

The agent that grows with you

fix(sessions): pin the page-first list contract, keep the facade under its cap

Teknium349f919c5fff
diff --git a/hermes_state_session_list.py b/hermes_state_session_list.py
new file mode 100644
index 00000000000..9de08687895
--- /dev/null
+++ b/hermes_state_session_list.py
@@ -0,0 +1,47 @@
+"""Session-list page projection for ``SessionDB.list_sessions_rich``."""
+from typing import Any
+
+
+def project_compression_tips(db, sessions: list[dict[str, Any]], compact_rows: bool) -> list[dict[str, Any]]:
+ """Replace each compression root's surfaced fields with its live tip's (root ``started_at`` kept
+ for stable ordering), one batched query. ``_lineage_ids`` carries every chain id (a tile may
+ hold a MIDDLE segment's id)."""
+ chain_by_root: dict[str, list[str]] = {} # only roots whose tip differs from themselves
+ for s in sessions:
+ if s.get("end_reason") == "compression":
+ chain = db.get_compression_chain(s["id"])
+ if chain and chain[-1] != s["id"]:
+ chain_by_root[s["id"]] = chain
+ tip_rows = (
+ db._get_session_rich_rows_batch(
+ {chain[-1] for chain in chain_by_root.values()}, compact_rows=compact_rows,
+ ) if chain_by_root else {}
+ )
+ projected = []
+ for s in sessions:
+ chain = chain_by_root.get(s["id"])
+ tip_row = tip_rows.get(chain[-1]) if chain else None
+ if not tip_row:
+ projected.append(s)
+ continue
+ merged = dict(s)
+ for key in (
+ "id", "ended_at", "end_reason", "message_count", "tool_call_count", "title", "last_active",
+ "preview", "model", "system_prompt", "cwd", "git_branch", "git_repo_root",
+ ):
+ if key in tip_row:
+ merged[key] = tip_row[key]
+ if merged.get("title") is None:
+ # The title is carried root->tip AFTER the publish transaction; a rotation cut off in
+ # between leaves it on the ended root, and exact-title lookups (`hermes peer dm` ->
+ # canonical "Bot Chat") must still see the lineage under its name (#106165).
+ merged["title"] = s.get("title")
+ merged["_lineage_root_id"] = s["id"]
+ merged["_lineage_ids"] = chain
+ # #121148: the projected row IS an automatic continuation, not a fresh conversation and
+ # not a user branch. The server already classifies the edge (_COMPRESSION_CHILD_SQL) but
+ # only ever used it to hide rows — surface the kind so clients can label the provenance
+ # instead of rendering a sealed-and-rotated chat as a brand-new session.
+ merged["continuation_kind"] = "compression"
+ projected.append(merged)
+ return projected
diff --git a/hermes_state_sessions.py b/hermes_state_sessions.py
index 4b5683ce216..c386b47e70e 100644
--- a/hermes_state_sessions.py
+++ b/hermes_state_sessions.py
@@ -1116,50 +1116,6 @@ class SessionSessionsMixin:
combined = " AND ".join(clauses)
return (f"{where_sql} AND {combined}" if where_sql else f"WHERE {combined}"), params
- def _project_compression_tips(self, sessions: list[dict[str, Any]], compact_rows: bool) -> list[dict[str, Any]]:
- """Replace each compression root's surfaced fields with its live tip's (root ``started_at`` kept
- for stable ordering), one batched query. ``_lineage_ids`` carries every chain id (a tile may
- hold a MIDDLE segment's id)."""
- chain_by_root: dict[str, list[str]] = {} # only roots whose tip differs from themselves
- for s in sessions:
- if s.get("end_reason") == "compression":
- chain = self.get_compression_chain(s["id"])
- if chain and chain[-1] != s["id"]:
- chain_by_root[s["id"]] = chain
- tip_rows = (
- self._get_session_rich_rows_batch(
- {chain[-1] for chain in chain_by_root.values()}, compact_rows=compact_rows,
- ) if chain_by_root else {}
- )
- projected = []
- for s in sessions:
- chain = chain_by_root.get(s["id"])
- tip_row = tip_rows.get(chain[-1]) if chain else None
- if not tip_row:
- projected.append(s)
- continue
- merged = dict(s)
- for key in (
- "id", "ended_at", "end_reason", "message_count", "tool_call_count", "title", "last_active",
- "preview", "model", "system_prompt", "cwd", "git_branch", "git_repo_root",
- ):
- if key in tip_row:
- merged[key] = tip_row[key]
- if merged.get("title") is None:
- # The title is carried root->tip AFTER the publish transaction; a rotation cut off in
- # between leaves it on the ended root, and exact-title lookups (`hermes peer dm` ->
- # canonical "Bot Chat") must still see the lineage under its name (#106165).
- merged["title"] = s.get("title")
- merged["_lineage_root_id"] = s["id"]
- merged["_lineage_ids"] = chain
- # #121148: the projected row IS an automatic continuation, not a fresh conversation and
- # not a user branch. The server already classifies the edge (_COMPRESSION_CHILD_SQL) but
- # only ever used it to hide rows — surface the kind so clients can label the provenance
- # instead of rendering a sealed-and-rotated chat as a brand-new session.
- merged["continuation_kind"] = "compression"
- projected.append(merged)
- return projected
-
def list_recent_sessions_bounded(
self,
*,
@@ -1492,7 +1448,8 @@ class SessionSessionsMixin:
seen_ids.add(s["id"])
sessions.append(s)
if project_compression_tips and not include_children:
- sessions = self._project_compression_tips(sessions, compact_rows)
+ from hermes_state_session_list import project_compression_tips
+ sessions = project_compression_tips(self, sessions, compact_rows)
if heads:
from hermes_state_local import annotate_local_lineages
sessions = annotate_local_lineages(sessions, heads)
diff --git a/scripts/benchmark_local_lineage.py b/scripts/benchmark_local_lineage.py
deleted file mode 100644
index 69d490ac662..00000000000
--- a/scripts/benchmark_local_lineage.py
+++ /dev/null
@@ -1,93 +0,0 @@
-#!/usr/bin/env python3
-"""Measure #143833's projection on synthetic data, never the user's state.db.
-
-Run: python scripts/benchmark_local_lineage.py --prompt-bytes 8192
-The unchanged index builder is the uncached control; the cached path is the one
-used by session list/count calls. Timings are component timings, not UI latency.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import platform
-import sqlite3
-import statistics
-import sys
-import tempfile
-import time
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-
-from hermes_state import SessionDB
-from hermes_state_local import POLICY_PREFIX, _cached_local_lineage_index, local_lineage_index
-
-
-def measure(fn, repeat, expected):
- samples = []
- for _ in range(repeat):
- start = time.perf_counter_ns()
- result = fn()
- samples.append((time.perf_counter_ns() - start) / 1_000_000)
- assert result == expected
- return {'median_ms': statistics.median(samples), 'min_ms': min(samples), 'max_ms': max(samples)}
-
-
-def main():
- parser = argparse.ArgumentParser(description=__doc__)
- parser.add_argument('--receipts', type=int, default=2098)
- parser.add_argument('--sessions', type=int, default=4583)
- parser.add_argument('--prompt-bytes', type=int, default=8192)
- parser.add_argument('--reset-lineages', type=int, default=0)
- parser.add_argument('--repeat', type=int, default=9)
- args = parser.parse_args()
- if not (0 <= args.reset_lineages <= args.receipts and args.sessions >= args.receipts + args.reset_lineages
- and args.receipts > 0 and args.prompt_bytes >= 0 and args.repeat > 0):
- parser.error('positive counts, nonnegative payload, and enough sessions for owners plus reset children required')
- with tempfile.TemporaryDirectory(prefix='hermes-lineage-bench-') as folder:
- db = SessionDB(db_path=Path(folder) / 'state.db')
- try:
- conn = db._conn
- assert conn is not None
- conn.executemany('INSERT INTO sessions(id,source,started_at,end_reason) VALUES(?,?,0,?)', (
- (f's-{i}', 'cli', 'session_reset' if i < args.reset_lineages else None)
- for i in range(args.sessions)))
- conn.executemany('INSERT INTO state_meta(key,value) VALUES(?,?)', (
- (POLICY_PREFIX + f's-{i}', json.dumps({
- 'session_id': f's-{i}',
- 'lineage': [f's-{i}', f's-{args.receipts+i}'] if i < args.reset_lineages else [f's-{i}'],
- 'policy': {'request_json': json.dumps({'prompt': 'x' * args.prompt_bytes})},
- })) for i in range(args.receipts)))
- conn.commit()
- with db._read_ctx() as reader:
- expected = local_lineage_index(reader)
- assert len(expected[0]) == args.reset_lineages
- uncached = measure(lambda: local_lineage_index(reader), args.repeat, expected)
- cold = measure(lambda: _cached_local_lineage_index(db, reader), 1, expected)
- warm = measure(lambda: _cached_local_lineage_index(db, reader), args.repeat, expected)
- scans = []
- reader.set_trace_callback(lambda sql: scans.append(sql) if 'FROM state_meta' in sql and 'GLOB' in sql else None)
- try:
- for _ in range(args.repeat):
- assert _cached_local_lineage_index(db, reader) == expected
- warm_scans = len(scans)
- # Any committed DB write conservatively invalidates, not just receipt writes.
- conn.execute('INSERT INTO state_meta(key,value) VALUES(?,?)', ('benchmark-write', '1'))
- conn.commit()
- invalidated = measure(lambda: _cached_local_lineage_index(db, reader), 1, expected)
- invalidated_scans = len(scans) - warm_scans
- finally:
- reader.set_trace_callback(None)
- assert warm_scans == 0 and invalidated_scans == 1
- print(json.dumps({
- 'workload': vars(args), 'python': platform.python_version(), 'sqlite': sqlite3.sqlite_version,
- 'platform': platform.system(), 'synthetic': True, 'uncached': uncached,
- 'cache_first_read': cold, 'cache_warm': warm, 'after_committed_write': invalidated,
- 'warm_receipt_scans': warm_scans, 'after_write_receipt_scans': invalidated_scans,
- }, indent=2))
- finally:
- db.close()
-
-
-if __name__ == '__main__':
- main()
diff --git a/tests/hermes_state/test_session_list_page_cost.py b/tests/hermes_state/test_session_list_page_cost.py
new file mode 100644
index 00000000000..af0632d0fa3
--- /dev/null
+++ b/tests/hermes_state/test_session_list_page_cost.py
@@ -0,0 +1,74 @@
+"""A recency-ordered session page pays the row projection only for its own rows (#119403).
+
+The sidebar asks ``list_sessions_rich(order_by_last_active=True)`` for a small page of a store
+that can hold tens of thousands of sessions (cron runs). Ranking must look at every admitted
+row, but the projection (``s.*``, the resolved prompt, the preview subquery over message
+content) belongs to the page alone: when it ran for every admitted row before ``LIMIT``, a
+35k-session store took 121 s per sidebar refresh.
+"""
+
+from contextlib import contextmanager
+
+import pytest
+
+from hermes_state import SessionDB
+
+
+def _seed(db: SessionDB, count: int) -> None:
+ for i in range(count):
+ sid = f"s{i:05d}"
+ db.create_session(sid, source="cli")
+ db.append_message(session_id=sid, role="user", content=f"question {i} " + "x" * 400)
+ db.append_message(session_id=sid, role="assistant", content="answer")
+
+
+def _vm_steps(db: SessionDB, limit: int) -> int:
+ """SQLite VM instructions spent by one sidebar-shaped list call."""
+ steps = 0
+
+ def tick() -> int:
+ nonlocal steps
+ steps += 1
+ return 0
+
+ borrow = db._read_ctx
+
+ @contextmanager
+ def counted_read(*, reopen: bool = True):
+ # Whichever connection the read borrows (pooled WAL reader or the DELETE-mode writer).
+ with borrow(reopen=reopen) as conn:
+ conn.set_progress_handler(tick, 1)
+ try:
+ yield conn
+ finally:
+ conn.set_progress_handler(None, 0)
+
+ db._read_ctx = counted_read # type: ignore[method-assign]
+ try:
+ rows = db.list_sessions_rich(order_by_last_active=True, limit=limit, compact_rows=True,
+ min_message_count=1)
+ finally:
+ del db._read_ctx
+ assert len(rows) == limit
+ return steps
+
+
+def stores(tmp_path):
+ small, large = SessionDB(db_path=tmp_path / "small.db"), SessionDB(db_path=tmp_path / "large.db")
+ try:
+ _seed(small, 30)
+ _seed(large, 300)
+ yield small, large
+ finally:
+ small.close()
+ large.close()
+
+
+def test_rows_outside_the_page_are_ranked_but_not_projected(stores):
+ small, large = stores
+ # Cost each extra admitted row adds to a one-row page ...
+ per_row_unprojected = (_vm_steps(large, 1) - _vm_steps(small, 1)) / 270
+ # ... versus a row that is ranked AND projected (every row on the page).
+ per_row_projected = (_vm_steps(large, 300) - _vm_steps(small, 30)) / 270
+ assert per_row_unprojected < 0.7 * per_row_projected, (per_row_unprojected, per_row_projected)