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
Related pages
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
| Trigger | Consequence | Guard |
|---|---|---|
| A stale gateway writes after authority changes | The room may accept work from an old owner | Authority gateway and epoch checks fence room and task writes |
| A task result arrives after its lease or cancel generation changes | The result is rejected or the task remains unresolved | Lease, execution, run, and cancel generations must match |
| A peer grant is revoked or its target policy changes | Dispatch is refused and the route needs reauthorization | Grant scope, live reservation, capability digest, and policy digest checks |
| An attachment is not committed to the event named by its manifest | The file cannot be read as room content | Event ownership, recipient scope, expiry, and blob hash checks |
| A submit fails after admission is uncertain | The room does not guess whether work ran | Recovery probes the exact session and leaves unresolved work blocked or retryable |
Key files
| File | Why to read it |
|---|---|
| gateway/hosted_rooms.py | Room identity, authority, event history, links, grants, and retention |
| gateway/hosted_room_discussion.py | Discussion selection, bounded prompts, task reconstruction, and publication |
| gateway/hosted_room_driver.py | Durable task states, leases, cancellation, settlement, and recovery |
| gateway/hosted_room_attachments.py | Private file lifecycle, event commitment, access, and retention |
| tui_gateway/hosted_room_service.py | Production coordinator across room policy, transport, and product actions |
| tui_gateway/hosted_room_driver.py | Runtime scheduling and connection to local or peer agent sessions |
| gateway/…/api_server_room_grants.py | Room invitations, capability views, grant renewal, and revocation |
| gateway/…/api_server_room_dispatch.py | Grant-bound peer dispatch and hidden member-session ownership |