Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / hosted-room-coordination-and-work-execution

Hosted room coordination and work execution

Hosted rooms coordinate several Bot members around one durable conversation. The system keeps room identity, membership, authority, discussion state, files, work attempts, and agent results consistent across local profiles, peer gateways, restarts, and transport failures. See also Hosted agent rooms.

Hosted room model

A hosted room is a durable group conversation with a fixed member roster and one current authority. User messages enter an append-only room history. A coordinator turns that history into at most one member task at a time, then publishes the member result back into the same history.

The room history is the visible source of truth. The system also keeps bounded projections for scheduling and recovery so a busy room does not need to rebuild all work on every poll.

flowchart LR
    U[User message] --> L[Room event log]
    L --> C[Discussion checkpoint]
    C --> T[One member task]
    T --> X[Local or peer agent session]
    X --> R[Terminal result]
    R --> L

Room creation and membership

Room identity and membership

Room creation establishes a permanent room identifier, a display name, a frozen roster, and the gateway authority that manages the room. The owner claim and room record are admitted together, so a room cannot exist without a matching owner record. A disbanded identifier remains retired and cannot name a new room.

Members identify the profile or peer target that will answer for them. New discussion rooms use two to six unique members. Each member has a stable member ID and handle. A local member runs on a profile served by the owning gateway. A peer member names another installation, target profile, and capability identity.

The saved roster remains valid for an existing room even if a local profile later becomes unavailable. New rooms cannot seat an unavailable profile. This lets the room report one member as unavailable without stopping other members.

References: tui_gateway/hosted_room_service.py• L172-207 tui_gateway/hosted_room_service.py• L534-546 gateway/hosted_room_discussion.py• L284-324 gateway/session_hosted_service.py• L97-120

Authority checkpoints

Authority is the pair of gateway identity and authority epoch stored with the room. Every change to room state carries that pair. A gateway must match the current pair before it can append events, schedule work, stop a room, or publish a result.

An authority transfer increments the epoch and records the predecessor in the history. The epoch makes an old gateway unable to write after a transfer. The recorded chain also lets later work evidence show which gateway owned each part of the room history. Authority history explains ownership; it does not grant ownership by itself.

Remote execution adds a second checkpoint: the target gateway issues a room-member grant for one exact room, member, installation, profile, authority epoch, and permission set. The target checks that grant and its current reservation before it accepts work.

References: gateway/hosted_rooms.py• L956-1004 gateway/hosted_rooms.py• L1063-1111 gateway/hosted_room_authority_history.py• L47-76 gateway/…/api_server_room_grants.py• L91-108

Attachments and discussion handling

Attachment lifecycle

Attachments are private room inputs. The room event contains only a server-created attachment ID and bounded metadata. The bytes stay in a private, content-addressed store and are checked against their recorded digest when read.

The lifecycle has four meaningful stages:

  1. The client uploads bytes with an upload ID. Repeating the upload is safe only when the content and metadata match.
  2. A message commit binds the upload to one event and the room's recipient roster.
  3. The event append makes the binding durable. A failed append returns the upload to its uncommitted state.
  4. A member task resolves only the files allowed for that member and event. The target route must support attachments or the task fails before agent submission.

Local member routes can materialize authorized files for the agent. Peer routes currently advertise no attachment support, so the coordinator refuses a file-bearing task on that route rather than silently dropping the files.

References: gateway/hosted_room_attachments.py• L1-8 gateway/hosted_room_attachments.py• L514-647 gateway/hosted_room_attachments.py• L672-789 gateway/session_hosted_attachments.py• L58-76 tui_gateway/hosted_room_driver.py• L594-611

Discussion lifecycle

A user send creates a typed message.user event for a thread. The discussion policy selects the oldest latest user message that is not stopped or complete. The first round answers the user-selected members. Later rounds answer only members explicitly mentioned by a prior member.

Each member turn has stable coordinates: room, thread, discussion event, member, round, and task identity. A member can return a useful message or (pass). A useful result becomes message.member; every result also receives a terminal event such as settled, failed, cancelled, or deferred. The coordinator publishes the visible reply before the terminal receipt so later policy can use only committed replies.

The policy bounds rounds, messages, prompt size, attachment input, and transcript size. A completed or bounded discussion writes room activity, which removes it from the active queue. A newer user message supersedes a late result in the same thread; stale prose is cancelled instead of changing the current discussion.

References: gateway/hosted_room_discussion.py• L26-37 gateway/hosted_room_discussion.py• L630-755 gateway/hosted_room_discussion.py• L877-910 tui_gateway/hosted_room_service.py• L469-514

Work records and lineage

Durable work evidence

Work records are bounded, passive evidence about room work. They describe the room history prefix, roster, authority, outstanding tasks, remote run receipts, and stop facts. They help an operator or another gateway understand what work may still exist. They are not an execution checkpoint and their absence does not prove that work was never admitted.

The record is tied to a canonical history digest and roster digest. A later authority cannot overwrite the prior authority's current evidence. Authority changes freeze older records as historical or superseded. Malformed retained evidence is marked invalid rather than replaced with a made-up current snapshot.

Lineage follows committed authority spans. A successor can use evidence only when each task source and remote receipt maps to an authority span in the room history. This prevents a copied record from becoming a new claim of ownership.

References: gateway/hosted_room_work_records.py• L143-174 gateway/hosted_room_work_records.py• L242-325 gateway/hosted_room_work_storage.py• L148-156 gateway/hosted_room_work_lineage.py• L5-35

Transport and agent-run dispatch

Local member execution

Local execution uses the owning gateway's session service. The coordinator resolves or creates a hidden session named Group: <room_id> for the member profile. This stable session name preserves one transcript when a room moves between local and hosted use.

The driver submits the task with a private hosted-room identity. The session service checks the room owner, current authority, frozen member binding, target profile, task identity, and execution generation before it admits the agent turn. The advertised room policy is bound to the target profile, including allowed tool sets, approval mode, and iteration limit.

References: tui_gateway/hosted_room_server_rpc.py• L28-71 tui_gateway/hosted_room_server_rpc.py• L73-117 gateway/session_hosted_service.py• L129-201 gateway/hosted_room_execution_policy.py• L30-65

Peer member execution

Peer execution uses a RoomLink between the home gateway and the target gateway. The home gateway sends a fully fenced dispatch over the target's direct HTTPS or loopback endpoint. The dispatch includes the room and authority coordinates, member and profile, task and execution generation, source event, prompt digest, capability digest, and policy digest.

The target validates the scoped grant before it creates or reuses the hidden group session. It then checks that the dispatch targets its active profile and installation, that the capability and policy digests still match, and that the idempotency key matches the task generation. The target gateway, not the Desktop, owns admission and agent execution.

The home gateway stores the remote run handle before it observes the result. This receipt lets recovery find the exact run after a process restart. Alternate RoomLink addresses may be tried only for retryable failures. An ambiguous submission is not failed over blindly because the first gateway may already have admitted the task.

References: gateway/hosted_room_peer.py• L1-5 gateway/hosted_room_peer.py• L356-392 tui_gateway/hosted_room_peer_transport.py• L119-133 tui_gateway/hosted_room_peer_http.py• L364-432 gateway/…/api_server_room_dispatch.py• L77-122

Recovery and lifecycle control

Recovery states

The driver uses a room lease and task generations to ensure that only one process can advance a room's work. A task moves from queued to running, then to a terminal result. A stop request first records intent and only becomes cancelled after the exact session or remote run acknowledges the stop.

Recovery follows this path:

  1. A new worker acquires the current room lease and marks abandoned foreign attempts as indeterminate.
  2. The worker checks the exact local session or remote run for a matching terminal receipt.
  3. A verified receipt is committed under the new lease. A proven pre-admission failure returns the task to queued with backoff.
  4. If the result cannot be proved, the task stays blocked until the uncertainty window ends, then becomes deferred.
  5. An explicit retry either resolves a discovered result or starts a new execution generation. Automatic retry does not repeat uncertain work.

The same fences protect late callbacks. A result from an old lease, authority epoch, or execution generation is discarded. A room can therefore recover without allowing a stale process to publish a reply after a newer owner has taken control.

References: gateway/hosted_room_driver.py• L532-570 gateway/hosted_room_driver.py• L638-760 gateway/hosted_room_driver.py• L829-845 tui_gateway/hosted_room_driver.py• L514-545 tui_gateway/hosted_room_driver.py• L772-879

Room stop and disband

Room stop appends a durable stop fence that supersedes earlier user turns. The coordinator cancels queued work directly and asks active local or peer work to stop. A room is not safely disbanded while active work still needs a stop acknowledgement.

Disband records a tombstone and retires the room ID permanently. The system later prunes old event and work payloads while retaining the retired identity. Attachment bytes receive a grace period before cleanup. This preserves the difference between an expired history and a room that never existed.

References: gateway/hosted_room_service.py• L570-590 gateway/hosted_rooms.py• L1053-1060 gateway/hosted_rooms.py• L1132-1161 gateway/hosted_rooms.py• L576-611

Change checklist

When these files or sections are changed, remember to consider these:

  • Event kinds or payloads: update the room event contract, discussion validation, policy checkpoint projection, and terminal publication rules together.
  • Roster or member target fields: keep room validation, local binding checks, peer dispatch scope, and roster digests aligned.
  • Execution policy or capability fields: preserve the policy digest and catalog digest checks on invitation, refresh, and dispatch.
  • Task identity or generation fields: update local fences, peer idempotency keys, remote receipts, and recovery probes as one contract.
  • Authority transfer rules: preserve epoch checks, authority history, and work-record lineage validation.
  • Attachment behavior: keep upload commitment, event retention, member authorization, and route capability checks consistent.
  • Hidden session identity: preserve the bot_room source and Group: <room_id> namespace across local and peer transports.

Important failure modes

TriggerConsequenceGuard
A stale gateway writes after an authority transferThe old process cannot publish room events or task resultsGateway ID and authority epoch fences on room and task writes
A peer grant or policy digest is revoked or changedThe target refuses admission and the route needs reauthorizationExact scoped grant checks plus live catalog and policy digest checks
A submit response is lost after the request may have been admittedThe task becomes indeterminate instead of being blindly retriedExact run receipt recovery and explicit retry after reconciliation
A room member route cannot carry attached filesThe task fails before agent submissionRoute capability check in the driver
A stop races with a running agentWork remains in stopping until the exact run acknowledges itTwo-phase stop and task generation fences
A room history or attachment store reaches its boundNew work is refused or the room is reported unavailablePer-room and host-wide quotas with control-event reserve

Key files

FileWhy to read it
tui_gateway/hosted_room_service.pyMain coordinator for room creation, sends, policy preparation, peer routes, and lifecycle actions
gateway/hosted_rooms.pyDurable room identity, authority, append-only events, retention, and room stop/disband behavior
gateway/hosted_room_discussion.pyDiscussion rules, task identity, bounded prompt input, and terminal publication
gateway/hosted_room_policy_checkpoint.pyBounded scheduling projection derived from the visible room log
gateway/hosted_room_driver.pyDurable task state, leases, generations, cancellation, and recovery fences
tui_gateway/hosted_room_driver.pyRuntime worker that dispatches agent turns and observes terminal results
gateway/hosted_room_attachments.pyPrivate attachment bytes, event commitments, recipient access, and cleanup
gateway/hosted_room_work_records.pyPassive work evidence and bounded task and run snapshots
gateway/hosted_room_work_lineage.pyAuthority-span checks for work evidence across ownership changes
gateway/hosted_room_peer.pyRoomLink catalog, dispatch contract, scoped grants, and transport rules
tui_gateway/hosted_room_peer_transport.pyAdapter from a hosted task to a peer gateway member route
tui_gateway/hosted_room_peer_http.pyPeer admission, remote run receipts, polling, stop, and grant renewal
gateway/…/api_server_room_dispatch.pyTarget-side validation and hidden member-session binding
gateway/session_hosted_service.pyAuthority-bound local member access and admission checks