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: give every artifact a version it means and a changelog (CHOO-1865)

Louis Amaudruz7f80c4c62796
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a969b965f..58421e8e9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,15 +5,35 @@ All notable changes to Switch are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project aims to adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-Switch ships two independently-versioned artifacts, tracked in the two sections
-below:
-
-- **switch-core** — the backend service (`core/`) and the operator dashboard
- (`gateway/`). Released by tagging `switch-v<version>`; the version lives in
- `core/pyproject.toml`. See [RELEASING.md](RELEASING.md).
+Switch ships several independently-versioned artifacts, each with its own
+section below. Every artifact carries three-part semver (`MAJOR.MINOR.PATCH`)
+and a changelog, without exception (CHOO-1865).
+
+A version says **where an artifact is** — which release you are running. It says
+nothing about what that release can talk to. Compatibility is carried separately
+by the contract revisions in [`contracts.yaml`](contracts.yaml), which move
+independently: a release that changes nothing on the wire bumps its version and
+leaves its contracts alone.
+
+- **switch-core** — the backend service (`core/`). Released by tagging
+ `switch-v<version>`; the version lives in `core/pyproject.toml`. See
+ [RELEASING.md](RELEASING.md).
- **switchdash** — the desktop app (`dash/`). Released by tagging
`switchdash-v<version>`; the version lives in
`dash/apps/switchdash-desktop/package.json`.
+- **agent-runtime** — the Switch protocol client and MCP runtime
+ (`dash/packages/switch-agent-runtime/`), published to a package registry.
+- **sidecar** — the remote runtime switchdash deploys to an agent host
+ (`dash/apps/switchdash-desktop/src/sidecar/`). Versioned in
+ `sidecar-version.ts` and deployed by switchdash, not published separately.
+- **switch-connector** / **switch-connector-codex** — the two connector plugins
+ (`connectors/`), versioned in their respective plugin manifests.
+
+Three things are **not** separately versioned, and ship under the switch-core
+release so a single tag pins the whole stack: the **operator dashboard**
+(`gateway/`), the **Helm chart**, and the **standalone compose artifact**. Their
+versions are stamped at package time from the switch-core version; do not add a
+version of their own to them without also giving them a release of their own.
---
@@ -21,6 +41,38 @@ below:
### [Unreleased]
+#### Added
+- Cross-artifact version compatibility, part 1 — every artifact declares what it
+ is and what it speaks (CHOO-1865). `contracts.yaml` is the one authored
+ registry of contract revisions; per-language modules are generated from it and
+ CI fails if they are stale or hand-edited. switch-core reads its own release
+ version, discloses it and its ranges on authenticated surfaces only (the
+ `connection_state` frame, the 409 refusal body, the gateway session response,
+ and an authenticated credential-scoped `GET /version`), and records what each
+ client declared. **Nothing acts on the declarations yet** — a client that
+ declares nothing connects exactly as before.
+- The authentication surface is now **frozen**: never versioned, permanently
+ backward-compatible, and excluded from `gateway-api`, so a client can always
+ authenticate far enough to be told what is wrong (CHOO-1865).
+
+#### Fixed
+- The agent-protocol check no longer defaults a silent client to the server's own
+ version. It defaulted to agreement, and since no shipped client ever sent
+ `?protocol=`, the check had never once fired. Absent now records as unknown —
+ and still connects (CHOO-1865).
+- A protocol refusal names which side is behind. It always said "update the
+ Switch agent runtime", which for a client ahead of the server sent the user to
+ downgrade the side that was already right (CHOO-1865).
+- The compatibility check is a range overlap rather than exact equality. The two
+ numbers are equal today, so nothing changes yet (CHOO-1865).
+- `SWITCH_VERSION` is required by the standalone compose instead of defaulting to
+ `latest`, which silently floated the whole stack to whatever had most recently
+ been published (CHOO-1865).
+- The Helm chart no longer claims a version it has not been at for months. The
+ real one is stamped at package time; the file now says `0.0.0-dev` (CHOO-1865).
+- Refreshed the stale switch-core version in `uv.lock`, which the release
+ procedure never re-locked (CHOO-1865).
+
### [0.12.3] - 2026-08-07
#### Added
@@ -216,6 +268,24 @@ below:
### [Unreleased]
+#### Added
+- Declares its `sidecar-control` range in the sidecar's ready file, and reads
+ back whatever a running sidecar declares. A sidecar that declares nothing
+ records as unknown, never as agreement (CHOO-1865).
+
+#### Fixed
+- A managed server whose deployed switch-core version **cannot be read** is now
+ surfaced as such, in the banner and the sidebar. It previously reported "no
+ drift" — the identical result a healthy, in-step stack gives — so a failed
+ probe rendered as a green server and the user was told nothing (CHOO-1865).
+- Starting a stack whose version cannot be compared to this build's pin now says
+ so loudly. It passed in complete silence, in the same branch as a clean match,
+ while carrying the same risk as a downgrade (CHOO-1865).
+- CI verifies the bundled standalone compose is in step with the repo's copy.
+ Nothing checked before — the two could drift with only a comment asking
+ nicely, which is how the sync script once silently stopped running
+ (CHOO-1865).
+
### [0.19.2] - 2026-08-07
#### Added
@@ -657,3 +727,83 @@ migrations 0031–0036, including a locations backfill).
Desktop-app releases predating this changelog live in the git log and in the
per-release notes on their GitHub Releases (`switchdash-v*` tags).
+
+---
+
+## agent-runtime
+
+The Switch protocol client and MCP runtime
+(`dash/packages/switch-agent-runtime/`). Version lives in its `package.json`.
+
+### [Unreleased]
+
+#### Added
+- Declares its `agent-protocol` range, artifact name and release version on the
+ event stream it already opens, so switch-core can record what is connecting
+ (CHOO-1865).
+- Logs the server's declaration from the `connection_state` frame, so which
+ versions were actually talking to each other is answerable from a bug report
+ rather than a guess (CHOO-1865).
+
+### [0.1.5]
+
+Releases before this changelog existed are in the git log. They are not
+reconstructed here: an invented history reads exactly like a real one.
+
+---
+
+## sidecar
+
+The remote runtime switchdash deploys to an agent host. Versioned in
+`dash/apps/switchdash-desktop/src/sidecar/sidecar-version.ts` and deployed by
+switchdash rather than published on its own.
+
+### [Unreleased]
+
+#### Changed
+- Three-part semver: `1.7` becomes `1.7.0`. **The major stays at 1** — every
+ switchdash already in the field judges compatibility on the major and parses
+ two parts, so `1.7` and `1.7.0` read as the same version and neither side
+ replaces the other. `2.0.0` would have every existing install treat this
+ sidecar as incompatible and replace it while a newer install replaces it back
+ (CHOO-1937, CHOO-1865).
+- The version no longer carries compatibility. It says which release is running;
+ what the sidecar can speak is the `sidecar-control` range it now declares in
+ its ready file (CHOO-1865).
+
+### [1.7]
+
+Earlier versions used a two-part `x.y` scheme in which the major *was* the
+compatibility signal. History for those is in the git log.
+
+---
+
+## switch-connector (Claude Code)
+
+`connectors/claude-code-plugin/`. Version lives in
+`.claude-plugin/plugin.json`.
+
+### [Unreleased]
+
+_No changes yet. The plugin ships the room-workflow skill; CHOO-1865 changed
+nothing an agent-facing client needs to know, so it is deliberately unbumped._
+
+### [0.7.8]
+
+Releases before this changelog existed are in the git log and in the plugin
+manifest history.
+
+---
+
+## switch-connector-codex
+
+`connectors/codex-plugin/`. Version lives in `.codex-plugin/plugin.json`.
+
+### [Unreleased]
+
+_No changes yet, and deliberately unbumped — see the note above._
+
+### [0.2.0]
+
+Releases before this changelog existed are in the git log and in the plugin
+manifest history.
diff --git a/RELEASING.md b/RELEASING.md
index 08bd0b88e..3fe8da394 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -8,11 +8,40 @@ standalone Docker Compose file. The switchdash desktop app releases separately
## Versioning
- Switch follows [Semantic Versioning](https://semver.org): `MAJOR.MINOR.PATCH`.
+ Every artifact carries three parts and a changelog, without exception.
- The canonical `switch-core` version is `version` in `core/pyproject.toml`.
- The Helm chart, the three images, and the standalone compose artifact are
published under the **same** version as the git tag, so a single tag pins the
whole stack.
+**A version says where an artifact is, not what it can talk to.** Compatibility
+is carried separately, by the contract revisions in
+[`contracts.yaml`](contracts.yaml). The two move independently: a release that
+changes nothing on the wire bumps its version and leaves its contracts alone.
+Never derive one from the other.
+
+### What is, and is not, separately versioned
+
+The **operator dashboard** (`gateway/`), the **Helm chart**, and the **standalone
+compose artifact** have no version of their own. They ship inside the switch-core
+release and are stamped with its version at package time, which is what lets a
+single tag pin the whole stack. They are documented as part of switch-core in
+`CHANGELOG.md` rather than given sections of their own.
+
+Do not give any of them a version without also giving it a release of its own —
+a version nobody publishes independently is a number that drifts from reality,
+which is exactly what `Chart.yaml` did while it claimed `0.2.1`.
+
+The separately-versioned artifacts are switch-core, switchdash, the
+agent-runtime package, the sidecar, and the two connector plugins.
+
+### Bumping a contract
+
+When you change an interface named in `contracts.yaml`, raise that artifact's
+`speaks` for the contract and run `just contracts`. Raise `accepts` only when
+dropping support for an older revision — that is a breaking change for every
+peer still on it, and it can never be raised past what is running in the field.
+
## Cutting a release
1. **Bump the version** in `core/pyproject.toml` (`[project].version`).
diff --git a/deploy/remote/helm/switch/Chart.yaml b/deploy/remote/helm/switch/Chart.yaml
index bd4d06438..c19780206 100644
--- a/deploy/remote/helm/switch/Chart.yaml
+++ b/deploy/remote/helm/switch/Chart.yaml
@@ -2,5 +2,15 @@ apiVersion: v2
name: switch
description: Switch AI agent orchestration platform
type: application
-version: 0.2.1
-appVersion: "0.2.1"
+# Placeholder, and deliberately one that announces itself as such (CHOO-1865).
+#
+# The real version is stamped at package time by the switch-release workflow
+# (`helm package --version --app-version`) with the switch-core release version,
+# so the chart ships under the same version as the images and a single tag pins
+# the whole stack. The value in this file is never published.
+#
+# It used to read `0.2.1`, which was simply untrue: nothing kept it in step, so
+# anyone reading the repo saw a version the chart had not been at for months.
+# `0.0.0-dev` cannot be mistaken for a release.
+version: 0.0.0-dev
+appVersion: "0.0.0-dev"
diff --git a/docs/api/AGENT_PROTOCOL.md b/docs/api/AGENT_PROTOCOL.md
index 7d0eaf60f..ab2a89e7c 100644
--- a/docs/api/AGENT_PROTOCOL.md
+++ b/docs/api/AGENT_PROTOCOL.md
@@ -278,7 +278,11 @@ Accept: text/event-stream
filter all | addressed
start_from head | <sequence number> (default head)
spawn_capable bool (default false)
- protocol protocol version
+
+ protocol newest agent-protocol revision the client implements
+ protocol_accepts oldest it still handles (default: same as protocol)
+ client artifact name, e.g. agent-runtime
+ client_version that artifact's semver
```
The client generates the connection id, which makes opening **idempotent**: a
@@ -289,9 +293,40 @@ be treated as a secret. An id belonging to a different agent is rejected.
The server responds with an open `text/event-stream` and sends the connection's
state as the first event.
-**Protocol version is checked at open.** An incompatible client is refused with
-a message telling the user to update. The runtime lives on the user's machine
-and Switch moves independently; silent degradation is not acceptable.
+**The four declaration parameters are optional, and absent means _unknown_.** A
+client built before they existed says nothing, and unknown is a state the model
+carries deliberately — it is not incompatible, and such a client connects
+normally (CHOO-1865). `protocol` previously defaulted to the server's own value,
+which read silence as agreement; since no shipped client sent it, the check had
+never once fired.
+
+`client` and `client_version` say which released artifact is connecting and
+where it is. They are recorded and reported, never judged: a semver says nothing
+about compatibility. That is what the contract revisions are for.
+
+**A declared protocol range is checked at open.** Client and server are
+compatible when their `[accepts, speaks]` ranges **overlap** — not when they are
+equal — and they then operate at the lower of the two `speaks`. A client whose
+range cannot meet the server's is refused with a `409` whose body carries both
+ranges and names which side is behind:
+
+```json
+{
+ "detail": {
+ "message": "...",
+ "contract": "agent-protocol",
+ "server": { "version": "0.12.3", "speaks": 1, "accepts": 1 },
+ "client": { "speaks": 2, "accepts": 2 },
+ "remedy": "update switch-core"
+ }
+}
+```
+
+The refusal carries the ranges because a refused client never receives a
+`connection_state` frame, so this is its only chance to learn what the server
+speaks. The runtime lives on the user's machine and Switch moves independently;
+silent degradation is not acceptable, and neither is a refusal that leaves the
+user guessing which side to move.
### 5.2 Heartbeat
@@ -447,7 +482,7 @@ New, carried on the same stream:
| type | payload | meaning |
|---|---|---|
-| `connection_state` | `connection_id`, `scope`, `filter`, `rooms`, `cursor`, `protocol` | first event on every stream |
+| `connection_state` | `connection_id`, `scope`, `filter`, `rooms`, `cursor`, `protocol`, `server`, `client` | first event on every stream |
| `subscription_changed` | `rooms`, `reason` | scope changed — including a room going dark because another connection claimed it |
| `gap` | `from_sequence`, `reason` | events were dropped; re-read context. Carried to the agent on the next surfaced event, not as a wake of its own (§4.2) |
| `evicted` | `reason` | this connection lost its slot or was taken over; it must stop acting |
@@ -455,6 +490,28 @@ New, carried on the same stream:
`gap` and `evicted` exist so that degradation is always visible. A client that
has missed events must never appear healthy.
+**`connection_state` is where the server declares itself** (CHOO-1865). It is
+the first frame of an already-authenticated stream, so no separate endpoint —
+and no unauthenticated one — is needed:
+
+```json
+{
+ "server": {
+ "version": "0.12.3",
+ "contracts": { "agent-protocol": { "speaks": 1, "accepts": 1 } }
+ },
+ "client": { "speaks": 1, "accepts": 1, "artifact": "agent-runtime", "version": "0.1.5" }
+}
+```
+
+`server.version` is `null` when switch-core cannot read its own version. Null
+means unknown and must be rendered as such, never as current. `db-schema` is
+internal to switch-core and appears in no externally facing response.
+
+`client` echoes back what the server understood the client to have said, with
+`null` for anything it did not. A declaration that silently failed to parse is
+worse than one never sent, because both sides believe it landed.
+
---
## 7. Operations (agent → server)
@@ -739,7 +796,8 @@ Fail loud, never fake. Concretely:
| room slot already claimed | reject, naming the incumbent — except `connect_to_room`, which takes over and reports what it evicted |
| slot taken over | incumbent's rooms change; it receives `subscription_changed` and goes dark on that room |
| server restart | cursors invalidated; clients told to re-read |
-| incompatible protocol version | refuse at open with an upgrade message |
+| non-overlapping protocol ranges | refuse at open; the 409 body carries both ranges and names which side is behind |
+| client declares no protocol range | record as unknown and admit — unknown is not incompatible |
| per-agent connection cap exceeded | reject loudly |
A connection that has silently missed events must never appear healthy.