feat(session_context): add set/reset_current_turn_session_key public wrappers by Isla-Liu · Pull Request #32927 · NousResearch/hermes-agent

Isla-Liu · 2026-05-27T01:35:24Z

This adds public wrappers for the per-turn session-identity ContextVar in
gateway.session_context, mirroring the structural pattern that
tools/approval.py uses for the approval-session ContextVar.

Motivation

hermes-webui PR fix(oauth): use platform.claude.com endpoint for token refresh + startup warning #2968 (backend: emit bg_task_complete SSE on background-task completion (server-side wakeup + per-session coalesce) nesquena/hermes-webui#2968)
currently binds per-turn session identity by importing _SESSION_KEY
and calling .set(...) directly inside api/streaming.py. The
webui maintainer flagged the private-API touch and asked for a public
setter to mirror tools/approval.py:set_current_session_key. This PR
closes that gap.

What ships

gateway.session_context.set_current_turn_session_key(key: str) -> Token
gateway.session_context.reset_current_turn_session_key(token: Token) -> None
Test coverage: round-trip, nested set+reset, empty-string normalization,
None-normalized-to-empty.
No change to _SESSION_KEY itself or to existing callers; the wrappers
are additive.

Naming

Deliberately distinct from tools/approval.py's
set_current_session_key — the two ContextVars carry different
concerns and downstream callers may need to set both in the same
scope. turn_session (this module) vs session (approval) keeps
imports unambiguous.

Follow-up

hermes-webui will land a small commit on PR fix(oauth): use platform.claude.com endpoint for token refresh + startup warning #2968 replacing the
private touch in api/streaming.py:_set_turn_session_identity with
set_current_turn_session_key once this lands. No webui change is
needed in this PR.

Refs

backend: emit bg_task_complete SSE on background-task completion (server-side wakeup + per-session coalesce) nesquena/hermes-webui#2968 (webui side review comment)

Isla-Liu · 2026-05-27T02:25:08Z

Quick downstream context on why this PR exists, plus a side-effect read so the merge call is easy.

Why these wrappers. hermes-webui#2968 (nesquena/hermes-webui#2968) needs to bind a per-turn session_key onto gateway.session_context._SESSION_KEY for server-initiated wakeup turns. Background tasks completing with notify_on_complete=true can spawn a turn from a thread whose ambient ContextVar carries a stale value, misrouting the wakeup SSE to the wrong session in a narrow multi-tab window. The current WebUI PR binds via direct _SESSION_KEY.set(...); the WebUI maintainer flagged that as a private-API touch and asked for a public agent-side setter before that import lands. These wrappers are that setter.

What ships — additive only.

Two new public functions in gateway/session_context.py: set_current_turn_session_key(session_key) returning a contextvars.Token, and reset_current_turn_session_key(token) taking it back. Mirrors the structural pattern of tools/approval.py's session-key setters.
4 new tests in tests/test_session_context_public_turn_setters.py covering set/reset round-trip, copy_context isolation, nesting, and reset-with-stale-token.

What does NOT change.

_SESSION_KEY itself — still private; we only add public wrappers around it.
No existing imports or call sites in hermes-agent are touched.
No behavior change in turn handling; the new wrappers have no in-tree consumer today.
tools/approval.py's set_current_session_key / reset_current_session_key for the approval-session ContextVar are untouched. The wrappers here carry turn_session in the middle on purpose: the unqualified name is already taken in tools/approval.py for a different ContextVar, so a collision-free name was required.

Side effects. None expected — pure indirection over an existing ContextVar, no shared state, no thread-pool implications beyond what the ContextVar already has. If _SESSION_KEY is ever refactored, the wrappers give a stable indirection point for downstream.

Downstream follow-up. Once this merges, the WebUI side replaces the private _SESSION_KEY.set(...) import with the public setter in a small follow-up PR — ~1 line of meaningful change in api/streaming.py:_set_turn_session_identity plus the matching reset.

Refs: hermes-webui#2968 — nesquena/hermes-webui#2968

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds public, per-turn session-key ContextVar setter/resetter APIs and validates expected ContextVar behavior via unit tests.

Changes:

Introduce set_current_turn_session_key() / reset_current_turn_session_key() wrappers around gateway.session_context._SESSION_KEY.
Add tests for round-trip, nesting, and normalization behavior (including None input).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
gateway/session_context.py	Adds public per-turn session key setter/resetter APIs returning/resetting `contextvars.Token`.
tests/test_session_context_public_turn_setters.py	Adds tests exercising per-turn session key bind/reset behavior, including nesting and `None` handling.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

Adds a public wrapper pair for the per-turn session-identity ContextVar in gateway.session_context, mirroring the structural pattern that tools/approval.py uses for the approval-session ContextVar. Naming: deliberately distinct from approval.py's set_current_session_key -- the two ContextVars carry different concerns and downstream callers will eventually need to set both. 'turn_session' disambiguates from the approval-session. Motivation: hermes-webui PR NousResearch#2968 (nesquena/hermes-webui#2968) currently binds per-turn session identity by importing _SESSION_KEY and calling .set() directly, which the maintainer flagged as a private-API touch. This wrapper closes that gap; the webui-side refactor lands as a follow-up commit on that PR once this lands.

