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
Record official template revisions at release time
Simon Flack915c547bf891
diff --git a/.github/workflows/switch-release.yml b/.github/workflows/switch-release.ymlindex 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.mdindex 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 release1. **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):```bashdiff --git a/core/switch_core/official_templates/__init__.py b/core/switch_core/official_templates/__init__.pyindex 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, numberedfrom 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 agentscreated 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 annotationsdiff --git a/core/switch_core/official_templates/revisions.py b/core/switch_core/official_templates/revisions.pyindex 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 everyrevision, so an old buddy nobody changed is recognised as the revision itcame 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 0if 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 2diff --git a/core/tests/switch_core/management/test_agent_operations.py b/core/tests/switch_core/management/test_agent_operations.pyindex 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 annotationsimport hashlibimport secretsfrom collections.abc import AsyncIterator, Iterator+from pathlib import Pathfrom typing import Anyimport httpx@@ -20,6 +21,7 @@ import pytestfrom sqlalchemy import select, updatefrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+import switch_core.official_templates as official_templates_packagefrom switch_core.addressing import default_agent_policy, parse_policyfrom switch_core.bridges.agent.mcp.server import mcpfrom 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.pyindex 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 annotationsimport asynciofrom collections.abc import AsyncIterator, Iteratorfrom dataclasses import replace+from pathlib import Pathfrom typing import Anyimport httpx@@ -15,6 +16,7 @@ import pytestfrom sqlalchemy import func, select, updatefrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+import switch_core.official_templates as official_templates_packagefrom switch_core.bridges.agent.operations import context as op_contextfrom switch_core.bridges.agent.operations import template_statusfrom switch_core.bridges.agent.operations.callctx import (@@ -33,11 +35,13 @@ from switch_core.db.stores.agent_definition_store import DefinitionChangedfrom switch_core.db.stores.template_install_store import TemplateInstallStorefrom switch_core.gateway import dependencies as gw_depsfrom switch_core.gateway.rooms import router as rooms_router+from switch_core.management import template_updates as template_updates_modulefrom switch_core.management.template_updates import BUDDY_ID, TemplateUpdatesfrom 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) == 0diff --git a/core/tests/switch_core/test_official_templates.py b/core/tests/switch_core/test_official_templates.pyindex 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 shutilfrom pathlib import Pathimport 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.mdindex 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 isreplaced, 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 recordsthe run as an **install**: the template's id and revision, the inputs it wasdiff --git a/justfile b/justfileindex 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