Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
docs(agent-protocol): document read_context's new response shape (CHOO-2034)
amaudruz40cd85aeddb4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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#### Changeddiff --git a/artifacts.yaml b/artifacts.yamlindex 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.0declared_in: connectors/claude-code-plugin/.claude-plugin/plugin.jsonswitch-connector-codex:description: The Codex connector plugin.- version: 0.2.1+ version: 0.3.0declared_in: connectors/codex-plugin/.codex-plugin/plugin.jsoncontracts:diff --git a/connectors/claude-code-plugin/.claude-plugin/plugin.json b/connectors/claude-code-plugin/.claude-plugin/plugin.jsonindex 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.mdindex 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 deliveryautomatically.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 staysin 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'sevents 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.jsonindex 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.mdindex 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 themessage — a `thread_id` appears there only when the message is already ina 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 catchup 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.mdindex 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 pluginversions must be updated when the agent-facing contract changes.