Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

Stop describing Matrix as Switch's message bus in docs, Helm and comments (#589)

Abel Dantas658a392272b0
diff --git a/CLAUDE.md b/CLAUDE.md
index 14a22e975..b3d8b448e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -107,6 +107,21 @@ stable identifiers and wire shapes, not as a sign that Matrix is in use. In
Python they are `transport_room_id` / `transport_user_id`, and the server name
is `ID_SERVER_NAME` (`MATRIX_SERVER_NAME` is still read, with a warning).
+**The message bus is PostgreSQL** (`transport/postgres.py`). Switch once ran on a
+Matrix homeserver; that is gone, and no Matrix server or client library is
+involved. A send is an `INSERT` into `messages`, with a per-room advisory lock
+assigning `seq` (`db/stores/message_store.py`). The `messages_notify` trigger
+calls `pg_notify('switch_message', …)` with the room, `seq` and row id, delivered
+on commit (`db/notify_ddl.py`). One `MessageListener` (`messages/notify.py`)
+holds a dedicated `LISTEN` connection and wakes the subscribers for that room;
+each client then reads the rows after its own cursor, 200 at a time. The
+notification is a wake-up, never the payload. Invites and presence travel over
+in-process buses (`transport/invites.py`, `transport/ephemeral.py`), which is
+part of why switch-core runs as a single replica. Names such as
+`matrix_room_id`, `matrix_user_id`, `MATRIX_SERVER_NAME`, the `@localpart:server`
+id shape and `m.room.message` content types are kept as stable identifiers and
+wire shapes, not as a sign that Matrix is in use.
+
## The Switch skill
Every agent session is started by Switch Console or its sidecar; there are no
diff --git a/docs/official/TOC.md b/docs/official/TOC.md
index 0d59c4c42..776ffefab 100644
--- a/docs/official/TOC.md
+++ b/docs/official/TOC.md
@@ -63,7 +63,6 @@ rather than to a path in this repository, which they cannot open.
## Under the hood
- [internals/index](internals/index.md) — <https://docs.flintai.dev/flintai/switch/internals>
-- [internals/matrix-substrate](internals/matrix-substrate.md) — <https://docs.flintai.dev/flintai/switch/internals/matrix-substrate>
- [internals/collaboration-bridge](internals/collaboration-bridge.md) — <https://docs.flintai.dev/flintai/switch/internals/collaboration-bridge>
- [internals/agent-protocol](internals/agent-protocol.md) — <https://docs.flintai.dev/flintai/switch/internals/agent-protocol>
- [internals/connectors-and-runtime](internals/connectors-and-runtime.md) — <https://docs.flintai.dev/flintai/switch/internals/connectors-and-runtime>
diff --git a/docs/official/deploy/index.md b/docs/official/deploy/index.md
index 33554f859..0b0b7ab11 100644
--- a/docs/official/deploy/index.md
+++ b/docs/official/deploy/index.md
@@ -52,8 +52,7 @@ See [Host Switch for your team](self-host.md).
A Switch server is several services rather than one:
- **switch-core** — the agent API and the MCP server your agents connect to.
-- **Tuwunel** — the Matrix homeserver that carries room messages.
-- **PostgreSQL** — rooms, agents, and the rest of the server's state.
+- **PostgreSQL** — room messages, rooms, agents, and the rest of the server's state.
- **The Gateway** — the operator dashboard, where you administer rooms and connections in a browser.
- **Mattermost** — optional, and brought up for you by Switch Console so a managed server has somewhere to talk from the moment it starts. Deploy the server yourself and you choose whether to include it or connect the messaging app your team already uses.
diff --git a/docs/official/deploy/self-host.md b/docs/official/deploy/self-host.md
index 03e8c8198..a2e64d217 100644
--- a/docs/official/deploy/self-host.md
+++ b/docs/official/deploy/self-host.md
@@ -14,6 +14,14 @@ This page covers what you need to choose, what the deployment exposes, and how t
If a server is already running and somebody can give you its Gateway URL and API URL, you don't need to deploy anything. Go to [Add a server](../getting-started/add-a-server.md) and choose **Connect to an existing server**.
+## Before you begin
+
+- **Somewhere to run it.** A Linux machine you administer, or a namespace in a cluster you can deploy to. Whoever provisions infrastructure in your organization is the person to ask, and that ask usually has the longest lead time on this page.
+- **Whoever fronts your internal services.** A fresh deployment is reachable only from the machine it's running on, and your colleagues reach it through whatever your organization uses to terminate TLS and sign people in. That's rarely the same person who deploys the server.
+- **An administrator of your messaging app**, if you're bridging the server to one your team already uses. [Connect messaging apps](messaging-apps/index.md) says what each app needs from theirs. You don't need one to start with: both deployments below can bring up a Mattermost of their own.
+
+One decision can't be undone once the server has started — the name it gives every account and room it creates. Read [Decide the server's name before the first start](#decide-the-servers-name-before-the-first-start) before you deploy, rather than when you reach it.
+
## Choose where it runs
Each Switch release publishes both of the following, stamped with the same version, so a single version number pins the whole stack.
@@ -43,7 +51,7 @@ The Compose file **requires** you to set a version and has no fallback. That's d
## What the Compose deployment gives you
-The core of the stack — the Switch server itself, its database, and the `tuwunel` message server that carries room traffic — starts by default. The rest is opt-in through Compose profiles:
+The core of the stack — the Switch server itself and its database — starts by default. The database carries room traffic as well as everything else the deployment stores. The rest is opt-in through Compose profiles:
- **`collab`** adds a Mattermost instance and seeds it, so the deployment comes with a messaging app rather than needing one connected first.
- **`gateway`** adds the Gateway, the administrative surface for the server.
@@ -60,9 +68,9 @@ Set `AGENT_REGISTRATION_TOKEN` before the first start. It becomes the server's s
### Decide the server's name before the first start
-The Compose file names the message server `localhost`, in two places — `TUWUNEL_SERVER_NAME` and `MATRIX_SERVER_NAME` — and both have to carry the same value.
+The Compose file sets the server's name to `localhost`, in `MATRIX_SERVER_NAME`. The server has no default for it and won't start without one.
-That name doesn't have to resolve anywhere, because the deployment doesn't federate with any other. But it becomes part of every user and room identifier the server creates, so it's visible to everyone using the deployment, and changing it after the server has run orphans everything created up to that point. Pick a name you can live with, or keep the default deliberately.
+Nothing is ever contacted at that name — it's a naming scheme rather than an address, so it doesn't have to resolve anywhere. But it becomes the second half of every user and room identifier the server creates, so it's visible to everyone using the deployment, and changing it after the server has run orphans everything created up to that point. Pick a name you can live with, or keep the default deliberately.
## What the Helm chart gives you
@@ -91,13 +99,25 @@ In Switch Console, add a server and choose **Connect to an existing server**. En
They install Switch Console, choose the same option, and enter the same addresses. Each person also needs an account on the deployment and on the messaging app it's bridged to.
-## Back up the signing key
+## What to back up
**Warning**
-**The signing key is the one thing you cannot recover.** It's the cryptographic identity of your deployment: lose it and every account on the server is orphaned, and the server can never be restored as itself. On a Compose deployment it lives in the `tuwuneldata` volume. Back that up before anyone relies on the deployment.
+**The database is the backup.** Rooms, messages, the files people share, and every account live in PostgreSQL. Take a database backup before anyone relies on the deployment — without one there is nothing to restore.
+
+The Helm chart ships no backup jobs, deliberately — a backup written to storage in the same cluster shares the failure it's meant to protect against, and your cluster already has better primitives. The chart's own `BACKUP.md` says what to take and how.
+
+Two more things live in the environment rather than on disk, so a backup of neither the database nor a volume captures them.
+
+**`JWT_SECRET_KEY` is the one to guard.** It signs session tokens, and it encrypts the API keys the server stores — each agent's, and the Gateway's. Bring the deployment back on a different value and nothing looks broken: those API keys go on working, because checking one doesn't involve the secret. What you lose is the ability to read any of them back, so anyone who didn't keep their own copy needs a new key issued.
+
+`AGENT_REGISTRATION_TOKEN` is the key your colleagues' agents register against. Keep both wherever your organization keeps secrets.
+
+### One volume matters only if you upgraded
+
+A deployment that has been running since before Switch kept shared files in the database still holds the files shared up to that point in a single volume — `tuwuneldata` on Compose, a retained claim on Kubernetes. Those files stayed where they were rather than moving, so that volume is their only copy. Back it up alongside the database, or decide deliberately to let them go. On Kubernetes, `retainedTuwunelDataSize` has to match the size the volume was created at, because Kubernetes rejects a smaller claim rather than resizing.
-The Helm chart ships no backup jobs, deliberately — a backup written to storage in the same cluster shares the failure it's meant to protect against, and your cluster already has better primitives. The chart's own `BACKUP.md` says what to back up and how, including the database and the Mattermost files.
+**Standing up a new deployment, none of that applies to you.** Nothing writes to that volume, so it stays empty — and you can set `retainTuwunelData` to `false` rather than claim storage you'll never fill.
## Next steps
diff --git a/docs/official/internals/agent-protocol.md b/docs/official/internals/agent-protocol.md
index 970390ca6..9e9c9bc7c 100644
--- a/docs/official/internals/agent-protocol.md
+++ b/docs/official/internals/agent-protocol.md
@@ -178,6 +178,35 @@ sequenceDiagram
- **`command.args`** carries the role name to re-assume for `reset` and `compact`.
- **`room_join.listening`** is per room and per agent. The event is always buffered; the client decides whether to surface it.
+### Participant ids
+
+`sender` and `member` carry a participant id, in the form `@<localpart>:<server>`. The localpart takes one of two shapes:
+
+```
+switch-<type>-<short id> a per-participant client
+switch-<type> a system client, one per instance
+```
+
+`<type>` is what the client is for: `agent`, `user`, `bridge`, or `admin` for the voice Switch speaks in itself. A person talking from a messaging app has a `user` client of their own, so every sender in a room is a client and there is no separate human case to handle.
+
+The `<server>` half is a naming scheme, not an address. Nothing is contacted at it, and it does not resolve. It is fixed per deployment and forms part of every id that deployment has ever issued, which is why it cannot be changed after a server has run.
+
+**Warning**
+
+Treat the whole id as opaque. Match on it, don't parse it: the shapes above are what Switch issues today, and a client that splits an id to infer a type will break on the first one that doesn't fit.
+
+### Multi-file attachments
+
+A media event carries one file, and messaging platforms allow several in one post. Switch sends one event per file and marks the batch, rather than inventing a multi-file event.
+
+Every event in a batch carries `com.switch.attachment_group` in its content, holding `id`, `index` and `total`. The receiving side coalesces the group back into one logical message. An event without the key is a group of one, so an ungrouped attachment needs no special handling, and a malformed marker degrades to ungrouped rather than failing, so one odd event cannot stall a receiver.
+
+Two further content markers appear on otherwise ordinary events: `com.switch.admin` for output Switch posts in its own voice, and `com.switch.auto_reply` for a reply generated on an agent's behalf rather than by it.
+
+**Tip**
+
+If you're writing a client, treat the group marker as the unit of work. Handling media events one at a time will function and will look wrong in every channel it touches.
+
### Task events
Every task event carries `task_id`, `requester_agent_id` and `performer_agent_id`, plus one field of its own. **Delivery is one-sided.**
diff --git a/docs/official/internals/collaboration-bridge.md b/docs/official/internals/collaboration-bridge.md
index 88613b32c..03f06c936 100644
--- a/docs/official/internals/collaboration-bridge.md
+++ b/docs/official/internals/collaboration-bridge.md
@@ -1,14 +1,14 @@
# The collaboration bridge
-_How Switch relays a messaging app into a Matrix room, and the contract you implement to add one it doesn't support_
+_How Switch relays a messaging app into a Switch room, and the contract you implement to add one it doesn't support_
Published at <https://docs.flintai.dev/flintai/switch/internals/collaboration-bridge> — link readers there, not to this file.
-The collaboration bridge relays an external chat platform into a Matrix room, in both directions. One adapter per platform.
+The collaboration bridge relays an external chat platform into a Switch room, in both directions. One adapter per platform.
A Switch room maps to one channel on the far side. The mapping is a database row, not a runtime association, so it survives a restart.
-The bridge is itself a Matrix participant: it has a client, it joins rooms, and it sees only what happens after it joins.
+The bridge is itself a participant: it has a client, it joins rooms, and it sees only what happens after it joins.
## Adapters that exist
@@ -65,7 +65,7 @@ async def delete_message(self, channel_id: str, message_ref: str) -> None: ...
async def send_typing(self, channel_id: str, sender_name: str, is_typing: bool) -> None: ...
```
-`send_message` returns the platform's own id for the post. Return it — the bridge core stores it against the Matrix event id, and threading, edits and deletes all resolve through that pair.
+`send_message` returns the platform's own id for the post. Return it — the bridge core stores it against the Switch event id, and threading, edits and deletes all resolve through that pair.
`sender_name` is the agent whose voice the message goes out in. Render it however the platform allows: a per-agent identity, a display-name override, a prefix.
@@ -145,13 +145,13 @@ Everything an adapter hands back through the callbacks is a platform-neutral Pyd
Supporting models: `Attachment`, `OutboundAttachment`, `AttachmentFailure`, `DirectoryUser`.
-**There is no outbound message model.** Outbound is a Matrix event handed to the bridge core, which passes primitives to `send_message`.
+**There is no outbound message model.** Outbound is a room event handed to the bridge core, which passes primitives to `send_message`.
## Puppeting
-A **puppet** is a Matrix account that stands in for one external person. The bridge core keeps a map from external user id to puppet client id.
+A **puppet** is a client that stands in for one external person. The bridge core keeps a map from external user id to puppet client id.
-On an inbound message the core looks up or creates the puppet, waits for it to be ready, invites it to the Matrix room, waits for the join to land, and only then sends.
+On an inbound message the core looks up or creates the puppet, waits for it to be ready, invites it to the Switch room, waits for the join to land, and only then sends.
```mermaid
%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
@@ -161,16 +161,16 @@ sequenceDiagram
participant A as Adapter
participant B as Bridge core
participant P as Puppet client
- participant M as Matrix room
+ participant R as Switch room
U->>A: platform message event
A->>A: normalize into InboundMessage
A->>B: on_message
B->>B: resolve channel to room
B->>P: look up or create puppet
- B->>M: invite puppet
- M-->>B: join lands
- Note over B,M: a client ignores events predating its own join — an early send is dropped silently
- P->>M: post message
+ B->>R: invite puppet
+ R-->>B: join lands
+ Note over B,R: a client ignores events predating its own join — an early send is dropped silently
+ P->>R: post message
```
Puppet creation is guarded by a per-user lock with a double-check inside it, because two messages from the same new person can arrive close together.
@@ -179,15 +179,15 @@ The core refuses to puppet a name belonging to a registered bridged agent, so an
## Loop prevention
-The outbound path skips any Matrix event whose sender is a known puppet.
+The outbound path skips any event whose sender is a known puppet.
A message that arrived from Slack entered the room as a puppet, so it is never relayed back to Slack. Agents and other Switch participants have non-puppet senders and go out normally.
## Threads, edits and deletes
-A durable table maps Matrix event ids to external post ids. It is written in both directions, with a uniqueness constraint on each side, so either id resolves the other.
+A durable table maps Switch event ids to external post ids. It is written in both directions, with a uniqueness constraint on each side, so either id resolves the other.
-- **Threading.** A Matrix reply carries the event id it replies to. The map turns that into the platform's thread root, and the reply lands in the thread.
+- **Threading.** A reply carries the event id it replies to. The map turns that into the platform's thread root, and the reply lands in the thread.
- **Edits and deletes.** The bridge looks up the external post id and calls `update_message` or `delete_message` against it, however long after the fact.
```mermaid
@@ -195,12 +195,12 @@ A durable table maps Matrix event ids to external post ids. It is written in bot
sequenceDiagram
autonumber
participant G as Agent
- participant M as Matrix room
+ participant R as Switch room
participant C as Bridge client
participant B as Bridge core
participant A as Adapter
- G->>M: post message
- M->>C: room event
+ G->>R: post message
+ R->>C: room event
C->>B: hand off event
B->>B: sender is not a known puppet
B->>B: look up external post id in the message map
@@ -221,7 +221,7 @@ What differs per platform is only how a person reaches them.
| Front door | Mechanism |
|---|---|
-| Bang form, `!help` | Recognized inbound and bridged into Matrix as a `com.switch.command` event |
+| Bang form, `!help` | Recognized inbound and bridged into the room as a `com.switch.command` event |
| Discord slash commands | Generated from the registry; each declared argument becomes a Discord option, reassembled into the positional form the handlers already parse |
| Telegram command menu | Published from the registry, so the menu can't drift from what's implemented |
@@ -234,5 +234,3 @@ The bang form works with no adapter effort. Generating a native command surface
## Next steps
- [Life of a message](life-of-a-message.md) — One message from a channel to an agent and back, hop by hop
-
-- [The Matrix substrate](matrix-substrate.md) — Participants as clients, sync and resume, and the custom events Switch layers on
diff --git a/docs/official/internals/index.md b/docs/official/internals/index.md
index 527795742..06be8a456 100644
--- a/docs/official/internals/index.md
+++ b/docs/official/internals/index.md
@@ -4,7 +4,7 @@ _The components of Switch, what each one is responsible for, and how they connec
Published at <https://docs.flintai.dev/flintai/switch/internals> — link readers there, not to this file.
-Switch is a service that puts people and AI agents in the same room, on top of a Matrix message bus. This section covers its components, the contracts between them, and the parts of the design that aren't obvious from the outside.
+Switch is a service that puts people and AI agents in rooms together, over a message bus of its own. This section covers its components, the contracts between them, and the parts of the design that aren't obvious from the outside.
Read it if you're writing an adapter for a new messaging app, writing an agent client of your own, or working on Switch itself.
@@ -22,34 +22,32 @@ flowchart TB
collab["<b>Collaboration bridge</b><br/>an adapter per app<br/>puppets · threads · commands"]
agentbridge["<b>Agent bridge</b><br/>HTTP · SSE · the event buffer<br/>the operations registry"]
gateway["<b>Gateway</b><br/>the operator API"]
+ collab ~~~ agentbridge ~~~ gateway
end
- matrix["<b>Matrix homeserver</b><br/>the message bus — every participant is a client on it"]
- store["<b>PostgreSQL</b><br/>rooms · agents · resources · identities · mappings"]
+ store["<b>PostgreSQL</b><br/>the message bus and Switch's own state<br/>rooms · messages · agents · resources · identities · mappings"]
people --> collab
agents --> agentbridge
operators --> gateway
- collab --> matrix
- agentbridge --> matrix
+ collab --> store
+ agentbridge --> store
gateway --> store
- matrix --> store
classDef plain fill:none,stroke:#888888,stroke-width:1px
- class people,agents,operators,collab,agentbridge,gateway,matrix,store plain
+ class people,agents,operators,collab,agentbridge,gateway,store plain
style core fill:none,stroke:#888888,stroke-width:1px
linkStyle default stroke:#888888
```
-Each population reaches Switch through a component of its own. None of them addresses the others directly. Everything below the top row turns all of them into participants in the same Matrix room.
+Each population reaches Switch through a component of its own. None of them addresses the others directly. Everything below the top row turns all of them into participants in the same Switch room.
| Component | Responsibility |
| --- | --- |
-| **Collaboration bridge** | Relays between an external chat platform and a Matrix room. One adapter per platform. |
+| **Collaboration bridge** | Relays between an external chat platform and a Switch room. One adapter per platform. |
| **Agent bridge** | The HTTP and SSE surface agents connect to. Owns registration, connections, the event buffer and the operations registry. |
| **Gateway** | The operator API, serving a browser or Switch Console over a session cookie. |
-| **Matrix homeserver** | The message bus. Tuwunel, running beside `switch-core`. |
-| **PostgreSQL** | Switch's own state: rooms, agents, the resource library, identity mappings, message correlation. |
+| **PostgreSQL** | The message bus, and Switch's own state: rooms, agents, the resource library, identity mappings, message correlation. |
`switch-core` is one service. The agent bridge is the root application, the Gateway is mounted underneath it, and `/health` sits on the root.
@@ -57,33 +55,36 @@ Each population reaches Switch through a component of its own. None of them addr
The agent bridge speaks **HTTP and SSE**. HTTP for calls, one SSE stream for events. That is the whole of [the agent protocol](agent-protocol.md).
-Agent sessions — Claude Code, Codex, OpenCode, Cursor CLI or Antigravity — are started by Switch Console, or by the sidecar it deploys to a remote host. For each agent, Console or the sidecar runs a watcher that:
+Agent sessions — Antigravity, Claude Code, Codex, Cursor or OpenCode — are started by Switch Console, or by the sidecar it deploys to a remote host. For each agent, Console or the sidecar runs a watcher that:
- holds the agent's one SSE connection and delivers room events into the right session
- runs each tool call as an HTTP request against the agent bridge
-Each session's own host process serves the Switch operations to the agent as MCP tools on loopback and forwards every call to the watcher. The agent sees MCP tools; the thing talking to Switch is the watcher, over HTTP and SSE. A client written from scratch calls the agent bridge directly. [Sessions and the runtime](connectors-and-runtime.md) covers how that works.
+Each session's own host process serves the Switch operations to the agent as MCP tools on loopback and forwards every call to the watcher. The agent sees MCP tools. The thing talking to Switch is the watcher, over HTTP and SSE. A client written from scratch calls the agent bridge directly. [Sessions and the runtime](connectors-and-runtime.md) covers how that works.
-## Matrix as the substrate
+## Participants and the message bus
-Every room in Switch is a room on a Matrix homeserver. Nobody signs in to it and it isn't a user-facing feature.
+Every room in Switch is a row-backed room in PostgreSQL, and every message in it is a row. There is no separate message server to run, sign in to, or back up on its own.
-What Matrix supplies:
+What the bus supplies:
-- **Rooms and membership.** Who is in a room and who may post are questions Matrix already answers.
-- **Durable, replayable history.** A reconnecting client catches up from the homeserver.
+- **Rooms and membership.** Who is in a room and who may post are answered in one place, for everyone in it.
+- **Durable history.** Every message is stored and stays readable, so a room can be read back long after it was written.
- **Symmetric participants.** A message from a person and a message from an agent are the same kind of event from the same kind of sender.
-Every participant has a real Matrix account: each agent, each system actor, and each person talking from a messaging app. A person in Slack is represented by a **puppet** account that posts on their behalf.
+Every participant is a client with its own row: each agent, each system actor, and each person talking from a messaging app. A person in Slack is represented by a **puppet** client that posts on their behalf.
-The consequence is that addressing, membership, permissions and history are implemented once, against Matrix participants, rather than once per population. The cost lands in the collaboration bridge.
+The consequence is that addressing, membership, permissions and history are implemented once, against participants, rather than once per population. The cost lands in the collaboration bridge.
+
+**Note**
+
+Durable history is not the same as replay. A room starts a new client at its current head, so nothing said before that client arrived turns up in its stream. A connection that drops and reopens is the exception: it resumes from its own cursor, for as long as the buffer still reaches back that far. Catching up on anything older is a deliberate read of the room, not something delivery does.
## State
| Store | Holds |
| --- | --- |
-| PostgreSQL | Rooms and metadata, registered agents, the resource library, identity mappings, role leases, message correlation |
-| Matrix homeserver | Room events, membership, each client's sync position |
+| PostgreSQL | Room messages and membership, rooms and metadata, registered agents, the resource library, identity mappings, role leases, message correlation |
| Switch Console | A local database on the machine it runs on, for sessions and local configuration |
Switch Console's database is not a cache of the server's. Neither is evidence for what the other contains.
@@ -98,8 +99,6 @@ The repository declares a registry of artifact versions and wire-contract revisi
- [Life of a message](life-of-a-message.md) — One message from a Slack channel to an agent and back, hop by hop
-- [The Matrix substrate](matrix-substrate.md) — Participants as clients, sync and resume, and the custom events Switch layers on
-
- [The collaboration bridge](collaboration-bridge.md) — The adapter contract, and what it takes to support a new messaging app
- [The agent protocol](agent-protocol.md) — Registration, connections, the event stream, and the operations registry
diff --git a/docs/official/internals/life-of-a-message.md b/docs/official/internals/life-of-a-message.md
index 01f854468..6208c9cee 100644
--- a/docs/official/internals/life-of-a-message.md
+++ b/docs/official/internals/life-of-a-message.md
@@ -4,7 +4,7 @@ _One message traced from a Slack channel to an agent and back, with the componen
Published at <https://docs.flintai.dev/flintai/switch/internals/life-of-a-message> — link readers there, not to this file.
-A message posted in a Slack channel reaches an agent as an ordinary Matrix room event. The reply returns along the same path in reverse.
+A message posted in a Slack channel reaches an agent as an ordinary Switch room event. The reply returns along the same path in reverse.
## The path
@@ -15,39 +15,39 @@ sequenceDiagram
participant P as Person in Slack
participant SA as Slack adapter
participant BC as Bridge core
- participant MX as Matrix room
+ participant RM as Switch room
participant AC as Agent client
participant AG as Agent
P->>SA: message event, over the connection Switch dialed out
SA->>BC: normalized into the inbound model
- BC->>MX: invite the puppet, wait for the join
- Note over BC,MX: a client ignores events that predate its own join
- BC->>MX: puppet posts the message
- MX->>AC: event through sync
+ BC->>RM: invite the puppet, wait for the join
+ Note over BC,RM: a client ignores events that predate its own join
+ BC->>RM: puppet posts the message
+ RM->>AC: event reaches the client
AC->>AC: addressed? name, alias, role, policy
AC->>AG: sequenced in the buffer, pushed over SSE
Note over AC,AG: delivery is not acting
- AG->>MX: reply, through the agent bridge over HTTP
- MX->>BC: bridge client sees the reply
+ AG->>RM: reply, through the agent bridge over HTTP
+ RM->>BC: bridge client sees the reply
BC->>SA: puppet senders skipped, correlation resolved
SA->>P: reply in the channel thread
```
1. **Slack pushes the message.** It arrives on the connection the adapter dialed out when the bridge started. No inbound port is involved.
2. **The adapter normalizes it.** Platform formatting becomes the neutral inbound model: channel and channel type, sender id and name, content, message reference, optional thread root, attachments. Everything past this point is written against that model. See [the collaboration bridge](collaboration-bridge.md).
-3. **The bridge core prepares the puppet.** It maps the channel to its Matrix room, looks up or creates the sender's puppet account, invites it, and waits for the join to land.
-4. **The puppet posts the message.** It is now an ordinary event from an ordinary room member. See [the Matrix substrate](matrix-substrate.md).
-5. **The agent's Matrix client picks it up through sync.** Each client runs its own sync loop against the homeserver.
+3. **The bridge core prepares the puppet.** It maps the channel to its Switch room, looks up or creates the sender's puppet client, invites it, and waits for the join to land.
+4. **The puppet posts the message.** It is now an ordinary event from an ordinary room member.
+5. **The agent's client picks it up.** Each client is delivered the events written to the rooms it belongs to.
6. **Addressing is decided.** By name, by an alias the agent holds in this room, or by a role it holds. The [addressing policy](identity-and-access.md) decides whether this sender may make this agent respond.
7. **The event is buffered and streamed.** It is appended to the agent's sequenced buffer and pushed down the open SSE stream. Each frame carries its sequence number as the SSE id, so a reconnect resumes with `Last-Event-ID`. See [the agent protocol](agent-protocol.md).
-8. **The agent replies.** It posts into the same Matrix room through the agent bridge over HTTP. A session started by Switch Console calls the Switch tool its host serves, and Console or the sidecar makes that request.
+8. **The agent replies.** It posts into the same Switch room through the agent bridge over HTTP. A session started by Switch Console calls the Switch tool its host serves, and Console or the sidecar makes that request.
9. **The bridge client sees the reply.** It is a member of the room, so the reply reaches it like any other event.
10. **The bridge core routes it out.** Known puppet senders are skipped, and the correlation table resolves the external post to reply under.
11. **The adapter posts it in the channel.** In the agent's name, in the right thread.
## The join wait
-A Matrix client ignores events that predate its own join. The bridge core invites the puppet and waits for the join to land before sending, because a message sent in the gap is filtered out at the far end without raising anything.
+A client ignores events that predate its own join. This is Switch's own rule, applied by the client as events reach it, not something PostgreSQL enforces. The bridge core invites the puppet and waits for the join to land before sending, because a message sent in the gap is filtered out at the far end without raising anything.
The same rule applies wherever Switch adds a participant that has to see what happens next. Room creation invites the bridge client before any agent for this reason.
@@ -59,11 +59,11 @@ An agent that sets its filter to `addressed` narrows delivery as well, and stops
## Loop prevention
-The outbound path skips any Matrix event whose sender is a known puppet. Without it, a message relayed in from Slack is relayed straight back out to Slack.
+The outbound path skips any event whose sender is a known puppet. Without it, a message relayed in from Slack is relayed straight back out to Slack.
## Thread correlation
-A durable table maps Matrix event ids to external post ids, written in both directions with a uniqueness constraint on each side, so either id resolves the other. It is what puts a reply in the right thread, and what makes a later edit or delete land on the right post.
+A durable table maps Switch event ids to external post ids, written in both directions with a uniqueness constraint on each side, so either id resolves the other. It is what puts a reply in the right thread, and what makes a later edit or delete land on the right post.
## Other platforms
diff --git a/docs/official/internals/matrix-substrate.md b/docs/official/internals/matrix-substrate.md
deleted file mode 100644
index 98dd64f0f..000000000
--- a/docs/official/internals/matrix-substrate.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# The Matrix substrate
-
-_How every participant becomes a Matrix client, how those clients sync and resume, and the events Switch layers on top_
-
-Published at <https://docs.flintai.dev/flintai/switch/internals/matrix-substrate> — link readers there, not to this file.
-
-Every Switch room is a room on a Matrix homeserver. The homeserver is Tuwunel, running beside `switch-core`. Nobody signs in to it directly, and it is not a user-facing feature.
-
-## Every participant is a real account
-
-Each agent, each system actor, and each person talking from a messaging app has its own Matrix account on the homeserver and its own row in the `clients` table. There is no lightweight virtual-member concept.
-
-A person in Slack is represented by a **puppet** account that posts on their behalf. At the transport layer there is no human-versus-agent distinction, because everyone in the room is a Matrix client.
-
-Creating a client mints an id, derives a Matrix localpart, registers the account on the homeserver, and persists the row. The localpart takes one of the following shapes:
-
-```
-switch-<type>-<short id> a per-participant account
-switch-<type> a system actor, one per instance
-```
-
-## Client types
-
-A type decides what a client is for — which rooms it is invited to, what it does with what it sees. It does not change how the client talks.
-
-| Type | Role in a room |
-| --- | --- |
-| `agent` | A registered agent. One account per agent, joined to every room that agent belongs to. |
-| `user` | A person participating in a room. |
-| `bridge` | The collaboration bridge's own presence in a room. |
-| `resource_manager` | The participant that services resource requests sent into the room. |
-| `admin` | The account Switch speaks as in its own voice, such as admin-owned command output. |
-
-Room membership is tracked in `client_rooms`. Joining a room is an ordinary Matrix invitation, which managed clients accept automatically.
-
-## The sync loop
-
-Each client runs its own `sync_forever` loop against the homeserver with a 30-second timeout, inside a retry loop with exponential backoff. A homeserver blip costs a reconnect, not a dead participant.
-
-Callbacks are registered for the following: text messages, media, reactions, membership changes, invitations, and unknown events. Unknown events are how Switch's own custom types arrive, since the Matrix client library doesn't know them.
-
-## Resume, not re-login
-
-The client row carries the access token, the device id, and the last sync batch token. The batch token is written as sync progresses — throttled, so a busy room doesn't produce a write storm — and forced at login and on a clean stop.
-
-A restart is not a fresh start. The client restores its stored session, resumes the existing Matrix device instead of logging in and creating another one, and syncs from the batch token it last recorded.
-
-```mermaid
-%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
-sequenceDiagram
- autonumber
- participant P as switch-core
- participant C as Client
- participant DB as clients row
- participant HS as Homeserver
- P->>C: process starts, construct client
- C->>DB: read access token, device id, batch token
- DB-->>C: stored session
- C->>HS: restore session on the stored device
- C->>HS: sync since the stored batch token
- HS-->>C: everything recorded since that token
- Note over C,HS: events predating the client's join are filtered out
- C->>DB: persist the new batch token as sync progresses
-```
-
-Messages that arrived while the process was down are still delivered, because the homeserver held them.
-
-Resume covers the Matrix position only. The agent bridge's event buffer is a separate mechanism with its own sequence numbers, held in memory, so a connection's place in it does not survive a restart — the bridge reports a gap to the reader instead of pretending the stream is complete.
-
-## Pre-join events are filtered
-
-**A client ignores events that predate its own join.** Inviting a client to a room does nothing on its own. Until the join lands, anything posted in that room is, for that client, something that happened before it existed.
-
-Wherever Switch needs a client to see what happens next, it waits for the join rather than trusting the invitation:
-
-- Room creation invites the bridge client **first**, before any agent. A message sent before the bridge joins is a pre-join event for the bridge and never reaches the external channel.
-- The collaboration bridge creates or looks up a puppet on an inbound message, invites it, waits for the join to land, and only then sends.
-
-**Note**
-
-Sending before a join lands does not raise an error. The event is filtered and the message is lost silently. If you add a participant and immediately do something you expect it to observe, wait for the join. This comes up again in [the collaboration bridge](collaboration-bridge.md).
-
-## The `com.switch.*` events
-
-Ordinary conversation is ordinary Matrix: text messages, media, reactions. Everything Switch adds is a custom event type under the `com.switch.` namespace, delivered through the unknown-event callback.
-
-| Event type | Carries |
-| --- | --- |
-| `com.switch.command` | A room command, such as the bridged form of a `!` command typed in a messaging app. |
-| `com.switch.agent.runtime_state` | What a live agent session is doing, and what it can be told to do. |
-| `com.switch.permission.request`, `com.switch.permission.response` | A permission round trip in the room. |
-| `com.switch.resource.*` | The resource manager's request-and-response pairs: loading documents and references, and creating, updating or deleting room-scoped documents. |
-| `com.switch.task.*` | The task protocol. Present in the wire format, not yet in use — don't build against it. |
-
-Resource operations are round trips through a server-side participant rather than direct writes, so the check that a document belongs to the room asking for it happens on the server.
-
-### Content markers
-
-These are not event types. They are flags carried on otherwise ordinary events:
-
-- `com.switch.attachment_group`
-- `com.switch.admin`
-- `com.switch.auto_reply`
-
-## Multi-file attachments
-
-Matrix has no native multi-attachment message: a media event carries one file. Messaging platforms allow several files in one post.
-
-Switch sends one media event per file. Every event in the batch carries a shared `com.switch.attachment_group` marker with a group id, the file's index, and the total. The receiving side coalesces the group back into one logical message.
-
-Outbound, the relay buffers a group and flushes it as a single post, so an external channel gets one message with several files rather than a burst. Incomplete groups have their own flush path, so a group missing a file yields the files that did arrive instead of waiting forever.
-
-**Tip**
-
-If you're writing an adapter, treat the group marker as the unit of work. Handling media events one at a time will function and will look wrong in every channel it touches.
-
-## Next steps
-
-- [The collaboration bridge](collaboration-bridge.md) — Puppets, threads and commands — and why the join wait matters there most
-
-- [The agent protocol](agent-protocol.md) — Registration, connections, the event stream, and the operations registry
diff --git a/docs/official/internals/rooms-and-resources.md b/docs/official/internals/rooms-and-resources.md
index 5eee8fcb8..eb0c75016 100644
--- a/docs/official/internals/rooms-and-resources.md
+++ b/docs/official/internals/rooms-and-resources.md
@@ -65,7 +65,7 @@ Room-scoped documents are the agent-writable kind. A room-scoped document is del
An agent can change or delete only a document it created. Authorship is enforced, not advisory.
-Create, update and delete are not direct database writes from the caller's side. Each is a request-and-response round trip over the message bus, serviced by the resource manager client, so the check that the document belongs to the room being asked from runs server-side rather than being trusted to the caller.
+Create, update and delete are not direct database writes from the caller's side. Each is an operation switch-core serves, so the check that the document belongs to the room being asked from runs server-side rather than being trusted to the caller.
### Room groups
@@ -93,11 +93,11 @@ The ecosystem graph and the room-link graph are Gateway-only aggregations built
## Creating a room, in order
-Room creation touches PostgreSQL, the Matrix homeserver and an external chat platform. The order is deliberate, and some of it exists to prevent specific bugs.
+Room creation touches PostgreSQL and an external chat platform. The order is deliberate, and some of it exists to prevent specific bugs.
### Validate everything first
-The attachments and the group id are validated before anything is provisioned, so a request naming a reference that doesn't exist fails while it's still free to fail — no orphaned Matrix room, no stray external channel to clean up.
+The attachments and the group id are validated before anything is provisioned, so a request naming a reference that doesn't exist fails while it's still free to fail — no orphaned room, no stray external channel to clean up.
### Resolve the participants
@@ -115,9 +115,9 @@ If the room is adopting an existing channel and the caller didn't state its type
Creating a channel makes the bot auto-join it, and that join arrives back as an inbound event before the room mapping is committed. Without the mark, the inbound handler doesn't see the uncommitted mapping, concludes the channel is unknown, and creates a second Switch room for the same channel.
-### Create the Matrix room
+### Create the room
-The room on the homeserver is created. Everything after this point takes membership in it.
+The room itself is created. Everything after this point takes membership in it.
### Persist in one transaction
@@ -129,7 +129,7 @@ The channel-to-room mapping is registered and the provisioning mark is cleared i
### Invite the bridge client before any agent
-The bridge client is invited ahead of every agent, because a Matrix client ignores events that predate its own join. A message posted before the bridge joins is filtered as a pre-join event and never reaches the external channel — the room looks alive from inside Switch and silent from Slack.
+The bridge client is invited ahead of every agent, because a client ignores events that predate its own join. A message posted before the bridge joins is filtered as a pre-join event and never reaches the external channel — the room looks alive from inside Switch and silent from Slack.
### Populate the external channel
@@ -137,7 +137,7 @@ The agents and users are added on the platform side, so the channel's membership
### Invite the remaining participants
-The agent clients and the system clients are invited together, and then the membership rows are persisted and committed. Membership is ordinary Matrix invitation, which managed clients auto-accept.
+The agent clients and the system clients are invited together, and then the membership rows are persisted and committed. Membership is an ordinary invitation, which managed clients auto-accept.
### Attach references, packages and links
@@ -149,7 +149,7 @@ Rooms can also be created from a YAML definition through the Gateway, which runs
- **Update** changes metadata, instructions, group membership and the agent list.
- **Delete** removes the room and everything scoped to it, including its room-scoped documents.
-- **Archive** sets a reversible metadata-only flag. The Matrix room, the mapping and the membership stay as they were, and restoring the room brings it back without rerunning the provisioning sequence.
+- **Archive** sets a reversible metadata-only flag. The room, the mapping and the membership stay as they were, and restoring the room brings it back without rerunning the provisioning sequence.
- **Membership changes** add or remove agents and users after the fact, on the same invitation model as creation.
- **Moving a room to a different bridge** re-points it at another external chat connection.
@@ -157,15 +157,15 @@ Rooms can also be created from a YAML definition through the Gateway, which runs
Switch's own state lives in PostgreSQL beside `switch-core`. The tables that carry rooms and resources:
-- `rooms` — the Matrix room plus Switch metadata: bridge, external channel, channel type, instructions, group, owner, visibility, archive flag
+- `rooms` — the room plus Switch metadata: bridge, external channel, channel type, instructions, group, owner, visibility, archive flag
- `room_groups` and `room_links` — the tree, and the directed graph over it
- `room_agents` — which agents are in a room, carrying the alias and the join-event flag
- `room_roles` and `role_leases` — roles defined per room, and who currently holds one
- `references`, `documents`, `packages` and their association tables — the library and what it's attached to
- `agents` — name, description, integration profile, owner, optional parent agent for subagents, addressing policy
-- `clients` and `client_rooms` — one Matrix account per participant, with its sync state, and the rooms it's in
+- `clients` and `client_rooms` — one client per participant, and the rooms it's in
- `collaboration_bridges` — a configured external chat connection; at most one is the default
-- `bridge_message_map` — the Matrix-to-external correlation, written in both directions
+- `bridge_message_map` — the Switch-to-external correlation, written in both directions
- `external_users` and `external_user_claims` — platform identity to puppet client, and the claims linking a platform account to a Switch user
- `agent_sessions` and `agent_runtime_states` — reachability and transport-to-room binding, and what a live session is doing