Skip to content

The agent that grows with you

fix(state): let a swept caller-named API session id age out

David Dudok de Witf62b8f2003ac
diff --git a/gateway/platforms/api_server.py b/gateway/platforms/api_server.py
index b5a4a6387f9..f111dfdd018 100644
--- a/gateway/platforms/api_server.py
+++ b/gateway/platforms/api_server.py
@@ -4165,7 +4165,7 @@ class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):
session_history_delivery: str = "", turn_author: Optional[dict[str, Any]] = None,
relay_metadata: Optional[dict[str, Any]] = None, notification_category: str = "result",
resume_unanswered_turn: bool = False, approval_notify_callback=None,
- approval_session_key: Optional[str] = None) -> tuple:
+ approval_session_key: Optional[str] = None, walked_from: Optional[str] = None) -> tuple:
"""Create an agent and run one turn in a thread executor -> ``(result, usage)``.
``approval_notify_callback`` (with ``approval_session_key``) routes dangerous-command
approval requests to the caller's stream, keyed like ``/v1/runs`` approvals (#51871).
@@ -4187,7 +4187,7 @@ class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):
stream_delta_callback=stream_delta_callback, tool_progress_callback=tool_progress_callback,
tool_start_callback=tool_start_callback, tool_complete_callback=tool_complete_callback,
interim_assistant_callback=interim_assistant_callback, reasoning_callback=reasoning_callback,
- status_callback=status_callback,
+ status_callback=status_callback, walked_from=walked_from,
agent_ref=agent_ref, active_run_id=active_run_id, gateway_session_key=gateway_session_key,
requested_model=requested_model, requested_provider=requested_provider, model_options=model_options,
route=route, session_model=session_model, requested_runtime=requested_runtime,
diff --git a/gateway/platforms/api_server_memory_sessions.py b/gateway/platforms/api_server_memory_sessions.py
index 7dcf75e6591..2addb389353 100644
--- a/gateway/platforms/api_server_memory_sessions.py
+++ b/gateway/platforms/api_server_memory_sessions.py
@@ -32,7 +32,8 @@ class ApiServerMemorySessions:
"""Session-keyed ``MemoryManager`` registry with exclusive check-out/check-in."""
def __init__(self, *, max_size: Optional[int] = None, idle_ttl_secs: Optional[float] = None) -> None:
- self._entries: OrderedDict[tuple[str, str], tuple[Any, Optional[Path], float]] = OrderedDict()
+ # (manager, owning home, last check-in on the monotonic clock, the same on the wall clock)
+ self._entries: OrderedDict[tuple[str, str], tuple[Any, Optional[Path], float, float]] = OrderedDict()
self._lock = threading.Lock()
self._max_size = max_size
self._idle_ttl_secs = idle_ttl_secs
@@ -63,13 +64,22 @@ class ApiServerMemorySessions:
# -- check-out / check-in ----------------------------------------------------------------
def checkout(self, session_id: Optional[str]) -> Optional[Any]:
- """The manager a previous request on ``session_id`` checked in, or None (build a new one)."""
+ """The manager a previous request on ``session_id`` checked in, or None (build a new one).
+ One checked in before the retry horizon is shut down instead: a housekeeping sweep's fence
+ on an id ages out at that horizon, so the id may now name a new session, which must not
+ get its previous session's recall."""
if not session_id:
return None
home_key, _home = self._owner_home()
with self._lock:
entry = self._entries.pop((home_key, session_id), None)
- return entry[0] if entry else None
+ if entry is None:
+ return None
+ from hermes_state_mutation_retirement import RETRY_HORIZON_S
+ if time.time() - entry[3] > RETRY_HORIZON_S:
+ self._shutdown_async(entry[0], entry[1])
+ return None
+ return entry[0]
def checkin(self, agent: Any) -> None:
"""Park ``agent``'s manager under the session the turn ended on (``agent.session_id`` carries a
@@ -86,8 +96,8 @@ class ApiServerMemorySessions:
displaced = self._entries.pop((home_key, session_id), None)
if displaced is not None and displaced[0] is not manager:
doomed.append((displaced[0], displaced[1]))
- self._entries[(home_key, session_id)] = (manager, home, now)
- for key, (mgr, owner, last_used) in list(self._entries.items()):
+ self._entries[(home_key, session_id)] = (manager, home, now, time.time())
+ for key, (mgr, owner, last_used, _wall) in list(self._entries.items()):
if mgr is manager:
continue
if now - last_used > idle_ttl or len(self._entries) > max_size:
@@ -101,7 +111,7 @@ class ApiServerMemorySessions:
with self._lock:
entries = list(self._entries.values())
self._entries.clear()
- for mgr, owner, _ in entries:
+ for mgr, owner, *_ in entries:
self._shutdown(mgr, owner)
# -- teardown -------------------------------------------------------------------------------
diff --git a/gateway/platforms/api_server_response_admissions.py b/gateway/platforms/api_server_response_admissions.py
index 0cc7273e0e4..26c91e742ec 100644
--- a/gateway/platforms/api_server_response_admissions.py
+++ b/gateway/platforms/api_server_response_admissions.py
@@ -141,16 +141,16 @@ async def prepare_context(adapter, request, body, gateway_session_key, durable_k
history, error = _parse_conversation_history(body['conversation_history'])
if error is not None:
return None, error
- stored_session_id = None
+ stored_session_id = chain_root = None
instructions = body.get('instructions')
if not history and previous:
stored = adapter._current_response_store().get(previous)
if stored is None:
return None, _error_response(f'Previous response not found: {previous}', 404)
history = list(stored.get('conversation_history', []))
- stored_session_id = await asyncio.to_thread(_stored_owner, adapter, stored.get('session_id'))
+ chain_root = await asyncio.to_thread(_stored_owner, adapter, stored.get('session_id'))
from gateway.platforms.api_server_authority_runs import continued_session
- stored_session_id, error = await continued_session(adapter, stored_session_id, request_id)
+ stored_session_id, error = await continued_session(adapter, chain_root, request_id)
if error is not None:
return None, error
if instructions is None:
@@ -175,6 +175,8 @@ async def prepare_context(adapter, request, body, gateway_session_key, durable_k
ephemeral_system_prompt=instructions, session_id=session_id,
gateway_session_key=gateway_session_key, bind_declared_conversation=declared_selected,
**overrides, route=route, relay_metadata=_request_relay_metadata(body))
+ if stored_session_id and stored_session_id != chain_root:
+ run_kwargs['walked_from'] = chain_root # the chain moved past its swept stored session
if durable_key:
return await _admit(adapter, durable_key, request_id, request_binding(adapter, request, durable_key),
run_kwargs, body.get('model', adapter._model_name)), None
diff --git a/gateway/platforms/api_server_runs.py b/gateway/platforms/api_server_runs.py
index 2c8a8ee137b..39c7e15dae2 100644
--- a/gateway/platforms/api_server_runs.py
+++ b/gateway/platforms/api_server_runs.py
@@ -484,13 +484,16 @@ def _resolve_conversation_history(
async def _resolve_chained_history(self, body: dict, raw_input: Any, *, _openai_error):
"""``_resolve_conversation_history`` with the chain's live session: a deleted chain moves to
its next generation (an explicit body ``session_id`` still wins in the caller), and a store
- that cannot answer is the retryable store verdict (``continued_session``)."""
+ that cannot answer is the retryable store verdict (``continued_session``). The last item is the
+ stored session the chain moved past (``walked_from``), else None."""
from gateway.platforms.api_server_authority_runs import continued_session
- history, instructions, stored_session_id, error = _resolve_conversation_history(
+ history, instructions, chain_root, error = _resolve_conversation_history(
self, body, raw_input, _openai_error=_openai_error)
+ stored_session_id = chain_root
if error is None:
- stored_session_id, error = await continued_session(self, stored_session_id)
- return history, instructions, stored_session_id, error
+ stored_session_id, error = await continued_session(self, chain_root)
+ return history, instructions, stored_session_id, error, (
+ chain_root if stored_session_id and stored_session_id != chain_root else None)
def _accepted_response(run_id: str, status: str, gateway_session_key, *, replayed: bool) -> web.Response:
@@ -537,6 +540,7 @@ class _RunLaunch:
browser_control_transport_family: Any
turn_author: Optional[dict[str, Any]] = None # memory-attribution label only; grants nothing
admission: Any = None
+ walked_from: Optional[str] = None # the swept stored session the chain moved past (``bind_api_steps``)
@property
def approval_session_key(self) -> str:
@@ -693,7 +697,7 @@ async def _admit_run_to_authority(
turn_author=launch.turn_author,
history_from_session=session_history_delivery,
session_history_delivery='1' if session_history_delivery else '',
- bind_declared_conversation=_declared_selected,
+ bind_declared_conversation=_declared_selected, walked_from=launch.walked_from,
**launch.agent_kwargs)
except Exception as exc: # health: allow BLE001 -- answered below; a committed admission is kept
# A storage failure after the admission committed (a later media-release write) still
@@ -746,7 +750,7 @@ async def _handle_runs(self, request: web.Request, *, _api_server) -> web.Respon
turn_author = _api_server._request_turn_author(body)
except ValueError as exc:
return _json_error(_openai_error, str(exc), code="invalid_author", status=400)
- conversation_history, instructions, stored_session_id, history_err = await _resolve_chained_history(
+ conversation_history, instructions, stored_session_id, history_err, walked_from = await _resolve_chained_history(
self, body, raw_input, _openai_error=_openai_error)
if history_err is not None:
return history_err
@@ -824,7 +828,7 @@ async def _handle_runs(self, request: web.Request, *, _api_server) -> web.Respon
request_profile=_api_server._api_request_profile.get(),
browser_control_principal=_api_server._api_request_browser_control_principal.get(),
browser_control_transport_family=_api_server._api_request_browser_control_transport_family.get(),
- turn_author=turn_author)
+ turn_author=turn_author, walked_from=walked_from if session_id == stored_session_id else None)
# A canonical Bot Chat that a Desktop holds live is that Desktop's to run: executing here would
# be a second writer beside its lease (#114959). The owner's mailbox takes the turn and its
# receipt drives this run's status, so `peer run` keeps its run_id and `peer status` still works.
diff --git a/gateway/session_api.py b/gateway/session_api.py
index 93ca7493233..78f300cbd74 100644
--- a/gateway/session_api.py
+++ b/gateway/session_api.py
@@ -37,8 +37,15 @@ def implicit_api_session(db, session_id, request_id=None):
from hermes_state_terminal import identity_key
pinned = None if not request_id else lambda conn, sid: conn.execute(
'SELECT 1 FROM state_meta WHERE key=?', (identity_key('api', sid, request_id),)).fetchone() is not None
- derive = lambda n: session_id if n == 0 else 'api-' + hashlib.sha256(f'{session_id}\0{n}'.encode()).hexdigest()[:16]
- return first_generation(db, derive, pinned=pinned)[1]
+ return first_generation(db, partial(api_generation_id, session_id), pinned=pinned)[1]
+
+
+def api_generation_id(session_id, generation):
+ """Generation *generation* of an API session id ``implicit_api_session`` walks: the id itself,
+ then ``api-<digest(id, n)>``."""
+ if not generation:
+ return session_id
+ return 'api-' + hashlib.sha256(f'{session_id}\0{generation}'.encode()).hexdigest()[:16]
def continued_api_session(runner, session_id, request_id=None):
@@ -132,19 +139,24 @@ async def run_steps_off_loop(authority, steps, *, orphaned=None):
raise
-def bind_api_session(authority, session_id, *, hosted_dispatch=None, declared_key=None, caller_key=None):
+def bind_api_session(authority, session_id, *, hosted_dispatch=None, declared_key=None, caller_key=None,
+ walked_from=None):
"""Only the authenticated API edge may reserve an API source; never public RPC."""
return run_steps(bind_api_steps(authority, session_id, hosted_dispatch=hosted_dispatch,
- declared_key=declared_key, caller_key=caller_key))
+ declared_key=declared_key, caller_key=caller_key, walked_from=walked_from))
-def bind_api_steps(authority, session_id, *, hosted_dispatch=None, declared_key=None, caller_key=None):
+def bind_api_steps(authority, session_id, *, hosted_dispatch=None, declared_key=None, caller_key=None,
+ walked_from=None):
"""``bind_api_session`` as write steps (``run_steps``): the binding transaction is yielded.
``caller_key`` is this request's validated ``X-Hermes-Session-Key`` even when an explicit
session id selected the conversation (``declared_key`` is set only when the key selected it).
It is used only to adopt a row an earlier release stamped with that same key, and is then
- registered as that session's declared key (and stamped into its binding receipt)."""
+ registered as that session's declared key (and stamped into its binding receipt).
+
+ ``walked_from`` is the stored session a Responses/Runs chain continued from when the chain moved
+ past it to *session_id* (``continued_api_session``): the fences it passed stay for good."""
authority._require_admission_open()
if not isinstance(session_id, str) or not session_id or _is_path_unsafe(session_id):
raise RuntimeStoreError('invalid_params')
@@ -186,9 +198,11 @@ def bind_api_steps(authority, session_id, *, hosted_dispatch=None, declared_key=
def write(conn):
_epoch(conn, authority.epoch)
authority._require_admission_open() # a drain that began while this waited on the writer wins
- from hermes_state_mutation_retirement import RETIRED_PREFIX
+ from hermes_state_mutation_retirement import RETIRED_PREFIX, keep_passed_fences
if conn.execute('SELECT 1 FROM state_meta WHERE key=?', (RETIRED_PREFIX + session_id,)).fetchone():
raise RuntimeStoreError('not_found')
+ if walked_from:
+ keep_passed_fences(conn, partial(api_generation_id, walked_from), session_id)
saved = conn.execute('SELECT value FROM state_meta WHERE key=?',
(_BINDING_PREFIX + session_id,)).fetchone()
if saved is not None:
diff --git a/gateway/session_api_turn.py b/gateway/session_api_turn.py
index e9df4d12549..c0bc81d480c 100644
--- a/gateway/session_api_turn.py
+++ b/gateway/session_api_turn.py
@@ -258,7 +258,7 @@ def _admit_api_payload(authority, adapter, sid, request_id, payload, settings, d
from gateway.session_contract import SessionRef
return authority, SessionRef(authority.profile_id, sid), row
ref = yield from bind_api_steps(authority, sid, hosted_dispatch=kwargs.get("room_dispatch"), declared_key=declared_key,
- caller_key=kwargs.get('gateway_session_key'))
+ caller_key=kwargs.get('gateway_session_key'), walked_from=kwargs.get('walked_from'))
check_api_turn(authority, ref, payload)
row = yield partial(admit_session_input, authority.db, epoch=authority.epoch, principal_id='api',
session_id=sid, request_id=request_id, payload=payload,
diff --git a/hermes_state_mutation_retirement.py b/hermes_state_mutation_retirement.py
index 3c605b6873f..5c826f0380c 100644
--- a/hermes_state_mutation_retirement.py
+++ b/hermes_state_mutation_retirement.py
@@ -46,6 +46,18 @@ def first_generation(db, derive, *, pinned=None, spent=None):
generation += 1
+def keep_passed_fences(conn, derive, session_id):
+ """Make permanent the fences a walk (``derive`` as for :func:`first_generation`) passed on its
+ way to *session_id*, inside the write that binds *session_id*: that successor now holds the
+ conversation, so a sweep marker aging out would send a later walk back to the passed
+ generation. Stops at *session_id* or at the first generation without a marker."""
+ generation = 0
+ while (sid := derive(generation)) != session_id and conn.execute(
+ "UPDATE state_meta SET value=json_remove(value, '$.expires') WHERE key=? AND json_valid(value)",
+ (RETIRED_PREFIX + sid,)).rowcount:
+ generation += 1
+
+
def has_mutation_receipt(db, principal_id, session_id, request_id):
for value in (principal_id, session_id, request_id):
_text(value)
@@ -170,9 +182,13 @@ def retire_mutation_receipts(conn, session_ids):
# Creation ids of the local conversations a gateway door derives and walks by generation
# (``first_generation``): Bot Chat and A2A contexts.
_DERIVED_LOCAL_PREFIXES = ('bot-chat:', 'a2a:')
-# Stored sources of the API sessions whose ids a door derives: the header-less chat and a
-# Responses/Runs chain (``api_server``) and a hosted-room member (``bot_room``).
-_DERIVED_SOURCES = ('api_server', 'bot_room')
+# The API sessions whose ids a door derives: a hosted-room member (``bot_room``), and the
+# ``api-<16 hex>`` ids of a header-less chat (``_derive_chat_session_id``) and of a deleted chat's or
+# Responses/Runs chain's next generation (``implicit_api_session``). A caller-named ``api_server`` id
+# (``POST /api/sessions``, ``X-Hermes-Session-Id``) is never derived. Matched on the id, not on a
+# binding-receipt field, so it also holds for rows an older release bound. Any id can root a
+# Responses/Runs chain: its fence becomes permanent once a chain moves past it (``keep_passed_fences``).
+_DERIVED_API_SQL = ("(source='bot_room' OR (source='api_server' AND id GLOB 'api-" + '[0-9a-f]' * 16 + "'))")
def _local_conversations(conn):
@@ -199,10 +215,10 @@ def _local_conversations(conn):
def _derived_api_sessions(conn, session_ids):
- """The ids among *session_ids* whose stored source is a derived API session's."""
+ """The ids among *session_ids* of derived API sessions (``_DERIVED_API_SQL``)."""
return {row[0] for row in conn.execute(
- f"SELECT id FROM sessions WHERE source IN ({','.join('?' * len(_DERIVED_SOURCES))}) "
- "AND id IN (SELECT value FROM json_each(?))", (*_DERIVED_SOURCES, json.dumps(list(session_ids))))}
+ f"SELECT id FROM sessions WHERE {_DERIVED_API_SQL} AND id IN (SELECT value FROM json_each(?))",
+ (json.dumps(list(session_ids)),))}
def retire_prunable(conn, session_ids):
@@ -214,10 +230,11 @@ def retire_prunable(conn, session_ids):
A sweep's markers age out at the retry horizon: housekeeping retires thousands of ids a pass
(cron), and a permanent marker each would grow ``state_meta`` without bound. A derived id's
- stays (Bot Chat, A2A context, header-less chat, Responses chain, hosted-room member): its
- conversation resumes on the next generation, and the generation walk stops at the first
- unfenced id, so an aged-out marker would send the next turn back to the swept generation. A
- Bot Chat's mailbox receipts also outlive the horizon."""
+ stays (Bot Chat, A2A context, header-less chat, a chain's next generation, hosted-room
+ member): its conversation resumes on the next generation, and the generation walk stops at the
+ first unfenced id, so an aged-out marker would send the next turn back to the swept generation.
+ A Bot Chat's mailbox receipts also outlive the horizon. A caller-named API id is not derived:
+ its marker ages out, so the caller can use that id again, as for any other swept session."""
swept, (conversations, derived) = set(session_ids), _local_conversations(conn)
def removable(sid):
diff --git a/tests/gateway/test_api_server_memory_sessions.py b/tests/gateway/test_api_server_memory_sessions.py
index f97bddcb206..ffa96cd9819 100644
--- a/tests/gateway/test_api_server_memory_sessions.py
+++ b/tests/gateway/test_api_server_memory_sessions.py
@@ -41,3 +41,19 @@ def test_manager_survives_across_requests_and_is_exclusive_per_home(monkeypatch)
assert registry.checkout("sess-1") is None
home[0] = "home-a"
assert registry.checkout("sess-1") is loser
+
+
+def test_a_manager_parked_past_the_retry_horizon_is_not_handed_to_a_reused_id(monkeypatch):
+ """A swept session's fence ages out at the retry horizon, after which its id may name a new
+ session: that session must not adopt the previous one's provider (and its prefetched recall)."""
+ import time
+ from hermes_state_mutation_retirement import RETRY_HORIZON_S
+ registry = ApiServerMemorySessions(max_size=8, idle_ttl_secs=10 * RETRY_HORIZON_S)
+ monkeypatch.setattr(ApiServerMemorySessions, "_owner_home", staticmethod(lambda: ("home-a", None)))
+ monkeypatch.setattr(registry, "_shutdown_async", registry._shutdown)
+ swept = _Manager()
+ registry.checkin(_agent(swept, "user-42"))
+ later = time.time() + RETRY_HORIZON_S + 60
+ monkeypatch.setattr(time, "time", lambda: later)
+ assert registry.checkout("user-42") is None
+ assert swept.shut_down
diff --git a/tests/gateway/test_derived_generation_after_sweep.py b/tests/gateway/test_derived_generation_after_sweep.py
index 2b6a0aecfed..28159708c1c 100644
--- a/tests/gateway/test_derived_generation_after_sweep.py
+++ b/tests/gateway/test_derived_generation_after_sweep.py
@@ -9,6 +9,7 @@ and split the conversation across two sessions.
from types import SimpleNamespace
import pytest
+from aiohttp import web
from aiohttp.test_utils import TestClient, TestServer
from tests.gateway import test_api_implicit_session_after_delete as chat
@@ -90,3 +91,53 @@ def test_an_ordinary_swept_session_still_ages_out(owner):
assert owner.db.get_meta(RETIRED_PREFIX + 'cron_job_run_1') is not None
_past_the_horizon(owner)
assert owner.db.get_meta(RETIRED_PREFIX + 'cron_job_run_1') is None
+
+
+async def test_a_swept_caller_named_api_session_id_is_usable_again_past_the_horizon(api, owner, served):
+ """``POST /api/sessions`` and ``X-Hermes-Session-Id`` name the id: no door derives it or walks its
+ generations, so its sweep marker ages out like any other, and the caller can use the id again."""
+ app = _app(api)
+ app.router.add_post('/api/sessions', api._handle_create_session)
+ auth = {'Authorization': 'Bearer ' + chat._API_KEY}
+ async with TestClient(TestServer(app)) as client:
+ created = await client.post('/api/sessions', json={'id': 'user-42'}, headers=auth)
+ assert created.status == 201, await created.text()
+ status, first, _ = await _post(client, _OPENING, session_id='user-42')
+ assert status == 200, first
+ _sweep(owner, 'user-42')
+ _past_the_horizon(owner)
+ again = await client.post('/api/sessions', json={'id': 'user-42'}, headers=auth)
+ assert again.status == 201, await again.text()
+ status, second, landed = await _post(client, _OPENING, session_id='user-42')
+ assert status == 200, second
+ assert landed == 'user-42'
+
+
[email protected]('path', ['/v1/responses', '/v1/runs'])
+async def test_a_chain_resumed_after_a_sweep_never_returns_to_its_swept_root(api, owner, served, path):
+ """Any id can root a Responses/Runs chain (here a server-minted one), so its sweep marker is not
+ permanent by itself. Once a continuation moved past the swept root to its next generation, a
+ later continuation of a response stored on the root goes there too, past the horizon. Both
+ continuations use one door, so each door's bind is the one that keeps the fence."""
+ from gateway.session_api import implicit_api_session
+ app = web.Application()
+ app.router.add_post('/v1/responses', api._handle_responses)
+ app.router.add_post('/v1/runs', api._handle_runs)
+ auth = {'Authorization': 'Bearer ' + chat._API_KEY}
+ store = api._current_response_store()
+ async with TestClient(TestServer(app)) as client:
+ opened = await client.post('/v1/responses', json={'input': 'remember 42'}, headers=auth)
+ assert opened.status == 200, await opened.text()
+ first = (await opened.json())['id']
+ root = store.get(first)['session_id']
+ _sweep(owner, root)
+ resumed = await client.post(path, json={'input': 'and then?', 'previous_response_id': first}, headers=auth)
+ assert resumed.status in (200, 202), await resumed.text()
+ successor = implicit_api_session(owner.db, root)
+ assert successor != root and owner.db.get_session(successor) is not None, 'no next generation was opened'
+ _past_the_horizon(owner)
+ forked = await client.post(path, json={'input': 'what number?', 'previous_response_id': first}, headers=auth)
+ assert forked.status in (200, 202), await forked.text()
+ assert owner.db.get_session(root) is None, 'the continuation went back to the swept root'