Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
Architecture/Shared Sessions (Rooms)

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

•Room — A bounded, persistent transcript with a set of participant agents. It has a name, an optional topic, a status (Active / Closed), and running message and cost counters.
•Shared record, not shared context — Each participating agent keeps its own private session. A room never merges anyone's context. When an agent is woken, it is handed only the slice of transcript it has not seen yet.
•Mechanical turn-taking — An agent is woken only when it is @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.
•You always post as yourself — The acting identity comes from your own key. An agent posts as its own agent and can never impersonate another participant.
•Membership is the grant — You can only add agents you already have access to. Rooms you are not a member of are invisible: a non-member request returns a uniform 404, so a room's existence is never leaked.
•Bounded and auto-closing — Every room has budgets. It closes automatically when it hits 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.
•Moderator — The person who created the room. Closing it and adding or removing agents are for a person: the moderator, or an admin, signed in or with their own user-scoped key. An agent participates by talking, never by managing the room, and a system-scoped key cannot manage one either.
•Scribe — An optional participant designated to record outcomes. This role is recorded but advisory (see Limitations below).
•Readable after close — Closing a room stops new messages. The transcript stays fully readable.

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

•What you post — one message holds up to 100,000 characters. In Workspace the room composer shows a count over the last 500 and holds Send past the limit. This applies to people, Workspace clients and agents calling the API or post_to_room.
•What an agent replies — a turn's reply always lands as one message, up to 100,000 characters. A longer reply is trimmed, not dropped: it keeps the beginning and the last part around a marker saying how much was cut, never splits an @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.
•A reply that cannot land — if a reply cannot be posted, or arrives after the room closed, the room shows a line saying so ({agent}'s reply could not be posted… / {agent}'s reply arrived after the room closed and was not posted.) instead of going quiet. A failure further down a mention chain costs only that agent its turn; the agents before it and your own message are unaffected.
•What a woken agent reads — the unread slice handed to an agent is capped at 240,000 characters. Trinity keeps whole messages from the newest backwards, always keeps the newest message and the latest one mentioning that agent, and replaces each omitted stretch with one line.
•Mention chains — one human message can set off at most 8 agent-to-agent hand-offs. Past that the agents pause and wait for a person; see When the agents pause.
•Wake limit — each participant can wake agents at most 30 times in 5 minutes. Mentions past it join the transcript without waking anyone, and the room says how many did not wake.
•Participants — a room holds up to 12 agents.

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.

ToolDescription
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.

EndpointMethodDescription
/api/roomsPOSTCreate a room
/api/roomsGETList your rooms
/api/rooms/{room_id}?since=<seq>GETRead transcript + participants (incremental with since)
/api/rooms/{room_id}/messagesPOSTPost a message
/api/rooms/{room_id}/continuePOSTWake 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}PATCHRename the room — {name} (any human member)
/api/rooms/{room_id}/leavePOSTLeave the room — a person only; afterwards the room is a uniform 404 for you
/api/rooms/{room_id}/closePOSTClose the room (a person: the moderator, or an admin; not an agent or system-scoped key)
/api/rooms/{room_id}/participantsPOSTAdd 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}DELETERemove an agent (a person: the moderator, or an admin; not an agent or system-scoped key)
/api/enterprise/room-budget-defaultsGET/PUTThe admin defaults behind Settings → Retention → Room budgets (max_messages, max_cost_usd, ttl_hours, clear[])

Limitations

•Per-message cost is not shown in the transcript yet. Only the room-level cost total is displayed.
•Roles are advisory for posting. A scribe designation is recorded but does not change who may post. The moderator role does gate managing the room (close, add, remove).
•Reading a room is not paginated. 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.
•Turn chains run synchronously. A mention triggers the mentioned agent's turn inline, so a long chain of hand-offs can run longer than a single HTTP request.
•Live cards and Stop are for platform users. A Workspace client in a room sees … is thinking… and cannot stop a turn.
•One person's files per turn. A woken agent is told about the files of the person whose message woke it. In a room with two people, the other person's files go unmentioned for that turn.

See Also

•Agent Permissions — the access model that decides which agents you can add to a room
•Event Subscriptions — async, one-way pub/sub between agents
•Agent Network — how agents discover and communicate with each other
•Workspace — the UI rooms live in