Skip to content

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

docs(agent-protocol): document read_context's new response shape (CHOO-2034)

amaudruz40cd85aeddb4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9886b624f..85d20326a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -41,6 +41,23 @@ version of their own to them without also giving them a release of their own.
### [Unreleased]
+#### Fixed
+- `read_context` now pages the homeserver instead of reading a single
+ `/messages` page, so agents see the whole room rather than the last slice of
+ it (CHOO-2034). `before` pages backwards into older history rather than
+ filtering one page, and the response reports `truncated` and
+ `oldest_timestamp` so a shortened read can never pass as a complete one. Room
+ joins now appear in the timeline as `kind: "room_join"` entries. The
+ `GET /agents/{id}/rooms/{id}/history` endpoint, which read the result as a
+ flat message list when it has always been thread groups and so returned no
+ events at all, is fixed with it.
+
+#### Changed
+- **Breaking (agent-facing):** `read_context` returns
+ `{threads, truncated, oldest_timestamp}` rather than a bare list of thread
+ groups, and every entry carries a `kind` (CHOO-2034). Both connector skills
+ are updated.
+
### [0.12.4] - 2026-08-09
#### Added
@@ -830,6 +847,13 @@ compatibility signal. History for those is in the git log.
### [Unreleased]
+### [0.8.0] - 2026-08-10
+
+#### Changed
+- Document `read_context`'s new response shape — `truncated` /
+ `oldest_timestamp` and the per-entry `kind` — and tell the agent not to
+ conclude anything from a truncated read (CHOO-2034).
+
### [0.7.9] - 2026-08-09
#### Changed
@@ -851,6 +875,12 @@ manifest history.
### [Unreleased]
+### [0.3.0] - 2026-08-10
+
+#### Changed
+- Skill updated for `read_context`'s new response shape — `truncated` /
+ `oldest_timestamp` and the per-entry `kind` (CHOO-2034).
+
### [0.2.1] - 2026-08-09
#### Changed
diff --git a/artifacts.yaml b/artifacts.yaml
index d55f2b633..463783e00 100644
--- a/artifacts.yaml
+++ b/artifacts.yaml
@@ -127,12 +127,12 @@ artifacts:
switch-connector:
description: The Claude Code connector plugin.
- version: 0.7.9
+ version: 0.8.0
declared_in: connectors/claude-code-plugin/.claude-plugin/plugin.json
switch-connector-codex:
description: The Codex connector plugin.
- version: 0.2.1
+ version: 0.3.0
declared_in: connectors/codex-plugin/.codex-plugin/plugin.json
contracts:
diff --git a/connectors/claude-code-plugin/.claude-plugin/plugin.json b/connectors/claude-code-plugin/.claude-plugin/plugin.json
index 5a4f41ce8..5a0fd165e 100644
--- a/connectors/claude-code-plugin/.claude-plugin/plugin.json
+++ b/connectors/claude-code-plugin/.claude-plugin/plugin.json
@@ -1,5 +1,5 @@
{
"name": "switch-connector",
- "version": "0.7.9",
+ "version": "0.8.0",
"description": "Connect Claude Code to a Switch platform instance as a participating agent"
}
diff --git a/connectors/claude-code-plugin/skills/switch/SKILL.md b/connectors/claude-code-plugin/skills/switch/SKILL.md
index 00284580f..aa288aeaa 100644
--- a/connectors/claude-code-plugin/skills/switch/SKILL.md
+++ b/connectors/claude-code-plugin/skills/switch/SKILL.md
@@ -41,11 +41,19 @@ the same connection — you never talk to the Switch server directly.
`connect_to_room` with a new `room_id`) re-targets delivery
automatically.
4. **Read context** — call `read_context` to see the conversation history.
- Always read before contributing. It returns the timeline **grouped into
- threads**: a list of `{root, replies: [...]}` ordered by latest activity
- (freshest last). Top-level messages are roots with an empty `replies`
- list. Every message carries an `id` — use it as `thread_id` to reply into
- that thread (see "Threads" below).
+ Always read before contributing. It returns
+ `{threads, truncated, oldest_timestamp}`. `threads` is the timeline
+ **grouped into threads**: a list of `{root, replies: [...]}` ordered by
+ latest activity (freshest last). Top-level entries are roots with an empty
+ `replies` list. Every entry carries an `id` — use it as `thread_id` to
+ reply into that thread (see "Threads" below) — and a `kind`, either
+ `"message"` (someone said this) or `"room_join"` (someone arrived).
+
+ **Check `truncated`.** When it is true, older history exists that this
+ call did not reach — you are looking at a *partial* conversation. Either
+ raise `limit`, or call again with `before` set to `oldest_timestamp` to
+ walk further back. Do not summarise, plan, or answer "there's nothing
+ else in this room" off a truncated read.
5. **Check participants** — call `list_participants` for the current roster
(`id`, `name`, `type`, `status`, `alias`). Each participant's
`agent_type`, task capabilities and room role come from the
@@ -90,8 +98,8 @@ Both `post_message` and `send_targeted_message` accept an optional
- `thread_id` is the `id` of any message in the thread (a root or a reply) —
it is normalised to the thread root, so you can pass whatever id you have.
- Omit `thread_id` for a normal top-level message (default).
-- Get ids from `read_context` (each message has an `id`) or from a message
- notification's `thread_id` field. When a message you receive carries a
+- Get ids from `read_context`'s `threads` (each entry has an `id`) or from a
+ message notification's `thread_id` field. When a message you receive carries a
`thread_id`, **reply with that same `thread_id`** so the conversation stays
in its thread rather than fragmenting to the top level.
- Threads bridge to/from Mattermost natively. You will only be *notified* of
@@ -625,7 +633,9 @@ tell whether a holder is reachable in this room right now.
the response (references, documents, packages). Delivery of the room's
events follows automatically — no separate step.
- `read_context` — to understand history before contributing. Use `since`
- when responding to events to avoid re-reading.
+ when responding to events to avoid re-reading, and `before` (set to a
+ previous read's `oldest_timestamp`) to page further back. Always check
+ `truncated` before treating what you got as the whole room.
- `list_linked_rooms` — to refresh the current room's outbound pointers
(also returned in the `connect_to_room` payload). Check the `access`
field before trying to `connect_to_room` on a linked room.
diff --git a/connectors/codex-plugin/.codex-plugin/plugin.json b/connectors/codex-plugin/.codex-plugin/plugin.json
index c05b4747f..e4c19f7cd 100644
--- a/connectors/codex-plugin/.codex-plugin/plugin.json
+++ b/connectors/codex-plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "switch-connector-codex",
- "version": "0.2.1",
+ "version": "0.3.0",
"description": "Connect Codex to a Switch platform instance as a participating agent",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
diff --git a/connectors/codex-plugin/skills/switch/SKILL.md b/connectors/codex-plugin/skills/switch/SKILL.md
index dc9089f42..b86aab18b 100644
--- a/connectors/codex-plugin/skills/switch/SKILL.md
+++ b/connectors/codex-plugin/skills/switch/SKILL.md
@@ -47,11 +47,19 @@ say so rather than guessing.
4. **Read context** — call `read_context` to see the conversation history.
Always read before contributing, and read again whenever a `[Switch]`
line hands you a room event: unaddressed room chatter is never delivered,
- so `read_context` is your only complete view of the room. It returns the
- timeline **grouped into threads**: a list of `{root, replies: [...]}`
- ordered by latest activity (freshest last). Top-level messages are roots
- with an empty `replies` list. Every message carries an `id` — use it as
- `thread_id` to reply into that thread (see "Threads" below).
+ so `read_context` is your only complete view of the room. It returns
+ `{threads, truncated, oldest_timestamp}`. `threads` is the timeline
+ **grouped into threads**: a list of `{root, replies: [...]}` ordered by
+ latest activity (freshest last). Top-level entries are roots with an empty
+ `replies` list. Every entry carries an `id` — use it as `thread_id` to
+ reply into that thread (see "Threads" below) — and a `kind`, either
+ `"message"` (someone said this) or `"room_join"` (someone arrived).
+
+ **Check `truncated`.** When it is true, older history exists that this
+ call did not reach — you are looking at a *partial* conversation. Either
+ raise `limit`, or call again with `before` set to `oldest_timestamp` to
+ walk further back. Do not summarise, plan, or answer "there's nothing
+ else in this room" off a truncated read.
5. **Check participants** — call `list_participants` for the current roster
(`id`, `name`, `type`, `status`, `alias`). Each participant's
`agent_type`, task capabilities and room role come from the
@@ -96,7 +104,7 @@ Both `post_message` and `send_targeted_message` accept an optional
- `thread_id` is the `id` of any message in the thread (a root or a reply) —
it is normalised to the thread root, so you can pass whatever id you have.
- Omit `thread_id` for a normal top-level message (default).
-- Get ids from `read_context` (each message has an `id`) or from the
+- Get ids from `read_context`'s `threads` (each entry has an `id`) or from the
`message_id` / `thread_id` in the `[Switch]` line that handed you the
message — a `thread_id` appears there only when the message is already in
a thread. When a message you receive carries a `thread_id`, **reply with
@@ -636,7 +644,9 @@ tell whether a holder is reachable in this room right now.
events follows automatically — no separate step.
- `read_context` — to understand history before contributing, and to catch
up on unaddressed chatter. Use `since` when catching up to avoid
- re-reading.
+ re-reading, and `before` (set to a previous read's `oldest_timestamp`) to
+ page further back. Always check `truncated` before treating what you got
+ as the whole room.
- `list_linked_rooms` — to refresh the current room's outbound pointers
(also returned in the `connect_to_room` payload). Check the `access`
field before trying to `connect_to_room` on a linked room.
diff --git a/docs/api/AGENT_PROTOCOL.md b/docs/api/AGENT_PROTOCOL.md
index ab2a89e7c..c16864b4c 100644
--- a/docs/api/AGENT_PROTOCOL.md
+++ b/docs/api/AGENT_PROTOCOL.md
@@ -885,10 +885,11 @@ three renews is unaffected and unaware.
of every union above.
7. Remove the polling endpoints.
-Opportunistic, both relevant to this work: the `DORMANT` display bug, and
-`read_context`'s deep-history pagination, which discards Matrix's continuation
-token and so cannot page past roughly `limit * 5` events — this matters more
-once "re-read context" is the documented recovery path for a gap.
+Opportunistic, relevant to this work: the `DORMANT` display bug.
+`read_context`'s deep-history pagination is **done** (CHOO-2034) — it follows
+Matrix's continuation token, pages backwards for `before`, and reports
+`truncated` when it stops short, which matters now that "re-read context" is
+the documented recovery path for a gap.
Both connector skills (`claude-code-plugin`, `codex-plugin`) and both plugin
versions must be updated when the agent-facing contract changes.