Skip to content

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

Record official template revisions at release time

Simon Flack915c547bf891
diff --git a/.github/workflows/switch-release.yml b/.github/workflows/switch-release.yml
index 42ea157ff..8461ec168 100644
--- a/.github/workflows/switch-release.yml
+++ b/.github/workflows/switch-release.yml
@@ -184,6 +184,21 @@ jobs:
echo "channel=$channel"
} | tee -a "$GITHUB_OUTPUT"
+ - name: Set up uv
+ if: ${{ steps.version.outputs.channel == 'release' }}
+ uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+ with:
+ python-version: '3.12'
+ enable-cache: true
+
+ - name: Refuse an official template change with no revision
+ # A release records a revision for each official template it changed
+ # (RELEASING.md); the agents an older revision created are brought up
+ # to it when the released server starts. Only on a release tag: an RC
+ # or a dev build serves a changed template under its last revision.
+ if: ${{ steps.version.outputs.channel == 'release' }}
+ run: uv run --project core python -m switch_core.official_templates.revisions check
+
- name: List the images
# scripts/pin_chart_images.py is the one list of first-party images; the
# build matrix, the pin and the recorded pins all come from it.
diff --git a/RELEASING.md b/RELEASING.md
index e56a6112a..9a79f327c 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -62,10 +62,18 @@ 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`).
+ With it, **record the official templates' revisions**: `just
+ record-template-revisions` adds one for each template that comes with
+ Switch (switch-buddy, the Switch expert) whose files changed since the last
+ release. Agents those templates created are brought up to the new revision
+ when the released server starts; see "Installs and updates" in
+ `docs/TEMPLATES.md`. The workflow refuses the tag while a change is
+ unrecorded.
2. **Update `CHANGELOG.md`**: under the `## switch-core` section, move the
`### [Unreleased]` items under a new `### [X.Y.Z]` heading and note the date.
(The desktop app has its own `## switch-console` section, versioned separately.)
-3. **Commit** the bump + changelog on a release branch and merge to `main`.
+3. **Commit** the bump, the revisions and the changelog on a release branch and
+ merge to `main`.
4. **Tag and push**: the tag MUST be `switch-v<version>` and match
`core/pyproject.toml` (the workflow verifies this and fails on mismatch):
```bash
diff --git a/core/switch_core/official_templates/__init__.py b/core/switch_core/official_templates/__init__.py
index 1008e1893..cb67fd5cf 100644
--- a/core/switch_core/official_templates/__init__.py
+++ b/core/switch_core/official_templates/__init__.py
@@ -21,9 +21,9 @@ Each also has ``revisions.json``: every revision of it released, numbered
from 1, with a fingerprint of what each one served and set on its agents.
The last is the revision this release serves (its ``version``), and agents
created from an older one are brought up to it when the server starts
-(``management/template_updates.py``). Changing a template means adding a revision, which
-``python -m switch_core.official_templates.revisions record <slug>`` does; a
-test fails while the files and the last revision disagree.
+(``management/template_updates.py``). Revisions are recorded at release time,
+with the other versions (see ``revisions.py``); between releases a changed
+template is served under its last revision.
"""
from __future__ import annotations
diff --git a/core/switch_core/official_templates/revisions.py b/core/switch_core/official_templates/revisions.py
index 280aca83a..53024548b 100644
--- a/core/switch_core/official_templates/revisions.py
+++ b/core/switch_core/official_templates/revisions.py
@@ -8,12 +8,17 @@ were recorded are matched against the ``agents`` fingerprints of every
revision, so an old buddy nobody changed is recognised as the revision it
came from.
-When a template's files change, record a revision::
+Revisions are recorded when Switch is released, with the other versions
+(RELEASING.md), never by whoever changes a template: a revision is what a
+release shipped. Between releases, a changed template is served under its
+last recorded revision, and the agents it already made are not updated until
+a release records the next one. To record one for every template whose files
+changed::
- python -m switch_core.official_templates.revisions record switch-buddy
+ just record-template-revisions
-and ``check`` (or the test that runs it) says whether every template's last
-revision is what its files serve now.
+``check`` says which templates changed since their last revision; the
+release workflow runs it on a release tag and stops the release when any did.
"""
from __future__ import annotations
@@ -95,19 +100,40 @@ def write(slug: str, revisions: list[dict[str, Any]]) -> None:
)
+def record_all() -> dict[str, int]:
+ """Record a revision for every official template whose files changed
+ since its last one; return the revision each one recorded."""
+ return {
+ shipped.slug: record(shipped.slug)
+ for shipped in _SHIPPED
+ if stale(shipped.slug)
+ }
+
+
def main(argv: list[str]) -> int:
if len(argv) == 2 and argv[0] == "record":
print(f"{argv[1]}: revision {record(argv[1])}")
return 0
+ if argv == ["record-all"]:
+ recorded_now = record_all()
+ for slug, revision in recorded_now.items():
+ print(f"{slug}: recorded revision {revision}")
+ if not recorded_now:
+ print("No official template changed since its last revision.")
+ return 0
if argv == ["check"]:
out = [shipped.slug for shipped in _SHIPPED if stale(shipped.slug)]
for slug in out:
print(
f"{slug} changed since its last revision: run "
- f"python -m switch_core.official_templates.revisions record {slug}"
+ "`just record-template-revisions` and commit the result with "
+ "the release's version bump (RELEASING.md)"
)
return 1 if out else 0
- print("usage: revisions record <slug> | revisions check", file=sys.stderr)
+ print(
+ "usage: revisions record-all | revisions record <slug> | revisions check",
+ file=sys.stderr,
+ )
return 2
diff --git a/core/tests/switch_core/management/test_agent_operations.py b/core/tests/switch_core/management/test_agent_operations.py
index 6ba48c5d3..73e74026e 100644
--- a/core/tests/switch_core/management/test_agent_operations.py
+++ b/core/tests/switch_core/management/test_agent_operations.py
@@ -13,6 +13,7 @@ from __future__ import annotations
import hashlib
import secrets
from collections.abc import AsyncIterator, Iterator
+from pathlib import Path
from typing import Any
import httpx
@@ -20,6 +21,7 @@ import pytest
from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+import switch_core.official_templates as official_templates_package
from switch_core.addressing import default_agent_policy, parse_policy
from switch_core.bridges.agent.mcp.server import mcp
from switch_core.bridges.agent.operations import all_operations, definitions
@@ -1541,6 +1543,9 @@ class TestTheConsoleRunsAVersion2Template:
assert "claude is not signed in on laptop" in body["detail"]
+_OFFICIAL = Path(official_templates_package.__file__).parent
+
+
async def _installs(harness: Harness, template_id: str) -> list[Any]:
async with harness.session_factory() as session:
installs = await TemplateInstallStore().of_template(session, template_id)
@@ -1612,7 +1617,7 @@ class TestARunOfAKnownTemplateIsRecorded:
assert (resource.key, resource.agent_id) == ("buddy", created["agent_id"])
assert (
resource.fingerprints
- == revisions.recorded("switch-buddy")[-1]["agents"]["buddy"]
+ == revisions.entry_for(_OFFICIAL / "switch-buddy")["agents"]["buddy"]
)
async def test_a_saved_template_named_by_id_is_recorded_at_its_version(
diff --git a/core/tests/switch_core/management/test_template_updates.py b/core/tests/switch_core/management/test_template_updates.py
index 75440e08d..e92925aa5 100644
--- a/core/tests/switch_core/management/test_template_updates.py
+++ b/core/tests/switch_core/management/test_template_updates.py
@@ -8,6 +8,7 @@ from __future__ import annotations
import asyncio
from collections.abc import AsyncIterator, Iterator
from dataclasses import replace
+from pathlib import Path
from typing import Any
import httpx
@@ -15,6 +16,7 @@ import pytest
from sqlalchemy import func, select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+import switch_core.official_templates as official_templates_package
from switch_core.bridges.agent.operations import context as op_context
from switch_core.bridges.agent.operations import template_status
from switch_core.bridges.agent.operations.callctx import (
@@ -33,11 +35,13 @@ from switch_core.db.stores.agent_definition_store import DefinitionChanged
from switch_core.db.stores.template_install_store import TemplateInstallStore
from switch_core.gateway import dependencies as gw_deps
from switch_core.gateway.rooms import router as rooms_router
+from switch_core.management import template_updates as template_updates_module
from switch_core.management.template_updates import BUDDY_ID, TemplateUpdates
from switch_core.official_templates import (
OfficialTemplate,
official_template,
released_agent_fingerprints,
+ revisions,
)
from tests.switch_core.management.harness import (
Harness,
@@ -83,6 +87,26 @@ async def client(harness: Harness) -> AsyncIterator[httpx.AsyncClient]:
yield client
+_OFFICIAL = Path(official_templates_package.__file__).parent
+
+
[email protected](autouse=True)
+def _released_as_served(monkeypatch: pytest.MonkeyPatch) -> None:
+ """As on a released server: the template's files are its last recorded
+ revision, even on a branch that changed them since."""
+ current = revisions.entry_for(_OFFICIAL / "switch-buddy")["agents"]
+ older = [
+ (revision, agents)
+ for revision, agents in released_agent_fingerprints("switch-buddy")
+ if revision != _buddy().version
+ ]
+ monkeypatch.setattr(
+ template_updates_module,
+ "released_agent_fingerprints",
+ lambda slug: [(_buddy().version, current), *older],
+ )
+
+
def _buddy() -> OfficialTemplate:
buddy = official_template(BUDDY_ID, True, switch_buddy=True)
assert buddy is not None
@@ -296,7 +320,7 @@ async def test_an_old_buddy_is_recorded_as_the_revision_it_matches(
assert resource.key == "buddy"
assert (
resource.fingerprints
- == released_agent_fingerprints("switch-buddy")[0][1]["buddy"]
+ == revisions.entry_for(_OFFICIAL / "switch-buddy")["agents"]["buddy"]
)
assert await _updates(harness).record_existing_buddies(TENANT_ZERO_ID) == 0
diff --git a/core/tests/switch_core/test_official_templates.py b/core/tests/switch_core/test_official_templates.py
index f0dedfb59..c604bcbc2 100644
--- a/core/tests/switch_core/test_official_templates.py
+++ b/core/tests/switch_core/test_official_templates.py
@@ -3,6 +3,7 @@ package, the document chosen by the agent_management flag, never changed."""
from __future__ import annotations
+import shutil
from pathlib import Path
import yaml
@@ -136,15 +137,30 @@ def test_an_unknown_official_id_is_none():
)
-def test_every_template_s_last_revision_is_what_its_files_serve():
- """A change to an official template is a new revision: agents created
- from an older one are brought up to it, and only a new revision tells
- them there is something to bring."""
+def test_a_release_records_a_revision_for_each_template_that_changed(
+ tmp_path, monkeypatch
+):
+ """At release time, `record-all` adds a revision for each template whose
+ files changed since its last one, after the ones already there, and
+ leaves the others alone."""
for shipped in _SHIPPED:
- assert not revisions.stale(shipped.slug), (
- f"{shipped.slug} changed since its last revision. Record one: "
- f"python -m switch_core.official_templates.revisions record {shipped.slug}"
- )
+ shutil.copytree(_PACKAGED / shipped.slug, tmp_path / shipped.slug)
+ monkeypatch.setattr(revisions, "_HERE", tmp_path)
+ revisions.record_all()
+ before = {s.slug: revisions.recorded(s.slug) for s in _SHIPPED}
+ assert not any(revisions.stale(s.slug) for s in _SHIPPED)
+
+ with (tmp_path / "switch-buddy" / "AGENT.md").open("a") as agent_md:
+ agent_md.write("\nOne more thing.\n")
+
+ assert revisions.stale("switch-buddy")
+ assert not revisions.stale("switch-expert")
+ assert revisions.record_all() == {"switch-buddy": len(before["switch-buddy"]) + 1}
+ after = revisions.recorded("switch-buddy")
+ assert after[:-1] == before["switch-buddy"]
+ assert after[-1]["agents"] != before["switch-buddy"][-1]["agents"]
+ assert revisions.recorded("switch-expert") == before["switch-expert"]
+ assert revisions.record_all() == {}
def test_a_template_is_served_at_its_last_revision():
diff --git a/docs/TEMPLATES.md b/docs/TEMPLATES.md
index e56311456..4516e12d8 100644
--- a/docs/TEMPLATES.md
+++ b/docs/TEMPLATES.md
@@ -716,9 +716,11 @@ counts it in telemetry by operation and reason.
A template's **revision** is its own edit count, not the language version
(`version: 2`): a saved template's goes up each time its document is
replaced, and an official template's is the last entry in its
-`revisions.json`, beside its files. Changing an official template means
-adding a revision (`python -m switch_core.official_templates.revisions record
-<slug>`); a test fails while its files and its last revision disagree.
+`revisions.json`, beside its files. Revisions are recorded when Switch is
+released, with the other versions (`just record-template-revisions`, see
+RELEASING.md), not by whoever changes a template: between releases a changed
+template is served under its last revision, and the release workflow refuses
+a release tag while a change is unrecorded.
When the server runs a template whose source it can vouch for, it records
the run as an **install**: the template's id and revision, the inputs it was
diff --git a/justfile b/justfile
index 499d5531b..85963459e 100644
--- a/justfile
+++ b/justfile
@@ -130,6 +130,13 @@ artifacts:
artifacts-check:
uv run --project core python scripts/gen_artifacts.py --check
+# ── Record the official templates' revisions, at release time ─────────────────
+# Adds a revision to revisions.json for each official template (switch-buddy,
+# the Switch expert) whose files changed since its last one; commit it with the
+# version bump. The release workflow refuses a release tag while any changed.
+record-template-revisions:
+ uv run --project core python -m switch_core.official_templates.revisions record-all
+
# ── Build the Teams app package an operator uploads ───────────────────────────
# Every route into a tenant wants a .zip — Developer Portal Import app, Upload a
# custom app, the admin centre — and none takes a bare manifest.json. Pass the