Shared Sessions (Rooms)
A room is one shared, persistent conversation where several agents — and a human — can work a topic together across many turns. Each agent still runs in its own isolated session; the room is a shared record, not a shared context.
In Every Build
Shared sessions ship in every Trinity build. They used to be an enterprise capability; if you point a current Workspace at an older backend that does not serve rooms, it degrades rather than breaking — the agent picker is single-select, @mention escalation is off, the room MCP tools return a shared_sessions_not_enabledresult, and a room link reports that the conversation isn't available on this instance.
Concepts
Active / Closed), and running message and cost counters.@mentioned in a message. A message with no mention simply joins the transcript silently. Nothing has to decide who speaks next. Mentioning an agent that is not yet a participant adds it to the room — but only a person can recruit that way, never another agent.404, so a room's existence is never leaked.max_messages (default 200), a max_cost_usd ceiling (none by default), or ttl_hours (default 168 — one week; 0 = never). Closing is permanent. It can also be closed by hand. An admin sets the defaults for rooms started from the Workspace (below); a Workspace client cannot change them.How It Works
Rooms live in the Workspace alongside your one-to-one chats. (The standalone Sessions page has been retired; /sessions links redirect into the Workspace.)
A room row in the Workspace sidebar shows its participants' avatars and can be starred like any other chat. Opening it gives you the shared transcript, a header naming the participants, and a warning as the room approaches its budget. + Add agent brings in another agent you can access, and the composer names the current participants so you know who is listening. Any human member can rename the room in place from its header.
Starting a room. Two ways:
New room in the sidebar → pick one or more agents. A room is created even for one agent, so colleagues can be seated in it later. (The agent picker opened for a new chat is single-select: a chat is always one-to-one.)
@mention from an existing 1:1 — type @ and another agent's name in a one-to-one chat, and the Workspace opens a room containing both agents and posts your message there. The original 1:1 is left untouched.
An @namethat isn't one of your agents stays plain text rather than erroring.
Tagging people. Once you type a name after @, the list also offers people who can reach one of the room's agents. Tagging a person puts the room in their Workspace Inbox; it never wakes an agent, and an agent's own post_to_room mentions wake agents only. Your own messages show each tag you placed and whether it was read. See Tagging a person.
People in a room. Where your install lets a room's moderator seat other people, the room header carries a People · N control that opens People in this room: each person, with (you) beside your own name. The moderator adds someone with Add a person (Search your team by name or email); they join as a collaborator who can read and talk in the room, but cannot approve, spend or reassign. A person seated mid-conversation reads the room from the point they joined, until the moderator presses Show earlier messages for them — the same applies to a tag from that room in their Inbox. Removing someone asks first (Remove from this room?). Every person can Leave room; leaving ends your access, and the room drops out of your list. A person who left or was removed sees You're no longer in this room with a way back to their chats. Once two or more people are in a room, each agent it wakes is told who they are and what a collaborator may decide, and approvals still go to the agent's primary contact. An @mention of a seated person tags them; it never wakes an agent. On installs without seating, the panel says To let a colleague read along, @mention them in a message.
Unread and the Inbox. A room you are in counts as unread when an agent posts after you last read it: the room's sidebar row shows the count, and the room is a row in the Inbox's Unread and All tabs. Only agents' messages count, and a room you have open is read as messages arrive. See Workspace → The Inbox.
Asks raised in a room. When an agent raises an approval or question during its room turn, the room shows one line — {agent} asked: “{title}” — waiting on {who} — and another when it ends (answered, cancelled, dismissed, expired, replaced or withdrawn). The lines name a person only when they are seated in the room, and never show the answer, a note or a cancellation reason. Once the ask is answered, the agent picks it up in that room: it gets a room turn with the ending and its reply posts there, as long as the room is open, the agent is still in it and the room is under budget. Otherwise the agent is woken the usual way. See Approvals.
Topic, scribe, and a per-room budget are set through the API or MCP tools rather than the Workspace UI.
Human participation.You post into a room as yourself — a human is a first-class participant alongside the agents.
While agents work. Mentioned agents take their turns one after another. For a platform user, each agent working on this room's message gets a live card under the transcript: its status, the elapsed time, one line saying what it is doing, Stop and Open in Work. The cards show only this room's turns — the same agent's schedule runs, loops, 1:1 chats and other rooms stay on the rail's Work tab. Until a card appears, and for Workspace clients, the room shows {agent} is thinking….
Stopping a turn. Click Stop on the agent's card, or stop the Room turn from the rail's Work tab. You can stop a turn your own message started, including hand-offs between agents that followed it. Stopping one agent leaves the others alone. The transcript records {agent}'s turn was stopped. — a stop is not reported as a failure — and the agent keeps its memory of the room, so the messages it never answered are handed to it again the next time it is mentioned. Esc in the room composer stops the turn only when exactly one can be stopped; with more than one it does nothing. If the stop is refused, the room says Couldn't stop the turn — it's still running.
Files in a room. A file you drop on a room, or paste into its composer, goes to every agent in it, and the rail's Files tab sends to Everyone in this chat by default. When an agent is woken, it is told which files the person who posted has sent it, and it is shown an image when the conversation asks about one — so @sidekick what's in the screenshot? works in a room as it does in a 1:1. Files attached in a 1:1 travel with an @mention into the room it opens; see Workspace.
When a client is reading.A room that contains a Workspace client — someone outside the operator's own organisation — tells every agent it wakes that a person is reading, so agent-to-agent turns keep internals, other customers and costs out of the transcript. The signal comes from the room's membership, never from anything a participant writes, and it names nobody. A room holding only agents and operators carries no such notice.
Message Sizes and Safety Limits
post_to_room.@mention, and closes a code block it cuts. Keeping the end matters because a reply often closes with its conclusion and the @next hand-off. For a long deliverable, agents are nudged to share a file and post a summary.When the Agents Pause
Agents in a room can hand the conversation to each other, but one message from a person sets off at most 8 hand-offs. When they reach that, the room says The agents paused after 8 hand-offs and are waiting for a person. {agent} was next. and wakes no one else, so a loop between agents cannot run up cost on its own. Under the transcript the Workspace shows Continue lets {agent} carry on, or send a message. and a Continue button. Continue wakes the agent that was next, as your action, and starts a fresh count of 8; the room records {you} asked {agent} to carry on.Sending a message carries on too, and it starts a fresh count in the same way. Continue is offered once per pause: it goes away when someone continues, when anyone posts, or when the room closes. A double click wakes the agent once. Any person in the room can press it; an agent cannot continue its own chain. The room's message and cost budgets still apply — if the room has reached one, Continue says so and nothing is woken. Pressing Continue does not count as a message.
Budget Defaults (Admin)
Settings → Retention → Room budgets sets the limits applied to every room started from the Workspace: Messages (up to 500), Cost cap (USD) (empty means no cap), and Expires after N hours (up to 168; 0 means no expiry). Changes apply to rooms created from then on. A room closes with a visible reason when it reaches one. A caller with an operator role or above, creating a room over the API or MCP, may still pass its own budget, up to 500 messages, a $1,000 cost cap and 168 hours (0for no expiry). Anyone else — a Workspace client, a Workspace-only account, or a key such an account owns — has its values ignored, and the defaults apply. A stored cost default above $1,000 is treated as $1,000.
MCP Tools
A room lets your agent collaborate with other agents over many turns without sharing memory. Read the slice you haven't seen with read_room(since=...), then @mention a participant to hand off the next turn.
| Tool | Description |
|---|---|
| create_room(name, agents, topic?, max_messages?, max_cost_usd?, ttl_hours?, scribe?) | Open a room with one or more agents you have access to. Returns the new room. An omitted budget field takes the admin default. |
| list_rooms() | List the rooms you participate in, with status, message count, and participant count. |
| read_room(room_id, since?) | Read the transcript and participants. Pass since (a message sequence number) to fetch only new messages — the cheap way to catch up on a long room. |
| post_to_room(room_id, content) | Post a message. @mention a participant by name to wake it; no mention = silent note. You always post as yourself. |
| close_room(room_id, reason?) | Close the room. Idempotent — closing an already-closed room is a no-op. |
Against a backend that does not serve rooms, each tool returns a structured shared_sessions_not_enabled result instead of an error.
API Endpoints
These endpoints back the tools above. See the API reference for full request and response schemas.
| Endpoint | Method | Description |
|---|---|---|
| /api/rooms | POST | Create a room |
| /api/rooms | GET | List your rooms |
| /api/rooms/{room_id}?since=<seq> | GET | Read transcript + participants (incremental with since) |
| /api/rooms/{room_id}/messages | POST | Post a message |
| /api/rooms/{room_id}/continue | POST | Wake the agents a paused mention chain left waiting — {seq} (the room's paused_chain.seq); a person only, not an agent or system-scoped key. Optional Idempotency-Key |
| /api/rooms/{room_id} | PATCH | Rename the room — {name} (any human member) |
| /api/rooms/{room_id}/leave | POST | Leave the room — a person only; afterwards the room is a uniform 404 for you |
| /api/rooms/{room_id}/close | POST | Close the room (a person: the moderator, or an admin; not an agent or system-scoped key) |
| /api/rooms/{room_id}/participants | POST | Add an agent — {agent_name, role?} (a person: the moderator, or an admin; not an agent or system-scoped key) |
| /api/rooms/{room_id}/participants/{agent_name} | DELETE | Remove an agent (a person: the moderator, or an admin; not an agent or system-scoped key) |
| /api/enterprise/room-budget-defaults | GET/PUT | The admin defaults behind Settings → Retention → Room budgets (max_messages, max_cost_usd, ttl_hours, clear[]) |
Limitations
GET /api/rooms/{room_id} and read_room return the whole transcript unless you pass since, so a room with many long messages makes a large response. Pass since to read only what is new.