yjW#xUdZddlmZddlmZddlmZmZeZ ee d<da e e d<de fd Z ed e Zee d <ed e Zee d<ede Zee d<ede Zee d<ede Zee d<ede Zee d<ede Zee d<ede Zee d<ede Zee d<ede Zee d<ede Zee d <ed!e Zee d"<ed#e Zee d$<ed%e Zee d&<ed'e Zee d(<ed)e Zee d*<ed+e Zee d,<ed-e Zee d.<id ed edededededededededed!ed#ed%ed)ed+ed-eZ d/e!dd0fd1Z"edOd/e!d0zded0fd2Z#d3d3d3d3d3d3d3d3d3d3d3d3d3d4d3e fd5e!d6e!d7e!d8e!d9e!d:e!d;e!de!d?e!d@e!dAe dBe!dCede$f"dDZ%dEe$dd0fdFZ&dPdGZ'dQdHe!dIe!de!fdJZ(e)hdKZ*de fdLZ+dPdMZ,de fdNZ-d0S)Ra Session-scoped context variables for the Hermes gateway. Replaces the previous ``os.environ``-based session state (``HERMES_SESSION_PLATFORM``, ``HERMES_SESSION_CHAT_ID``, etc.) with Python's ``contextvars.ContextVar``. **Why this matters** The gateway processes messages concurrently via ``asyncio``. When two messages arrive at the same time the old code did: os.environ["HERMES_SESSION_THREAD_ID"] = str(context.source.thread_id) Because ``os.environ`` is *process-global*, Message A's value was silently overwritten by Message B before Message A's agent finished running. Background-task notifications and tool calls therefore routed to the wrong thread. ``contextvars.ContextVar`` values are *task-local*: each ``asyncio`` task (and any ``run_in_executor`` thread it spawns) gets its own copy, so concurrent messages never interfere. **Backward compatibility** The public helper ``get_session_env(name, default="")`` mirrors the old ``os.getenv("HERMES_SESSION_*", ...)`` calls. Existing tool code only needs to replace the import + call site: # before import os platform = os.getenv("HERMES_SESSION_PLATFORM", "") # after from gateway.session_context import get_session_env platform = get_session_env("HERMES_SESSION_PLATFORM", "") )contextmanager) ContextVar)AnyIterator_UNSETF_session_context_engagedreturnctS)zTrue if any session has been bound via set_session_vars in this process. See the ``_session_context_engaged`` comment for the leak-policy rationale. )r=/home/ragecks/.hermes/hermes-agent/gateway/session_context.pysession_context_engagedr?s $#r HERMES_SESSION_PLATFORM)default_SESSION_PLATFORMHERMES_SESSION_SOURCE_SESSION_SOURCEHERMES_SESSION_CHAT_ID_SESSION_CHAT_IDHERMES_SESSION_CHAT_TYPE_SESSION_CHAT_TYPEHERMES_SESSION_CHAT_NAME_SESSION_CHAT_NAMEHERMES_SESSION_THREAD_ID_SESSION_THREAD_IDHERMES_SESSION_USER_ID_SESSION_USER_IDHERMES_SESSION_USER_NAME_SESSION_USER_NAMEHERMES_SESSION_KEY _SESSION_KEYHERMES_SESSION_ID _SESSION_IDHERMES_UI_SESSION_ID_SESSION_UI_SESSION_IDHERMES_SESSION_MESSAGE_ID_SESSION_MESSAGE_IDHERMES_SESSION_PROFILE_SESSION_PROFILEHERMES_CRON_SESSION _CRON_SESSIONHERMES_SESSION_ASYNC_DELIVERY_SESSION_ASYNC_DELIVERY!HERMES_CRON_AUTO_DELIVER_PLATFORM_CRON_AUTO_DELIVER_PLATFORM HERMES_CRON_AUTO_DELIVER_CHAT_ID_CRON_AUTO_DELIVER_CHAT_ID"HERMES_CRON_AUTO_DELIVER_THREAD_ID_CRON_AUTO_DELIVER_THREAD_ID session_idNcddl}t| ddlm}|rdSn#t $rYnwxYw||jd<dS)u]Synchronize ``HERMES_SESSION_ID`` across ContextVar and ``os.environ``. Long-lived single-process entrypoints like the CLI can rotate sessions via ``/new``, ``/resume``, ``/branch``, or compression splits without reconstructing the entire agent. Tools still consult ``get_session_env("HERMES_SESSION_ID")`` with an ``os.environ`` fallback, so both storage paths must move together when the active session changes. Delegated subagent children are the exception: they are constructed inside the parent process within ``delegated_child_context()``, and their ``AIAgent.__init__`` calls this same helper. Writing a child's internal session id to ``os.environ`` (process-global) would clobber the parent's ``HERMES_SESSION_ID`` for the rest of the process — leaking the child id into parent tools and subprocesses spawned after the child was built. The ContextVar write below is task-local and safe for concurrent children; only the process-global ``os.environ`` mirror is suppressed for delegated children. Root agents (CLI, gateway, cron) keep both paths. rN)is_delegated_child_contextr")osr#setagent.delegation_contextr6 Exceptionenviron)r4r7r6s r set_current_session_idr<s&IIIOOJ  GGGGGG % % ' '  F       '1BJ"###s3 AAc#Kt}|t| dVt|dS#t|wxYw)a/Bind a task-local session id and restore the prior value on exit. With ``session_id=None`` this acts as a save/restore boundary around code that may call :func:`set_current_session_id` itself (notably delegated ``AIAgent`` construction). It intentionally never mutates ``os.environ``. N)r#getr8)r4previouss r scoped_current_session_idr@sm  H ###" !!!!! !!!!s AA5Tplatformsourcechat_id chat_type chat_name thread_iduser_id user_name session_key message_idprofilecwdasync_delivery ui_session_id cron_sessionc\dat|t|t|t |t |t|t|t|t|t| t|t| t| t|t t#| g} ddlm}|| n#t($rYnwxYw|S)uSet all session context variables and return reset tokens. Call ``clear_session_vars(tokens)`` in a ``finally`` block when the handler exits. Note ``clear_session_vars`` resets every var to ``""`` (to suppress the ``os.environ`` fallback) rather than restoring prior values — these helpers are not nestable/stack-safe, and the returned tokens are accepted only for API compatibility. ``cwd`` pins the logical working directory for this context. ``async_delivery`` declares whether this session's channel can route a background completion back to the agent after the turn ends (see ``_SESSION_ASYNC_DELIVERY`` / ``async_delivery_supported``). Stateless request/response adapters (the API server) pass ``False``. ``cron_session`` is tri-state: ``_UNSET`` preserves legacy ``os.environ["HERMES_CRON_SESSION"]`` fallback, ``"1"`` marks a cron job, and ``""`` explicitly marks a non-cron session while masking leaked env. Tr)set_session_cwd)rrr8rrrrrrrr!r#r%r'r)r+r-boolagent.runtime_cwdrRr:)rBrCrDrErFrGrHrIrJr4rKrLrMrNrOrPtokensrRs r set_session_varsrVsfR $h''F##W%%y))y))y))W%%y))%% ##""=11 ++W%%,''##D$8$899F" 555555      Ms F F)(F)rUcdtttttt t tttttttfD]}|dtt  ddlm}|dS#t&$rYdSwxYw)a+Mark session context variables as explicitly cleared. Sets all variables to ``""`` so that ``get_session_env`` returns an empty string instead of falling back to (potentially stale) ``os.environ`` values. The *tokens* argument is accepted for API compatibility with callers that saved the return value of ``set_session_vars``, but the actual clearing uses ``var.set("")`` rather than ``var.reset(token)`` to ensure the "explicitly cleared" state is distinguishable from "never set" (which holds the ``_UNSET`` sentinel). rArclear_session_cwdN)rrrrrrrrr!r#r%r'r)r+r8r-rrTrYr:)rUvarrYs r clear_session_varsr[s   ''' 777777      sB!! B/.B/ctD]}|ttt ddlm}|dS#t$rYdSwxYw)uLReset every session context variable to ``_UNSET`` for THIS context. Distinct from :func:`clear_session_vars`, which sets the vars to ``""`` ("explicitly cleared" — suppresses the os.environ fallback and is used when a handler *finishes*). This helper restores the ``_UNSET`` sentinel ("never bound in this context"), which is what a freshly-spawned task should look like *before* it binds its own session. 🔴 Why this exists — the cross-session ContextVar inheritance leak. Each gateway message is processed in its own ``asyncio`` task, created via ``create_task`` (which snapshots the *current* context with ``copy_context``). When message B's task is spawned from a context where a concurrent message A had already called :func:`set_session_vars`, B inherits A's **set** ContextVars. Until B calls its own ``set_session_vars`` there is a window where any subprocess B spawns (e.g. a tool shelling out) reads *A's* ``HERMES_SESSION_*`` identity via the subprocess-env bridge. The bridge's ``_UNSET``-strip guard cannot help: the vars are not ``_UNSET``, they are set-to-A. Calling ``reset_session_vars`` at the top of the per-message handler drops the inherited identity so the window strips safe (no session) instead of leaking the foreign one; the handler then binds its own via ``set_session_vars`` a few steps later. See tests/tools/test_local_env_session_leak.py and tests/gateway/test_session_context_inheritance.py. Note ``_SESSION_ASYNC_DELIVERY`` lives outside ``_VAR_MAP`` (it is a bool capability flag read via :func:`async_delivery_supported`, not a string ``HERMES_SESSION_*`` env var read via :func:`get_session_env`), so it is reset explicitly below. Without it, a task spawned from a context where a sibling adapter bound ``async_delivery=False`` (the stateless API server) inherits that ``False`` through the pre-bind window, and ``async_delivery_supported`` wrongly reports the new turn's channel as unable to route a background completion until ``set_session_vars`` runs. rrXN)_VAR_MAPvaluesr8rr-rTrYr:)rZrYs r reset_session_varsr_;sD   ''' 777777      sA)) A76A7namercddl}t|}||}|tur|S|||S)uRead a session context variable by its legacy ``HERMES_SESSION_*`` name. Drop-in replacement for ``os.getenv("HERMES_SESSION_*", default)``. Resolution order: 1. Context variable (set by the gateway for concurrency-safe access). If the variable was explicitly set (even to ``""``) via ``set_session_vars`` or ``clear_session_vars``, that value is returned — **no fallback to os.environ**. 2. ``os.environ`` (only when the context variable was never set in this context — i.e. CLI, cron scheduler, and test processes that don't use ``set_session_vars`` at all). 3. *default* rN)r7r]r>rgetenv)r`rr7rZvalues r get_session_envrdksTIII ,,t  C     L 99T7 # ##r > rAclituitoolcodexlocalkanbandesktopgatewaywebhook api_servermsgraph_webhookc ddl}|dptdd}tdd}||fD]E}t|pd}|r |t vrdSFdS) a7Whether this turn is delivered over a human messaging channel. Callers use this to decide anything that differs between "the user is reading a chat message" and "the user is at a machine they own": whether to emit a delivery tag, whether a file has to land somewhere the gateway is allowed to send from, whether narration would read as chat noise. Resolves ``HERMES_PLATFORM``, then the session platform, then the session source, and reports messaging when any of them names a surface outside :data:`NON_MESSAGING_SESSION_SURFACES`. rNHERMES_PLATFORMrrArTF)r7rbrdstrstriplowerNON_MESSAGING_SESSION_SURFACES)r7rBrCidentitys r session_is_messaging_surfacerwsIIIyy*++]?XZ\/]/]H 4b 9 9Fv&x~2&&,,..4466  (FFF44 5r c:tddS)aWDeclare that this session cannot receive an async background completion. Binds only the delivery capability, leaving every other session var unset. Use this instead of ``set_session_vars(async_delivery=False)`` on a pure single-process runner: ``set_session_vars`` also latches ``_session_context_engaged`` (see above), which switches the subprocess env bridge from "os.environ fallback" to "ContextVar-authoritative, strip on _UNSET" in ``tools/environments/local.py``. A one-shot CLI that never engages the session-context system must not flip that latch as a side effect of declaring a capability. Callers that already build a full session context (cron's ``run_job``) get the same state by passing ``async_delivery=False`` to ``set_session_vars``. A session that cannot take a late completion makes ``delegate_task`` fall through to its existing inline/synchronous path, so subagent results are returned within the turn instead of being dispatched to a channel that will never deliver them. See NousResearch/hermes-agent#53027 and #63142. FN)r-r8r r r declare_stateless_channelrys,&&&&&r cddl}|jdrdSt}|turdSt |S)uWhether the current session can deliver a background completion later. Returns ``False`` for finite runtimes that can end before a detached result is delivered: sessions explicitly bound by a stateless channel — an adapter that cannot route a notification back after the turn ends (the API server), or a one-shot runner that exits after its final response (``hermes -z``, cron — see :func:`declare_stateless_channel`) — and dispatcher-spawned Kanban workers (identified by ``HERMES_KANBAN_TASK``), which are one-shot ``chat -q`` subprocesses. The real gateway platforms, the interactive CLI, and any other path that never bound the contextvar return ``True``. Tools that promise async delivery (``terminal`` notify_on_complete / watch_patterns, ``delegate_task`` background=True) consult this before registering a watcher / dispatching a detached child, so they can refuse a promise the channel can't keep instead of silently no-op'ing. rNHERMES_KANBAN_TASKFT)r7r;r>r-rrS)r7rcs r async_delivery_supportedr|sV"III  z~~*++u # ' ' ) )E t ;;r )N)r N)rA).__doc__ contextlibr contextvarsrtypingrrobjectr__annotations__rrSrrrrrrrrrr!r#r%r'r)r+r-r/r1r3r]rrr<r@listrVr[r_rd frozensetrurwryr|r r r rs$$$L&%%%%%"""""" fhh"'$&&&$$$$$!+ +Df U U U:UUU(j)@&QQQQQQ)z*BFSSS*SSS!+,FPV!W!W!WJWWW!+,FPV!W!W!WJWWW!+,FPV!W!W!WJWWW)z*BFSSS*SSS!+,FPV!W!W!WJWWW%:&:FKKK jKKK$*%8&III ZIII&0Z0FPV%W%W%W WWW#-*-HRX"Y"Y"YZYYY)z*BFSSS*SSS 'J'