# Peer messaging



Two of your saved Cluster Bot Computers — top-level root sessions, not local
sub-agents — can exchange a message directly, without belonging to the same
group. The sender keeps working; the recipient's final answer is delivered
back automatically in a later turn.

<Callout title="Scope">
  Peer messaging is limited to Cluster Bot Computer root sessions. Both the
  sender and the recipient must use the built-in `agent_cluster-bot` agent with
  the Computer profile, must not be members of a group,
  must not be archived, and must be running (a saved, provisioned
  [environment](/docs/agents/environments) with a live sandbox). Both must be
  owned by the same actor in the same organization. A peer request never grants
  the recipient permission for consequential actions, and it can't read the
  other bot's private conversation history.
</Callout>

## Tools [#tools]

Peer messaging is exposed as two built-in tools. They are not part of the
`tools` catalog for user-created agents and cannot be attached to one; the
service adds them to a Cluster Bot Computer root session's model request only
during a turn started by a signed-in human (never during a turn started by
another peer's message):

| Tool                 | Description                                                                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_root_agents`   | Lists the caller's other available saved bots by immutable ID. Read-only.                                                                                  |
| `message_root_agent` | Sends `{ target, message, file }` to another saved bot by exact ID and returns once the request is durably accepted — not once the recipient has answered. |

`file` is required by the schema but nullable: send `null` for a text-only
request, or a path relative to the sender's own mounted workspace to share
one file. Within the same user turn, sending the same `target` and request
again reuses the original exchange instead of creating a duplicate; a retry
that omits a `file` the original request included is rejected with `409`.

## File sharing [#file-sharing]

Sharing a file captures an immutable snapshot of the sender's synced copy —
up to 18 MiB, one regular file, no directories or symlinks — and delivers an
independent copy into the recipient's own workspace before its turn starts.
Later edits on either side never change the shared snapshot:

* Editing the sender's original after sharing does not change what the
  recipient (or the conversation attachment) sees.
* The recipient may freely edit its own copy; that never reaches back to the
  sender.
* Sharing an edited file again produces a new, separate snapshot.

A moving, unsynced, or oversized file fails the request outright rather than
silently sharing stale content.

## Exchange lifecycle and API [#exchange-lifecycle-and-api]

Each peer request is a durable **peer exchange**, viewable and stoppable
through the HTTP API:

| Method | Path                                 | Description                                                                                                                                                                                                                    |
| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET`  | `/v1/peer-exchanges/{id}`            | Get the exchange: request, answer, current phase/state, and `attachment` (`null` or `{id, filename, content_type, size, sha256}`).                                                                                             |
| `POST` | `/v1/peer-exchanges/{id}/stop`       | Stop that exchange only — it does not cascade to unrelated peer work.                                                                                                                                                          |
| `GET`  | `/v1/peer-exchanges/{id}/attachment` | Download the exchange's retained file bytes, if any, as `application/octet-stream`. Requires normal actor/org access to both bots; an inaccessible or revoked attachment fails closed rather than falling back to a live file. |

All three endpoints take the caller's Bearer JWT and a `?org_id=` query
parameter like the rest of the API — see
[API reference](/docs/agents/api-reference#authentication).

## Limits [#limits]

* At most four distinct peer targets may be addressed from one user turn.
* A bot that received a peer request cannot itself send further peer
  requests in the same turn (no nested delegation yet).
* Peer messaging is unrelated to the `cluster` CLI's
  [root-agent messaging](/docs/build/interactive#root-agent-messaging) (which
  uses the same tool names but only reaches local interactive sessions sharing
  a `~/.cluster` data root) and to its
  [local child agents](/docs/build/interactive#local-agents).