The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""The session owner's server→client requests to a local viewer, and who may settle them.
The owner sends a request frame (``tui_gateway/contracts/server_requests.py``: ``sudo``, ``secret``,
``clarify``, the Desktop UI requests) to the viewers attached to a session's event stream and blocks the
agent thread until one answers, the turn is interrupted, or it times out: the canonical side of main's
sidecar ``tui_gateway/server_requests.py``. A viewer answers with a JSON-RPC response frame
(:func:`resolve`) or, for a batch clarify, per question with ``clarify.lock`` (:func:`lock_answer`); both go
through :func:`may_settle`, and a batch's terminal result comes from ``tools.clarify_batch.settle_batch``,
the rule the sidecar uses too. Values are never published, journaled or logged: they travel only in the
viewer's response frame.
"""
from __future__ import annotations
import contextlib
import threading
import uuid
from tools.clarify_batch import settle_batch
REQUEST_TIMEOUT_S = 120 # main: ``_ask("sudo", ..., timeout=120)``
_POLL_S = 0.25
class _Pending:
__slots__ = ("event", "events", "locked", "method", "params", "qids", "replay", "result", "session_id", "value")
def __init__(self, session_id, qids=None, events=None, method=None, params=None, replay=True):
self.event = threading.Event()
self.session_id = session_id
self.method = method
# The frame's params as sent, so a viewer that reconnects gets the request again; ``replay`` False
# for an automatic window request (a preview click), which a second delivery would run twice.
self.params = params or {}
self.replay = replay
# The live session's own event stream the request went out on: one per authority (profile) and
# session mount, so a viewer of another profile's same-named session can never settle it.
self.events = events
self.value = ""
self.result = None
# A batch clarify: its question ids and the answers ``clarify.lock`` has locked so far.
self.qids = tuple(qids) if qids else None
self.locked = {}
_lock = threading.Lock()
_open: dict[str, _Pending] = {}
def owned_by(authority, session_id, events) -> bool:
"""True when *authority*'s live *session_id* is the very stream a request was sent on."""
live = authority.sessions.get(session_id)
return live is not None and events is not None and live.event_stream is events
def may_settle(authority, actor, session_id, events) -> bool:
"""The one rule for who may settle an owner request (a response frame or ``clarify.lock``): the
request went out on *authority*'s own live stream for that session (session ids repeat across
profiles and ``_open`` is process-wide), *actor* holds ``session:respond`` there, and *actor* is
attached to that session, the same set of connections the request frame was written to."""
from gateway.session_contract import SessionRef
from hermes_state_runtime import RuntimeStoreError
if not owned_by(authority, session_id, events):
return False
try:
authority.authorize(actor, SessionRef(authority.profile_id, session_id), "session:respond")
except RuntimeStoreError:
return False
live = authority.sessions.get(session_id)
return live is not None and actor in live.subscribers.values()
def is_response_frame(frame) -> bool:
"""A viewer's answer to one of the owner's requests: a string ``srq-`` id, a result/error, no method."""
return (isinstance(frame, dict) and "method" not in frame and isinstance(frame.get("id"), str)
and frame["id"].startswith("srq-") and ("result" in frame or "error" in frame))
def resolve(frame, *, session_ok=lambda session_id, events: True) -> bool:
"""Settle the open request *frame* answers; False when nothing (here) waits for that id.
``session_ok(session_id, events)`` lets the caller refuse an answer from a connection not entitled
to that session: the caller's own authority must own ``events``, the stream the request was sent on
(session ids are only unique per profile, and ``_open`` is process-wide)."""
with _lock:
pending = _open.get(frame["id"])
if pending is None or not session_ok(pending.session_id, pending.events):
return False
_open.pop(frame["id"], None)
locked = dict(pending.locked) if pending.qids is not None else None
result = frame.get("result") if "error" not in frame else None
if locked is not None:
# One rule with main's sidecar registry: the frame's answers over the locks, or a cancel-all.
result = settle_batch(locked, result)
value = result.get("value") if isinstance(result, dict) else ""
pending.value = value if isinstance(value, str) else ""
pending.result = result if isinstance(result, dict) else None
pending.event.set()
return True
def ask_viewer(events, session_id, method, params, *, cancelled=lambda: False, timeout=REQUEST_TIMEOUT_S,
replay=True) -> str:
"""Send one one-string server→client request (``sudo``, ``secret``: ``ValueResult``) to the
session's attached viewers and wait for its ``value``; "" on skip, interrupt, timeout or no viewer.
``replay=False``: a reconnecting viewer is not handed it again (``open_requests``)."""
pending = _ask(events, session_id, method, params, cancelled=cancelled, timeout=timeout, replay=replay)
return pending.value if pending is not None else ""
def ask_viewer_result(events, session_id, method, params, *, cancelled=lambda: False, timeout=REQUEST_TIMEOUT_S,
qids=None):
"""The same round trip for a structured answer (``clarify``: ``ClarifyResult``): the viewer's
``result`` dict, or None on interrupt, timeout, an error response or no attached viewer.
``qids`` makes it a batch, which always ends with ``{answers: <locked so far>, outcome}`` once
asked: ``lock_answer`` (the ``clarify.lock`` verb) answers it per question."""
pending = _ask(events, session_id, method, params, cancelled=cancelled, timeout=timeout, qids=qids)
return pending.result if pending is not None else None
def waiting(events, session_id, method) -> bool:
"""Whether a *method* request is open on this live session's stream (the card still waits)."""
with _lock:
return any(p.session_id == session_id and p.events is events and p.method == method for p in _open.values())
def open_requests(events, session_id) -> list[dict]:
"""The requests still waiting on this live session's stream, oldest first, as their frames
carried them (plus a batch's answers locked so far): what ``session.resume`` and
``session.events.since`` hand a reconnecting viewer to re-render (``OpenRequestEntry``)."""
with _lock:
waiting_now = [(rid, p) for rid, p in _open.items()
if p.session_id == session_id and p.events is events and p.replay]
return [{"id": rid, "method": p.method,
"params": {**p.params, "answers": dict(p.locked)} if p.locked else dict(p.params)}
for rid, p in waiting_now]
def withdraw(events, session_id, method) -> int:
"""Settle every open *method* request on this live session's stream with no answer, the way a
viewer that answered would: the asker reads None and every renderer gets ``request.cancel
reason: resolved``."""
with _lock:
settled = [_open.pop(rid) for rid, p in list(_open.items())
if p.session_id == session_id and p.events is events and p.method == method]
for pending in settled:
pending.event.set()
return len(settled)
def lock_answer(request_id, question_id, answer, *, session_ok=lambda session_id, events: False):
"""Lock one answer of an open batch request (``clarify.lock``; editable until the last lock;
``None`` = skipped). Returns the question ids still unanswered; the lock that empties it settles
the request with ``{answers, outcome: submitted}``. ``None`` when no open batch has that id or the
caller may not answer its session (expired, or another profile's / session's request: see
:func:`resolve`); ``ValueError`` for an unknown question id."""
with _lock:
pending = _open.get(request_id)
if pending is None or pending.qids is None or not session_ok(pending.session_id, pending.events):
return None
if question_id not in pending.qids:
raise ValueError(question_id)
pending.locked[question_id] = answer
remaining = [qid for qid in pending.qids if qid not in pending.locked]
if not remaining:
_open.pop(request_id, None)
pending.result = settle_batch(pending.locked, ended="submitted")
if not remaining:
pending.event.set()
return remaining
def _ask(events, session_id, method, params, *, cancelled, timeout, qids=None, replay=True):
if not events.fanout.transports():
return None
request_id = f"srq-{uuid.uuid4().hex[:12]}"
pending = _Pending(session_id, qids, events, method, {"session_id": session_id, **params}, replay)
with _lock:
_open[request_id] = pending
events.fanout.write({"jsonrpc": "2.0", "id": request_id, "method": method, "params": pending.params})
waited = 0.0
reason = "timeout"
while not pending.event.wait(_POLL_S):
waited += _POLL_S
if cancelled():
reason = "interrupted"
break
if timeout is not None and waited >= timeout:
break
with _lock:
still_open = _open.pop(request_id, None) is pending
if still_open and pending.qids is not None:
# A batch keeps every answer locked before the wait ended (main's sidecar: "locked
# answers survive a timeout"); sudo/secret have no question ids and stay unanswered.
pending.result = settle_batch(pending.locked,
ended="cancelled" if reason == "interrupted" else "timed_out")
if still_open:
# The same teardown main's renderers key on (``request.cancel``): the card closes and a
# timed-out password prompt says so.
with contextlib.suppress(Exception):
events.publish(session_id, {"id": request_id, "method": method, "reason": reason},
event_type="request.cancel")
return pending if pending.qids is not None else None
# Settled by a viewer (a response frame or the last ``clarify.lock``): every OTHER viewer still
# shows the card, and a classic CLI is parked inside its modal callback. Withdraw it everywhere
# with ``reason: resolved`` (``RequestCancelReason``) so each renderer closes the matching card and
# the CLI's connection thread releases its modal (``hermes_cli.gateway_agent``). No answer rides it.
with contextlib.suppress(Exception):
events.publish(session_id, {"id": request_id, "method": method, "reason": "resolved"},
event_type="request.cancel")
return pending