Anchors: - Copilot r3308087275/r3308087295: type signatures now accept Optional[str] and use Token[str]; import Optional. Public setter docstring also notes None is normalised to empty string. - Copilot r3308087305: rewrite turn_session vs session paragraph in set_current_turn_session_key docstring to reference the actual API surface (turn_session_key suffix, _SESSION_KEY ContextVar) so wording matches the names callers see. - Copilot r3308087325/r3308087343: harden test_set_and_reset_round_trip by capturing the surrounding ContextVar value before set() and asserting identity equality after reset() instead of relying on a != 'session-abc' check that could flake when an outer context already binds that string.

Anchors: - Copilot r3308922402: widen turn-session token typing for _UNSET sentinel - Copilot r3308922430: widen reset token typing for _UNSET sentinel - Copilot r3308922450: align _SESSION_KEY ContextVar token type with sentinel - Copilot r3308922477: assert session key behavior through public get_session_env

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

teknium1

Thanks for identifying a real downstream API seam. Current WebUI master still imports gateway.session_context._SESSION_KEY directly in api/streaming.py:1825 and resets it at :1846.

Problems

The PR is DIRTY and its broad sentinel/ContextVar rewrite (gateway/session_context.py PR head :43-74, :228) predates current main's session-context expansion and hardening (gateway/session_context.py:73-121, :157-301). Salvaging that rewrite would risk discarding current behavior unrelated to the requested API.
turn_session_key is a third public API at PR head gateway/session_context.py:143-150; the documented downstream contract only uses the explicit setter/resetter pair.

Suggested changes

Salvage only the additive setter/resetter pair against current main, preserving the current _UNSET, _VAR_MAP, and fallback behavior.
Omit the context manager unless a concrete caller needs it.

This is an automated hermes-sweeper review.

teknium1 · 2026-07-13T14:33:50Z

+from contextvars import ContextVar, Token
+from typing import Iterator, Optional
+
+class _UnsetType:


Please do not carry this sentinel/type migration into the salvage. The requested change is the public session-key wrapper pair, while current main has since expanded and hardened this ContextVar module; preserve its current state representation and add the wrappers only.

teknium1 · 2026-07-13T14:33:50Z

+    _SESSION_KEY.reset(token)
+
+
+@contextmanager


The downstream contract described by this PR uses the explicit setter/resetter pair. Please omit this additional public context-manager API unless a concrete consumer needs it.

alt-glitch added type/refactor Code restructuring, no behavior change P3 Low — cosmetic, nice to have comp/gateway Gateway runner, session dispatch, delivery labels May 27, 2026

Isla-Liu mentioned this pull request May 27, 2026

backend: emit bg_task_complete SSE on background-task completion (server-side wakeup + per-session coalesce) nesquena/hermes-webui#2968

Closed

Isla-Liu marked this pull request as ready for review May 27, 2026 02:37

Copilot AI review requested due to automatic review settings May 27, 2026 02:37

Copilot AI reviewed May 27, 2026

View reviewed changes

Isla-Liu requested a review from Copilot May 27, 2026 06:37

Copilot AI reviewed May 27, 2026

View reviewed changes

Comment thread gateway/session_context.py Outdated

Comment thread gateway/session_context.py Outdated

Comment thread gateway/session_context.py

Comment thread tests/test_session_context_public_turn_setters.py

Isla-Liu requested a review from Copilot May 27, 2026 07:54

Copilot AI reviewed May 27, 2026

View reviewed changes

Comment thread tests/test_session_context_public_turn_setters.py

Comment thread gateway/session_context.py Outdated

Comment thread gateway/session_context.py Outdated

Comment thread gateway/session_context.py Outdated

Isla-Liu requested a review from Copilot May 28, 2026 01:44

Copilot AI reviewed May 28, 2026

View reviewed changes

Isla-Liu added 4 commits May 28, 2026 17:18

fix: address Copilot review on session context setters

f8ffb2c

Isla-Liu force-pushed the feat/session-context-public-turn-setters branch from 6e8c79a to f8ffb2c Compare May 28, 2026 09:19

Isla-Liu requested a review from Copilot May 28, 2026 09:33

Copilot AI reviewed May 28, 2026

teknium1 reviewed Jul 13, 2026

View reviewed changes

		_SESSION_KEY.reset(token)


		@contextmanager

Uh oh!

Conversation

Isla-Liu commented May 27, 2026

Uh oh!

Isla-Liu commented May 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

teknium1 left a comment

Choose a reason for hiding this comment

Problems

Suggested changes

Uh oh!

teknium1 Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

teknium1 Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants