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-agent-rooms

Hosted agent rooms

Hosted agent rooms provide a shared space where people and agents can work together through one durable room history. The subsystem keeps participant identity, room authority, discussion state, files, and agent work aligned across local and remote product surfaces.

Collaboration model

Shared room state

A hosted room is a named collaboration space with a fixed participant roster and an ordered event history. User messages, member replies, room changes, activity notices, and work outcomes use that history as the common source for each connected surface.

The room is durable across process restarts. A room can be disbanded and later lose its retained history, but its retired identity is not reused for a different room.

References: gateway/hosted_rooms.py• L1-6 gateway/hosted_rooms.py• L87-148 gateway/hosted_rooms.py• L840-924

Participants and authority

Each participant has a stable member identity and a target profile. A target can be local to the owning gateway or a peer on another installation. The room also has one authority gateway and an authority epoch, which together identify the current owner of room changes and prevent an older owner from writing new state.

This authority model lets room membership and work continue through ownership changes without treating stale messages or work results as current. Peer access uses scoped grants that can expire, be revoked, or require renewal when the target policy changes.

References: gateway/hosted_rooms.py• L487-489 gateway/hosted_rooms.py• L681-790 tui_gateway/hosted_room_service.py• L198-207 gateway/…/api_server_room_grants.py• L91-108

Discussion and agent work

Discussion flow

Discussion turns a user message into a bounded set of member turns. The policy reads the room history and frozen roster, selects participants from mentions, and gives each selected member a bounded view of new discussion content. Later rounds occur only when a member calls another member into the discussion.

The policy produces at most one next task at a time. Terminal results become member messages or explicit pass, failure, cancellation, or deferral events. This makes a restart able to rebuild the next task from the same room history.

The diagram shows how a user message moves through policy replay, member work, and durable publication.

flowchart LR
    U[User message] --> L[Room event history]
    L --> P[Discussion policy]
    P --> T[One member task]
    T --> A[Local or peer agent]
    A --> R[Terminal result]
    R --> E[Member message or terminal event]
    E --> L

References: gateway/hosted_room_discussion.py• L89-165 gateway/hosted_room_discussion.py• L630-755 gateway/hosted_room_discussion.py• L877-910

Work execution

Agent work is separate from the discussion log. A durable task record tracks admission, execution, cancellation, settlement, and uncertain outcomes. A room lease allows one active worker generation to advance room work while fences stop stale workers from settling a task after authority, lease, or cancellation state changes.

The hosted-room runtime connects these records to the normal session handlers. It reuses a hidden Group: <room_id> session for each member, so a local session can continue when that member becomes part of hosted work. Local and peer members use the same task contract even though their transport differs.

References: gateway/hosted_room_driver.py• L1-6 gateway/hosted_room_driver.py• L192-224 gateway/hosted_room_driver.py• L532-683 tui_gateway/hosted_room_driver.py• L1-7 tui_gateway/hosted_room_driver.py• L594-705

Recovery and control

The runtime treats an interrupted or uncertain turn as unresolved until it can prove a terminal result or a stop. It can then settle the known result, cancel the work, defer it, or expose it for an explicit retry. This prevents a late agent response from hiding newer room input or from being published after a stop or authority change.

Room status exposes active member work, blocked work, pending approval, retry actions, and peer route health. These signals let product surfaces show what needs attention without taking ownership of the room state themselves.

References: gateway/hosted_room_driver.py• L701-760 tui_gateway/hosted_room_driver.py• L213-283 tui_gateway/hosted_room_service.py• L660-687

Shared content

Attachment lifecycle

Attachments let a room message carry private files into member work. The room history stores bounded attachment metadata and identifiers, while the canonical bytes stay in a private content store. Upload retries are idempotent, and a send-time commitment binds each file to one room event and its allowed recipients.

A member receives only files named by its task input. Viewer access also checks the current room authority, event ownership, recipient scope, and file integrity. This keeps shared files tied to the room conversation instead of making them general gateway files.

References: gateway/hosted_room_attachments.py• L1-8 gateway/hosted_room_attachments.py• L300-385 gateway/hosted_room_attachments.py• L672-789 gateway/hosted_room_attachments.py• L1120-1195

Cross-gateway participation

Peer members use a room link that describes the target installation, profile, capabilities, execution policy, and scoped grant. The owning gateway persists the route before making it active. During work, the route can dispatch a task, recover an admitted run, report a result, or mark the member unavailable.

The target gateway accepts only a grant-bound dispatch whose room identity, target profile, prompt, idempotency key, capability catalog, and execution policy still match. A policy or capability change therefore stops silent execution and asks for reauthorization.

References: tui_gateway/hosted_room_service.py• L230-263 tui_gateway/hosted_room_service.py• L284-346 gateway/…/api_server_room_dispatch.py• L77-124 gateway/hosted_room_execution_policy.py• L30-65

Product surfaces

Local session integration

The hosted-room service is the gateway-side coordinator for room creation, sends, stops, retries, approvals, status, and background work. It calls the same session handlers used by TUI and Desktop turns instead of creating a separate agent execution path.

The session adapter keeps room plumbing hidden from ordinary session clients. It passes task proof and attachment bindings through the in-process boundary so a client cannot forge the identity of a room task.

References: tui_gateway/hosted_room_service.py• L103-145 tui_gateway/hosted_room_service.py• L534-658 tui_gateway/hosted_room_server_rpc.py• L1-7 tui_gateway/hosted_room_server_rpc.py• L64-117

Room member API

The API surface lets a trusted gateway invite a target, inspect its capabilities, refresh a still-valid grant, revoke that grant, and submit a room-bound member dispatch. It presents the target's live execution policy and capability catalog so the sender can detect drift before work starts.

The API creates or verifies a hidden member session for the room. That session keeps the hosted transcript separate from ordinary sessions while preserving continuity for the same room and member.

References: gateway/…/api_server_room_grants.py• L73-78 gateway/…/api_server_room_grants.py• L111-205 gateway/…/api_server_room_dispatch.py• L19-62

The child page Hosted room coordination and work execution covers room creation and membership, authority checkpoints, attachment and discussion handling, work records, transport, recovery, and agent-run dispatch in more detail.

Change checklist

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

  • Changes to room event kinds or actor rules must stay aligned with discussion replay, terminal publication, and any peer history reader.
  • Changes to member target identity must stay aligned with room grants, peer route persistence, hidden member-session identity, and task recovery.
  • Changes to attachment manifests or recipient rules must stay aligned with task input reconstruction and both local and viewer read checks.
  • Changes to execution policy or capability catalogs must update grant issuance, dispatch validation, and route renewal together.
  • Changes to task or authority generations must preserve the work-record lineage and stale-worker fences.

Important failure modes

TriggerConsequenceGuard
A stale gateway writes after authority changesThe room may accept work from an old ownerAuthority gateway and epoch checks fence room and task writes
A task result arrives after its lease or cancel generation changesThe result is rejected or the task remains unresolvedLease, execution, run, and cancel generations must match
A peer grant is revoked or its target policy changesDispatch is refused and the route needs reauthorizationGrant scope, live reservation, capability digest, and policy digest checks
An attachment is not committed to the event named by its manifestThe file cannot be read as room contentEvent ownership, recipient scope, expiry, and blob hash checks
A submit fails after admission is uncertainThe room does not guess whether work ranRecovery probes the exact session and leaves unresolved work blocked or retryable

Key files

FileWhy to read it
gateway/hosted_rooms.pyRoom identity, authority, event history, links, grants, and retention
gateway/hosted_room_discussion.pyDiscussion selection, bounded prompts, task reconstruction, and publication
gateway/hosted_room_driver.pyDurable task states, leases, cancellation, settlement, and recovery
gateway/hosted_room_attachments.pyPrivate file lifecycle, event commitment, access, and retention
tui_gateway/hosted_room_service.pyProduction coordinator across room policy, transport, and product actions
tui_gateway/hosted_room_driver.pyRuntime scheduling and connection to local or peer agent sessions
gateway/…/api_server_room_grants.pyRoom invitations, capability views, grant renewal, and revocation
gateway/…/api_server_room_dispatch.pyGrant-bound peer dispatch and hidden member-session ownership