Skip to content

The agent that grows with you

fix(gateway): the live session listings read the store off the loop, one query per batch

Teknium45e7f7dd22bb
diff --git a/gateway/session_active_list.py b/gateway/session_active_list.py
index 2aa7298311f..f55d3acbbe4 100644
--- a/gateway/session_active_list.py
+++ b/gateway/session_active_list.py
@@ -9,9 +9,6 @@ turn that was still running. Rows keep ``server._session_live_item``'s shape; ``
"""
from __future__ import annotations
-import asyncio
-
-from gateway.session_contract import LISTING_YIELD_EVERY, SessionRef
from hermes_state_runtime import RuntimeStoreError
@@ -28,33 +25,20 @@ async def active_list(connection, ref, params):
raise RuntimeStoreError('invalid_params')
if 'session:read' not in connection.actor.capabilities:
raise RuntimeStoreError('permission_denied')
- from gateway.session_local_close import closed_and_unviewed
+ from gateway.session_live_listing import live_entries
from hermes_state_sessions import INTERNAL_LISTING_SOURCES
- authority = connection.authority
current = str(params.get('current_session_id') or '')
rows = []
- for index, (sid, live) in enumerate(tuple(authority.sessions.items())):
- if index and not index % LISTING_YIELD_EVERY:
- # Same reason as ``session.list``: this walks every live session on the loop that also
- # serves the turns' own I/O, so a long list must give it a turn per batch.
- await asyncio.sleep(0)
- candidate = SessionRef(connection.actor.profile_id, sid)
- try:
- handle = await authority.resolve(connection.actor, candidate)
- except RuntimeStoreError as exc:
- if exc.reason not in {'permission_denied', 'profile_mismatch', 'not_found'}:
- raise
- continue
- row = authority.db.get_session_list_row(sid) or {}
+ for entry in await live_entries(connection.authority, connection.actor):
+ row = entry.row
# The same population as the live ``session.list`` feed, hidden chats included: a hidden
# chat open in a pane still needs its turn's liveness.
- if row.get('source') in INTERNAL_LISTING_SOURCES or closed_and_unviewed(authority, sid, handle):
+ if row.get('source') in INTERNAL_LISTING_SOURCES or entry.closed:
continue
- started = float(row.get('started_at') or 0)
+ sid, started = entry.session_id, float(row.get('started_at') or 0)
rows.append({'current': sid == current, 'id': sid, 'session_key': sid,
'last_active': float(row.get('ended_at') or started), 'started_at': started,
'message_count': int(row.get('message_count') or 0),
'model': str(row.get('model') or ''), 'preview': '', 'title': row.get('title') or '',
- 'source': row.get('source'),
- 'status': _status(live, handle, authority._pending_rows(candidate))})
+ 'source': row.get('source'), 'status': _status(entry.live, entry.handle, entry.pending)})
return {'sessions': rows}
diff --git a/gateway/session_contract.py b/gateway/session_contract.py
index 8fb7697a7d9..dda3763a395 100644
--- a/gateway/session_contract.py
+++ b/gateway/session_contract.py
@@ -8,11 +8,6 @@ JsonObject = Mapping[str, object]
# Authenticated local WebSocket family, separate from the legacy Desktop API contract.
CANONICAL_GATEWAY_PROTOCOL = 'hermes-gateway-v1'
-# The live listings (`session.list`, `session.active_list`) walk every live session in one request
-# on the gateway's loop, the thread that also serves platform I/O, WS dispatch and delivery. Yield
-# this often so a long list interleaves instead of holding the thread for its whole duration.
-LISTING_YIELD_EVERY = 64
-
@dataclass(frozen=True)
class Principal:
diff --git a/gateway/session_controls.py b/gateway/session_controls.py
index 8b16b3c36b6..15b3847284c 100644
--- a/gateway/session_controls.py
+++ b/gateway/session_controls.py
@@ -9,8 +9,7 @@ import sqlite3
import uuid
from gateway.config import Platform
-from gateway.session_contract import (
- CANONICAL_GATEWAY_PROTOCOL, LISTING_YIELD_EVERY, Principal, SessionRef, Submission)
+from gateway.session_contract import CANONICAL_GATEWAY_PROTOCOL, Principal, SessionRef, Submission
from gateway.session_llm_oneshot import DeferredReply
from hermes_constants import profile_name_for_home
from hermes_state_runtime import RuntimeStoreError
@@ -540,34 +539,20 @@ class AuthorityConnection:
'running': found.session_id in self.authority.sessions}],
'scope': 'stored'}
from hermes_state_sessions import INTERNAL_LISTING_SOURCES
+ from gateway.session_live_listing import live_entries
sessions = []
- for index, sid in enumerate(tuple(self.authority.sessions)):
- if index and not index % LISTING_YIELD_EVERY:
- # A few thousand live rows must not hold the loop: platform I/O, the adapter's stop
- # path and WS writes share this thread, and a stall there reads as their own failure.
- await asyncio.sleep(0)
- candidate = SessionRef(self.actor.profile_id, sid)
- try:
- handle = await self.authority.resolve(self.actor, candidate)
- except RuntimeStoreError as exc:
- if exc.reason not in {'permission_denied', 'profile_mismatch', 'not_found'}:
- raise
- continue
- row = self.authority.db.get_session_list_row(sid) or {}
+ for entry in await live_entries(self.authority, self.actor):
+ row = entry.row
# The human picker feed (TUI switcher): kanban workers, `--source tool` integrations and
- # finite one-shot runs are not conversations, as on every other picker.
- if row.get('source') in INTERNAL_LISTING_SOURCES or (
+ # finite one-shot runs are not conversations, as on every other picker. Closed by its last
+ # viewer and idle: main lists it as resumable (the stored feed), not as a live session.
+ if row.get('source') in INTERNAL_LISTING_SOURCES or entry.closed or (
not params.get('include_hidden') and (row.get('hidden') or row.get('archived'))):
continue
- from gateway.session_local_close import closed_and_unviewed
- if closed_and_unviewed(self.authority, sid, handle):
- # Closed by its last viewer and idle: main lists it as resumable (the stored
- # feed), not as a live session.
- continue
- sessions.append({'session_id': sid, 'id': sid, 'title': row.get('title') or '',
+ sessions.append({'session_id': entry.session_id, 'id': entry.session_id, 'title': row.get('title') or '',
'source': row.get('source'), 'started_at': row.get('started_at'),
'message_count': row.get('message_count', 0), 'model': row.get('model'),
- 'running': handle.execution_state == 'running'})
+ 'running': entry.handle.execution_state == 'running'})
sessions.sort(key=lambda row: row['started_at'] or 0, reverse=True)
return {'sessions': sessions[:limit], 'scope': 'live'}
diff --git a/gateway/session_live_listing.py b/gateway/session_live_listing.py
new file mode 100644
index 00000000000..c474232daa3
--- /dev/null
+++ b/gateway/session_live_listing.py
@@ -0,0 +1,108 @@
+"""The live session feeds (``session.list`` live scope, ``session.active_list``) read off the loop.
+
+Both feeds cover every session in ``authority.sessions``, and a gateway restart refills that registry
+from receipts, so it can hold thousands of rows (mostly finished cron runs). Walking it one row at a
+time on the loop cost three full hydrations plus a receipt JSON parse per session: the loop stalled
+past 10 s, WS writes and the Telegram adapter's ``updater.stop()`` missed their deadlines (#141236).
+
+Here the loop does only in-memory work (authorization and liveness from ``LiveSession``); the store
+facts for a batch of sessions are ONE worker-thread read: picker columns, runtime revision and
+generation, pending admissions, and the local receipt target's ``ended_at``.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass
+
+from gateway.session_contract import SessionHandle, SessionRef
+from hermes_state_runtime import RuntimeStoreError
+
+# Sessions per worker-thread read; each batch is one await, so the loop serves other work between them.
+LISTING_BATCH = 256
+
+_SKIPPED_REASONS = frozenset({'permission_denied', 'profile_mismatch', 'not_found'})
+
+
+@dataclass(frozen=True)
+class LiveEntry:
+ session_id: str
+ live: object
+ handle: SessionHandle
+ row: dict
+ pending: list
+ closed: bool
+
+
+def _store_facts(db, session_ids):
+ """Worker thread: ``{sid: row}`` and ``{sid: [pending admission]}`` for *session_ids*, in two reads.
+
+ ``target_ended_at`` is the local receipt target's ``ended_at`` (``closed_and_unviewed``'s read):
+ SQLite extracts the target from the receipt, so no receipt is parsed in Python. A malformed or
+ non-local receipt reads as no target, as ``_local_target`` does."""
+ from hermes_state_local import POLICY_PREFIX
+ ids = json.dumps(list(session_ids))
+ with db._read_ctx() as conn:
+ rows = conn.execute(
+ "SELECT s.id, s.source, s.title, s.started_at, s.ended_at, s.message_count, s.model, s.hidden, "
+ "s.archived, s.runtime_revision, s.runtime_generation, "
+ "(SELECT t.ended_at FROM state_meta m JOIN sessions t ON t.id = CASE WHEN json_valid(m.value) "
+ "THEN json_extract(m.value, '$.entry.session_id') END WHERE m.key = ? || s.id) AS target_ended_at "
+ "FROM sessions s WHERE s.id IN (SELECT value FROM json_each(?))", (POLICY_PREFIX, ids)).fetchall()
+ pending = conn.execute(
+ "SELECT target_session_id, admission_id, seq, status FROM session_admissions "
+ "WHERE target_session_id IN (SELECT value FROM json_each(?)) "
+ "AND status IN ('queued','started','unknown') ORDER BY seq", (ids,)).fetchall()
+ by_session: dict[str, list] = {}
+ for row in pending:
+ by_session.setdefault(row['target_session_id'], []).append(dict(row))
+ return {row['id']: dict(row) for row in rows}, by_session
+
+
+def _masked_pending(live, rows):
+ """``SessionAuthority._pending_rows``: a settlement not yet published still reads as its started claim."""
+ if not live.settling:
+ return rows
+ merged = {row['admission_id']: row for row in rows}
+ merged.update(live.settling)
+ return sorted(merged.values(), key=lambda row: row['seq'])
+
+
+def _execution_state(pending) -> str:
+ statuses = {row['status'] for row in pending}
+ return 'unknown' if 'unknown' in statuses else ('running' if 'started' in statuses else 'idle')
+
+
+def _readable(authority, actor, session_id) -> bool:
+ if session_id not in authority.sessions:
+ return False # retired since the snapshot: a listing never restores a session
+ try:
+ authority.authorize(actor, SessionRef(actor.profile_id, session_id), 'session:read')
+ except RuntimeStoreError as exc:
+ if exc.reason not in _SKIPPED_REASONS:
+ raise
+ return False
+ return True
+
+
+async def live_entries(authority, actor) -> list[LiveEntry]:
+ """Every live session *actor* may read, with its handle, picker row and closed-and-unviewed verdict."""
+ from gateway.session_local_close import closed_idle_unviewed
+ entries = []
+ snapshot = tuple(authority.sessions)
+ for start in range(0, len(snapshot), LISTING_BATCH):
+ batch = [sid for sid in snapshot[start:start + LISTING_BATCH] if _readable(authority, actor, sid)]
+ if not batch:
+ continue
+ rows, pending = await asyncio.to_thread(_store_facts, authority.db, batch)
+ for sid in batch:
+ live, row = authority.sessions.get(sid), rows.get(sid)
+ if live is None or row is None:
+ continue # retired during the read, or its row was deleted (``_handle``'s not_found)
+ masked = _masked_pending(live, pending.get(sid, []))
+ state = _execution_state(masked)
+ handle = SessionHandle(SessionRef(authority.profile_id, sid), authority.instance_id, authority.epoch,
+ row['runtime_revision'], row['runtime_generation'], state)
+ entries.append(LiveEntry(sid, live, handle, row, masked,
+ closed_idle_unviewed(live, state, row['target_ended_at'])))
+ return entries
diff --git a/gateway/session_local_close.py b/gateway/session_local_close.py
index 156902f628b..d8643d836e1 100644
--- a/gateway/session_local_close.py
+++ b/gateway/session_local_close.py
@@ -16,17 +16,23 @@ def _local_target(authority, session_id):
return None # not a local session (API binding, malformed receipt): nothing to read as closed
-def closed_and_unviewed(authority, session_id, handle):
- """A live-feed row main would list as resumable: closed, idle and with no viewer left.
+def closed_idle_unviewed(live, execution_state, target_ended_at):
+ """The verdict on facts already read: the live listings read ``target_ended_at`` for a whole batch
+ in one off-loop query (``gateway/session_live_listing``)."""
+ if live is None or live.subscribers or execution_state != 'idle':
+ return False
+ if live.superseded:
+ return True # an old messaging conversation opened read-only: history once no one views it
+ return target_ended_at is not None
- Reads the local target's own columns rather than hydrating the row: the listing asks this per
- session on the gateway's loop, where a ``get_session`` (prompt/tool JOIN + token flush) per
- candidate is the cost the sweep must not pay."""
+
+def closed_and_unviewed(authority, session_id, handle):
+ """A live-feed row main would list as resumable: closed, idle and with no viewer left."""
live = authority.sessions.get(session_id)
if live is None or live.subscribers or handle.execution_state != 'idle':
return False
if live.superseded:
- return True # an old messaging conversation opened read-only: history once no one views it
+ return True
target = _local_target(authority, session_id)
row = authority.db.get_session_list_row(target) if target else None
- return bool(row and row.get('ended_at') is not None)
+ return closed_idle_unviewed(live, handle.execution_state, row and row.get('ended_at'))
diff --git a/tests/gateway/test_authority_listing_loop_turns.py b/tests/gateway/test_authority_listing_loop_turns.py
index 932942313b9..328f00fb9ea 100644
--- a/tests/gateway/test_authority_listing_loop_turns.py
+++ b/tests/gateway/test_authority_listing_loop_turns.py
@@ -1,25 +1,22 @@
-"""The live listings walk every live session, on the loop the gateway serves I/O from.
-
-A gateway can hold thousands of live session rows; ``session.list`` / ``session.active_list`` walk
-the authority's sessions in one request, and every step of that walk was synchronous DB work with
-no suspension point, so the whole listing ran as one uninterruptible block on the loop thread.
-Anything that needed the loop meanwhile — a platform adapter's stop path, a WS write, delivery —
-waited for it; measured on a 4,049-row store the loop stalled past 10 s, the Telegram adapter's
-``updater.stop()`` missed its deadline and the adapter was declared fatal (#141236).
-
-These tests pin the two properties the sweep needs: it gives the loop a turn every batch, and it
-reads the picker's own columns instead of hydrating a full row (prompt/tool JOIN + token flush)
-per session.
+"""The live listings walk every live session; their store reads must not run on the gateway's loop.
+
+A gateway can hold thousands of live session rows (a restart refills the registry from receipts);
+``session.list`` / ``session.active_list`` walked them one at a time on the loop thread, with three
+full hydrations and a receipt JSON parse per session and no suspension point. Measured on a
+4,049-row store the loop stalled past 10 s, the Telegram adapter's ``updater.stop()`` missed its
+deadline and the adapter was declared fatal (#141236).
+
+Pinned here: the loop gets a turn while a listing is in flight, no store read of the walk runs on the
+loop thread, the reads are batched (not one per session), and the closed-and-unviewed rule is kept.
"""
import asyncio
+import threading
from types import SimpleNamespace
import pytest
import pytest_asyncio
-from gateway.session_contract import SessionRef
-
-SESSION_COUNT = 130 # more than one LISTING_YIELD_EVERY batch
+SESSION_COUNT = 300 # more than one LISTING_BATCH
@pytest_asyncio.fixture
@@ -47,95 +44,81 @@ async def owner(tmp_path, monkeypatch):
assert 'result' in reply, reply
return reply['result']['sessions']
- yield SimpleNamespace(authority=authority, db=store._db, sids=sids, listing=listing,
- connection=connection)
+ yield SimpleNamespace(authority=authority, db=store._db, sids=sids, listing=listing)
-async def test_the_live_listing_gives_the_loop_a_turn_before_it_returns(owner):
- """A listing must not hold the loop for the whole walk: another task runs while it is in flight."""
- order = []
+def _count_reads_by_thread(monkeypatch, db):
+ """Every read connection checkout the walk makes, keyed by whether it ran on the loop thread."""
+ loop_thread = threading.get_ident()
+ reads = {'loop': 0, 'worker': 0}
+ original = type(db)._read_ctx
- async def sweep():
- await owner.listing('session.list', limit=200)
- order.append('listing')
+ def counting(self, *args, **kwargs):
+ reads['loop' if threading.get_ident() == loop_thread else 'worker'] += 1
+ return original(self, *args, **kwargs)
- async def competing():
- order.append('competing')
+ monkeypatch.setattr(type(db), '_read_ctx', counting)
+ return reads
- # Scheduled in this order, so an unyielding sweep appends first and the loop only gets the
- # competing task after the whole walk.
- await asyncio.gather(sweep(), competing())
- assert order == ['competing', 'listing'], order
+
[email protected]('method', ['session.list', 'session.active_list'])
+async def test_a_live_listing_reads_the_store_off_the_loop_in_batches(owner, monkeypatch, method):
+ reads = _count_reads_by_thread(monkeypatch, owner.db)
+ rows = await owner.listing(method)
+ assert len(rows) == (200 if method == 'session.list' else SESSION_COUNT)
+ assert reads['loop'] == 0, reads
+ # One worker read per batch, never one per session.
+ assert 0 < reads['worker'] < SESSION_COUNT // 10, reads
@pytest.mark.asyncio
-async def test_the_active_listing_gives_the_loop_a_turn_before_it_returns(owner):
[email protected]('method', ['session.list', 'session.active_list'])
+async def test_a_live_listing_gives_the_loop_a_turn_before_it_returns(owner, method):
order = []
async def sweep():
- await owner.listing('session.active_list')
+ await owner.listing(method)
order.append('listing')
async def competing():
order.append('competing')
+ # Scheduled in this order, so an unyielding sweep appends first.
await asyncio.gather(sweep(), competing())
assert order == ['competing', 'listing'], order
@pytest.mark.asyncio
-async def test_the_live_listing_does_not_hydrate_a_row_per_session(owner, monkeypatch):
- """``get_session`` is a full hydration; the walk needs columns, not the row."""
- hydrated = []
- original = type(owner.db).get_session
-
- def counting_get_session(db, session_id):
- hydrated.append(session_id)
- return original(db, session_id)
-
- monkeypatch.setattr(type(owner.db), 'get_session', counting_get_session)
- rows = await owner.listing('session.list', limit=200)
- assert len(rows) == SESSION_COUNT
- # One hydration per session is ``resolve``/``_handle``'s own read (it needs the runtime
- # revision/generation). The listing's own reads must not add any.
- assert len(hydrated) <= SESSION_COUNT, (len(hydrated), SESSION_COUNT)
-
-
-def test_closed_and_unviewed_reads_the_row_without_hydrating(monkeypatch):
- """The per-candidate close test reads ``ended_at``, and must not hydrate the whole row."""
- from gateway import session_local_close
-
- monkeypatch.setattr(session_local_close, 'local_receipt',
- lambda db, session_id: {'entry': {'session_id': 'target'}})
-
- class Db:
- def __init__(self):
- self.hydrated = []
-
- def get_session(self, session_id):
- self.hydrated.append(session_id)
- return {'id': session_id, 'ended_at': 1.0}
-
- def get_session_list_row(self, session_id):
- return {'id': session_id, 'ended_at': 1.0}
-
- db = Db()
- authority = SimpleNamespace(sessions={'live-1': SimpleNamespace(subscribers={})}, db=db)
- handle = SimpleNamespace(execution_state='idle')
- assert session_local_close.closed_and_unviewed(authority, 'live-1', handle) is True
- assert db.hydrated == []
-
-
-def test_closed_and_unviewed_keeps_an_open_row_listed(monkeypatch):
- """The light read keeps the rule: an open target is listed, a closed one is not."""
- from gateway import session_local_close
-
- monkeypatch.setattr(session_local_close, 'local_receipt',
- lambda db, session_id: {'entry': {'session_id': 'target'}})
- authority = SimpleNamespace(
- sessions={'live-1': SimpleNamespace(subscribers={})},
- db=SimpleNamespace(get_session_list_row=lambda session_id: {'id': session_id, 'ended_at': None},
- get_session=lambda session_id: {'id': session_id, 'ended_at': None}))
- assert session_local_close.closed_and_unviewed(
- authority, 'live-1', SimpleNamespace(execution_state='idle')) is False
+async def test_a_closed_unviewed_local_session_still_leaves_the_live_feed(owner):
+ """The batched read keeps ``closed_and_unviewed``: a local session whose receipt target is ended
+ and that nobody views is listed as resumable (stored feed), not live; an open one stays live."""
+ import json
+ from hermes_state_local import POLICY_PREFIX
+ closed, open_ = owner.sids[0], owner.sids[1]
+ owner.db.create_session('target-closed', source='tui')
+ owner.db.create_session('target-open', source='tui')
+ owner.db.end_session('target-closed', 'tui_close')
+ for sid, target in ((closed, 'target-closed'), (open_, 'target-open')):
+ owner.db.set_meta(POLICY_PREFIX + sid, json.dumps({'entry': {'session_id': target}}))
+ owner.db.set_meta(POLICY_PREFIX + owner.sids[2], '{not json')
+ with owner.db._lock: # newest, so session.list's 200-row window holds all three
+ owner.db._conn.execute('UPDATE sessions SET started_at = 9e9 WHERE id IN (?,?,?)', owner.sids[:3])
+ for method in ('session.list', 'session.active_list'):
+ ids = {row['id'] for row in await owner.listing(method)}
+ assert closed not in ids and open_ in ids and owner.sids[2] in ids, method
+
+
+async def test_a_session_retired_during_the_read_is_not_listed_or_restored(owner, monkeypatch):
+ from gateway import session_live_listing
+ original = session_live_listing._store_facts
+ gone = owner.sids[5]
+
+ def retire_midway(db, ids):
+ owner.authority.sessions.pop(gone, None)
+ return original(db, ids)
+
+ monkeypatch.setattr(session_live_listing, '_store_facts', retire_midway)
+ ids = {row['id'] for row in await owner.listing('session.active_list')}
+ assert gone not in ids and gone not in owner.authority.sessions