The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.pyindex 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-commandapproval 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.pyindex 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_sizeself._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 Nonehome_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:continueif 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.pyindex 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_khistory, error = _parse_conversation_history(body['conversation_history'])if error is not None:return None, error- stored_session_id = None+ stored_session_id = chain_root = Noneinstructions = 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, errorif instructions is None:@@ -175,6 +175,8 @@ async def prepare_context(adapter, request, body, gateway_session_key, durable_kephemeral_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 sessionif durable_key:return await _admit(adapter, durable_key, request_id, request_binding(adapter, request, durable_key),run_kwargs, body.get('model', adapter._model_name)), Nonediff --git a/gateway/platforms/api_server_runs.py b/gateway/platforms/api_server_runs.pyindex 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 toits 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_rootif 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: Anyturn_author: Optional[dict[str, Any]] = None # memory-attribution label only; grants nothingadmission: Any = None+ walked_from: Optional[str] = None # the swept stored session the chain moved past (``bind_api_steps``)@propertydef 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.Responturn_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.Responrequest_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.pyindex 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_keypinned = 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 explicitsession 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_fencesif 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.pyindex 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, dfrom gateway.session_contract import SessionRefreturn authority, SessionRef(authority.profile_id, sid), rowref = 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.pyindex 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.pyindex 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 Nonehome[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_downdiff --git a/tests/gateway/test_derived_generation_after_sweep.py b/tests/gateway/test_derived_generation_after_sweep.pyindex 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 SimpleNamespaceimport pytest+from aiohttp import webfrom aiohttp.test_utils import TestClient, TestServerfrom 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'