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: give every artifact a version it means and a changelog (CHOO-1865)
Louis Amaudruz7f80c4c62796
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 theper-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.mdindex 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 arepublished under the **same** version as the git tag, so a single tag pins thewhole 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 release1. **Bump the version** in `core/pyproject.toml` (`[project].version`).diff --git a/deploy/remote/helm/switch/Chart.yaml b/deploy/remote/helm/switch/Chart.yamlindex bd4d06438..c19780206 100644--- a/deploy/remote/helm/switch/Chart.yaml+++ b/deploy/remote/helm/switch/Chart.yaml@@ -2,5 +2,15 @@ apiVersion: v2name: switchdescription: Switch AI agent orchestration platformtype: 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.mdindex 7d0eaf60f..ab2a89e7c 100644--- a/docs/api/AGENT_PROTOCOL.md+++ b/docs/api/AGENT_PROTOCOL.md@@ -278,7 +278,11 @@ Accept: text/event-streamfilter all | addressedstart_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'sstate 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 thathas 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.