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
feat(artifacts): register everything Switch publishes, not just what it versions (CHOO-1865)
Louis Amaudruzae8ca6bd65bb
diff --git a/RELEASING.md b/RELEASING.mdindex 936b8b53a..55b0fad64 100644--- a/RELEASING.md+++ b/RELEASING.md@@ -22,19 +22,35 @@ 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 **operator dashboard** (`gateway/`), the **setup image**, 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 appear in+`artifacts.yaml` with `version_from: switch-core` — listed, because a registry+claiming to be the single source of truth cannot be silent about things we+publish, and `version_from` states "no version of its own" as data rather than+leaving it to be inferred from an absence.++Do not give any of them a version of their own 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, theagent-runtime package, the sidecar, and the two connector plugins.+### A known gap: the Helm chart has no contract++`values.yaml` is a real consumer-facing interface — operators write a values+file against its keys and pin the chart version — so a breaking change there is+as disruptive as renaming a compose service. It carries no contract anyway,+because a contract needs two sides that declare and nothing first-party consumes+the chart; the other side is a human-maintained values file.++A one-sided contract is a revision nobody compares, so this is left as a+documented gap rather than covered by a number that would only look like+coverage. Until it is closed, **treat a values-schema change as a breaking+change and say so in the changelog** — nothing will catch it for you.+### Bumping a contractWhen you change an interface named in `artifacts.yaml`, raise that artifact'sdiff --git a/artifacts.yaml b/artifacts.yamlindex b49b79c5c..0bf2389d6 100644--- a/artifacts.yaml+++ b/artifacts.yaml@@ -29,6 +29,21 @@# An artifact with no `declared_in` has no such home — nothing but this file# declares it, so this file is its source and the constant is generated.#+# ── About `version_from` ─────────────────────────────────────────────────────+#+# Some things Switch publishes have no version of their own: they ship inside+# another artifact's release and are stamped with its version at package time,+# which is what lets a single tag pin the whole stack. `version_from` names the+# artifact they inherit from.+#+# They are listed here rather than left out, because a registry that claims to+# be the single source of truth cannot be silent about things we publish. And+# `version_from` states the fact — "this has no version of its own" — as data+# rather than leaving it to be inferred from an absence. Nothing duplicates a+# number, so nothing can drift.+#+# Exactly one of `version` or `version_from` per artifact.+## ── Contract revisions ───────────────────────────────────────────────────────## speaks — the newest revision the artifact implements@@ -47,6 +62,7 @@ artifacts:description: The backend service, and the gateway API it serves.version: 0.12.3declared_in: core/pyproject.toml+ published_as: switch-coreswitchdash:description: The desktop app.@@ -76,6 +92,39 @@ artifacts:only source and the constant is generated from it.version: 1.8.0+ # ── Published under the switch-core release ────────────────────────────────+ # No version of their own: `helm package` and the image build stamp them with+ # the switch-core release version, so one tag pins the whole stack.++ gateway:+ description: The operator dashboard image.+ version_from: switch-core+ published_as: gateway++ setup:+ description: The collaboration-bridge seeder image.+ version_from: switch-core+ published_as: setup++ helm-chart:+ description: >-+ The Kubernetes chart. Its values.yaml is a consumer-facing interface —+ operators write a values file against those keys and pin the chart+ version — but nothing first-party consumes it, so there is no second side+ to declare a contract against. A breaking values change is therefore+ invisible to this model today; that gap is deliberate and belongs with+ the rest of Part 2, not papered over with a revision nobody compares.+ version_from: switch-core+ published_as: charts/switch++ compose:+ description: >-+ The standalone compose file, published as an OCI artifact. Unlike the+ chart this one has a real peer — switchdash's local-server mode drives it+ — so it does carry a contract, below.+ version_from: switch-core+ published_as: standalone-compose+switch-connector:description: The Claude Code connector plugin.version: 0.7.8diff --git a/core/switch_core/artifacts.py b/core/switch_core/artifacts.pyindex 07d5446ef..16ddad7a1 100644--- a/core/switch_core/artifacts.py+++ b/core/switch_core/artifacts.py@@ -24,6 +24,10 @@ ARTIFACT_VERSIONS: Final[dict[str, str]] = {"switchdash": "0.19.2","agent-runtime": "0.1.5","sidecar": "1.8.0",+ "gateway": "0.12.3",+ "setup": "0.12.3",+ "helm-chart": "0.12.3",+ "compose": "0.12.3","switch-connector": "0.7.8","switch-connector-codex": "0.2.0",}diff --git a/core/tests/test_gen_artifacts.py b/core/tests/test_gen_artifacts.pyindex 98cfd4a5c..ee6aad754 100644--- a/core/tests/test_gen_artifacts.py+++ b/core/tests/test_gen_artifacts.py@@ -107,6 +107,23 @@ def test_the_switchdash_pin_is_not_wired_to_switch_cores_version() -> None:assert "switch-core" in switchdash.pins+def test_every_contract_peer_is_an_artifact_the_registry_knows() -> None:+ """The two halves must agree about what an artifact is.++ `compose` was a peer on stack-compose while the artifacts section had never+ heard of it, so the same name resolved in one half and threw in the other.+ """+ named_in_contracts = {peer for peers in CONTRACTS.values() for peer in peers}+ assert named_in_contracts <= set(ARTIFACT_VERSIONS)+++def test_everything_published_under_the_switch_core_tag_shares_its_version() -> None:+ """One tag pins the whole stack, so these are stamped rather than declared."""+ core = ARTIFACT_VERSIONS["switch-core"]+ for stamped in ("gateway", "setup", "helm-chart", "compose"):+ assert ARTIFACT_VERSIONS[stamped] == core++def test_the_sidecar_has_no_declared_in_so_the_registry_owns_it() -> None:"""Nothing else declares the sidecar's version — it is deployed, not published."""registry = gen.load_registry()@@ -171,6 +188,94 @@ def test_registry_rejects_a_two_part_version(gen.load_registry()+def test_registry_rejects_both_version_and_version_from(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """An artifact either has its own version or inherits one. Never both."""+ _write_registry(+ tmp_path,+ monkeypatch,+ artifacts={+ "base": {"description": "d", "version": "1.0.0"},+ "demo": {"description": "d", "version": "2.0.0", "version_from": "base"},+ },+ contracts={+ "demo-contract": {+ "description": "d",+ "artifacts": {"demo": {"speaks": 1, "accepts": 1}},+ }+ },+ )+ with pytest.raises(ValueError, match="exactly one of"):+ gen.load_registry()+++def test_registry_rejects_neither_version_nor_version_from(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ _write_registry(tmp_path, monkeypatch, artifacts={"demo": {"description": "d"}})+ with pytest.raises(ValueError, match="exactly one of"):+ gen.load_registry()+++def test_an_inherited_version_resolves_to_its_source(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ _write_registry(+ tmp_path,+ monkeypatch,+ artifacts={+ "base": {"description": "d", "version": "3.4.5"},+ "derived": {"description": "d", "version_from": "base"},+ },+ contracts={+ "demo-contract": {+ "description": "d",+ "artifacts": {"derived": {"speaks": 1, "accepts": 1}},+ }+ },+ )+ registry = gen.load_registry()+ derived = next(a for a in registry.artifacts if a.name == "derived")+ assert derived.version == "3.4.5"+++def test_registry_rejects_inheriting_from_something_unknown(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ _write_registry(+ tmp_path,+ monkeypatch,+ artifacts={"demo": {"description": "d", "version_from": "nowhere"}},+ contracts={+ "demo-contract": {+ "description": "d",+ "artifacts": {"demo": {"speaks": 1, "accepts": 1}},+ }+ },+ )+ with pytest.raises(ValueError, match="not an artifact in this registry"):+ gen.load_registry()+++def test_registry_rejects_a_contract_peer_it_does_not_know(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """The check that would have caught `compose` being in one half only."""+ _write_registry(+ tmp_path,+ monkeypatch,+ contracts={+ "demo-contract": {+ "description": "d",+ "artifacts": {"a-stranger": {"speaks": 1, "accepts": 1}},+ }+ },+ )+ with pytest.raises(ValueError, match="not in the artifacts section"):+ gen.load_registry()++def test_registry_rejects_a_pin_of_something_it_does_not_know(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:diff --git a/dash/packages/shared/src/artifacts.ts b/dash/packages/shared/src/artifacts.tsindex db6108372..9d8d683f8 100644--- a/dash/packages/shared/src/artifacts.ts+++ b/dash/packages/shared/src/artifacts.ts@@ -24,6 +24,10 @@ export const ARTIFACT_VERSIONS = {switchdash: '0.19.2','agent-runtime': '0.1.5',sidecar: '1.8.0',+ gateway: '0.12.3',+ setup: '0.12.3',+ 'helm-chart': '0.12.3',+ compose: '0.12.3','switch-connector': '0.7.8','switch-connector-codex': '0.2.0',} as const satisfies Record<string, string>;diff --git a/dash/packages/switch-agent-runtime/src/artifacts.ts b/dash/packages/switch-agent-runtime/src/artifacts.tsindex db6108372..9d8d683f8 100644--- a/dash/packages/switch-agent-runtime/src/artifacts.ts+++ b/dash/packages/switch-agent-runtime/src/artifacts.ts@@ -24,6 +24,10 @@ export const ARTIFACT_VERSIONS = {switchdash: '0.19.2','agent-runtime': '0.1.5',sidecar: '1.8.0',+ gateway: '0.12.3',+ setup: '0.12.3',+ 'helm-chart': '0.12.3',+ compose: '0.12.3','switch-connector': '0.7.8','switch-connector-codex': '0.2.0',} as const satisfies Record<string, string>;diff --git a/scripts/gen_artifacts.py b/scripts/gen_artifacts.pyindex 3a6065d40..2f4486ad4 100644--- a/scripts/gen_artifacts.py+++ b/scripts/gen_artifacts.py@@ -37,7 +37,7 @@ import jsonimport reimport sysimport tomllib-from dataclasses import dataclass+from dataclasses import dataclass, replacefrom pathlib import Pathfrom typing import Any@@ -65,8 +65,14 @@ class Target:class Artifact:name: strdescription: str+ #: Resolved: an artifact with `version_from` carries its source's version.version: str+ #: Where a packaging ecosystem states this version, when one owns it.declared_in: str | None+ #: The artifact this one inherits its version from, if it has none of its own.+ version_from: str | None+ #: Where it lands on the registry, for anything we publish.+ published_as: str | Nonepins: dict[str, str]@@ -101,6 +107,7 @@ def load_registry() -> Registry:raise ValueError(f"{SOURCE} must have a top-level {section!r} mapping")artifacts = [_parse_artifact(name, body) for name, body in raw["artifacts"].items()]+ artifacts = _resolve_inherited_versions(artifacts)known = {artifact.name for artifact in artifacts}for artifact in artifacts:for pinned in artifact.pins:@@ -111,9 +118,52 @@ def load_registry() -> Registry:)contracts = [_parse_contract(name, body) for name, body in raw["contracts"].items()]++ # Every artifact a contract names must exist in the artifacts section.+ # Without this the two halves can disagree about what an artifact even is:+ # `compose` was a peer on stack-compose while the artifacts section had+ # never heard of it, so one name resolved in one half and threw in the+ # other (CHOO-1865).+ for contract in contracts:+ for participant in contract.artifacts:+ if participant not in known:+ raise ValueError(+ f"contract {contract.name!r} names artifact {participant!r}, "+ "which is not in the artifacts section — every peer must be "+ "an artifact this registry knows"+ )+return Registry(artifacts=artifacts, contracts=contracts)+def _resolve_inherited_versions(artifacts: list[Artifact]) -> list[Artifact]:+ """Give every `version_from` artifact the version it inherits.++ One hop only. A chain would mean an artifact inheriting from something that+ itself has no version of its own, which is a modelling mistake rather than+ a case worth supporting.+ """+ by_name = {artifact.name: artifact for artifact in artifacts}+ resolved: list[Artifact] = []+ for artifact in artifacts:+ if artifact.version_from is None:+ resolved.append(artifact)+ continue+ source = by_name.get(artifact.version_from)+ if source is None:+ raise ValueError(+ f"artifact {artifact.name!r} takes its version from "+ f"{artifact.version_from!r}, which is not an artifact in this registry"+ )+ if source.version_from is not None:+ raise ValueError(+ f"artifact {artifact.name!r} takes its version from "+ f"{artifact.version_from!r}, which has no version of its own"+ )+ resolved.append(replace(artifact, version=source.version))+ return resolved++def _parse_artifact(name: str, body: object) -> Artifact:if not isinstance(body, dict):raise ValueError(f"artifact {name!r}: expected a mapping")@@ -122,7 +172,23 @@ def _parse_artifact(name: str, body: object) -> Artifact:raise ValueError(f"artifact {name!r}: a description is required")version = body.get("version")- if not isinstance(version, str) or not SEMVER.fullmatch(version):+ version_from = body.get("version_from")+ if (version is None) == (version_from is None):+ raise ValueError(+ f"artifact {name!r}: set exactly one of 'version' (it has its own) "+ "or 'version_from' (it is stamped from another artifact's release)"+ )+ if version_from is not None:+ if not isinstance(version_from, str):+ raise ValueError(f"artifact {name!r}: version_from must be a name")+ if body.get("declared_in") is not None:+ raise ValueError(+ f"artifact {name!r}: declared_in makes no sense with version_from — "+ "nothing declares a version it does not have"+ )+ # Filled in once the source is known.+ version = "0.0.0"+ elif not isinstance(version, str) or not SEMVER.fullmatch(version):raise ValueError(f"artifact {name!r}: version must be three-part semver, got {version!r}")@@ -131,6 +197,10 @@ def _parse_artifact(name: str, body: object) -> Artifact:if declared_in is not None and not isinstance(declared_in, str):raise ValueError(f"artifact {name!r}: declared_in must be a path")+ published_as = body.get("published_as")+ if published_as is not None and not isinstance(published_as, str):+ raise ValueError(f"artifact {name!r}: published_as must be a string")+pins_raw = body.get("pins") or {}if not isinstance(pins_raw, dict):raise ValueError(f"artifact {name!r}: pins must be a mapping")@@ -148,6 +218,8 @@ def _parse_artifact(name: str, body: object) -> Artifact:description=_squash(description),version=version,declared_in=declared_in,+ version_from=version_from,+ published_as=published_as,pins=pins,)