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
Bring agents made from an official template up to its new revision at startup
Simon Flacke32466650db7
diff --git a/core/switch_core/bridges/agent/protocol/agent_core.py b/core/switch_core/bridges/agent/protocol/agent_core.pyindex 640d56286..de3b97c38 100644--- a/core/switch_core/bridges/agent/protocol/agent_core.py+++ b/core/switch_core/bridges/agent/protocol/agent_core.py@@ -886,6 +886,12 @@ class AgentCore:) -> None:self._agent_profile_listener = listener+ async def agent_profile_changed(self, agent_id: str) -> None:+ """Tell whoever follows agents' faces that this one's icon or+ display name changed, after a change made outside+ `update_agent_detail`."""+ await self._agent_profile_changed(agent_id)+async def _agent_profile_changed(self, agent_id: str) -> None:if self._agent_profile_listener is not None:await self._agent_profile_listener(require_tenant_id(), agent_id)diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.pyindex 08be6d324..47ecb9852 100644--- a/core/switch_core/db/models.py+++ b/core/switch_core/db/models.py@@ -1451,6 +1451,10 @@ class TemplateInstallResource(TenantScoped, Base):agent_id: Mapped[str | None] = mapped_column(Text, nullable=True)room_id: Mapped[str | None] = mapped_column(Text, nullable=True)fingerprints: Mapped[dict] = mapped_column(JSONB, nullable=False)+ # What Switch has to tell the agent about its template, until it reads+ # how it differs from it (``get_template_status``): a newer revision it+ # was not brought fully up to. Null when there is nothing to tell.+ notice: Mapped[str | None] = mapped_column(Text, nullable=True)# ── Packages ──────────────────────────────────────────────────────────────────diff --git a/core/switch_core/db/stores/agent_definition_store.py b/core/switch_core/db/stores/agent_definition_store.pyindex c8c5d97b3..cabac2a77 100644--- a/core/switch_core/db/stores/agent_definition_store.py+++ b/core/switch_core/db/stores/agent_definition_store.py@@ -8,6 +8,10 @@ from sqlalchemy.ext.asyncio import AsyncSessionfrom switch_core.db.models import Agent, AgentDefinition+class DefinitionChanged(Exception):+ """A definition changed between being read and being written."""++class AgentDefinitionStore:"""Managed agent definitions, one per agent.@@ -106,14 +110,20 @@ class AgentDefinitionStore:controller_id: str | None,desired_state: str,definition: dict[str, Any],+ expected_revision: int | None,) -> AgentDefinition:- """Replace the placement, desired state and definition, bumping the revision."""+ """Replace the placement, desired state and definition, bumping the+ revision. With `expected_revision`, only while the definition is still+ at it: `DefinitionChanged` when something changed it since it was read."""+ conditions = [+ AgentDefinition.tenant_id == tenant_id,+ AgentDefinition.agent_id == agent_id,+ ]+ if expected_revision is not None:+ conditions.append(AgentDefinition.revision == expected_revision)result = await session.execute(update(AgentDefinition)- .where(- AgentDefinition.tenant_id == tenant_id,- AgentDefinition.agent_id == agent_id,- )+ .where(*conditions).values(controller_id=controller_id,desired_state=desired_state,@@ -124,6 +134,11 @@ class AgentDefinitionStore:.execution_options(synchronize_session=False, populate_existing=True))row = result.scalar_one_or_none()+ if row is None and expected_revision is not None:+ raise DefinitionChanged(+ f"The definition of agent {agent_id} changed since revision "+ f"{expected_revision} was read"+ )if row is None:raise LookupError(f"No definition for agent: {agent_id}")return rowdiff --git a/core/switch_core/db/stores/template_install_store.py b/core/switch_core/db/stores/template_install_store.pyindex 02f923673..78ba994d7 100644--- a/core/switch_core/db/stores/template_install_store.py+++ b/core/switch_core/db/stores/template_install_store.py@@ -156,3 +156,28 @@ class TemplateInstallStore:.values(revision=to))return bool(result.rowcount) # type: ignore[attr-defined]++ async def set_notice(+ self, session: AsyncSession, resource_id: str, notice: str | None+ ) -> None:+ await session.execute(+ update(TemplateInstallResource)+ .where(+ TemplateInstallResource.tenant_id == require_tenant_id(),+ TemplateInstallResource.id == resource_id,+ )+ .values(notice=notice)+ )++ async def notice_for_agent(+ self, session: AsyncSession, agent_id: str+ ) -> str | None:+ """What Switch has to tell an agent about its template, if anything."""+ return (+ await session.execute(+ select(TemplateInstallResource.notice).where(+ TemplateInstallResource.tenant_id == require_tenant_id(),+ TemplateInstallResource.agent_id == agent_id,+ )+ )+ ).scalar_one_or_none()diff --git a/core/switch_core/main.py b/core/switch_core/main.pyindex 787571c8b..7fc134c76 100644--- a/core/switch_core/main.py+++ b/core/switch_core/main.py@@ -178,11 +178,13 @@ from switch_core.db.tenant_lookup import all_tenant_idsfrom switch_core.delivery.conversation import ConversationRules, ConversationSettingsfrom switch_core.delivery.recipient import RecipientServicesfrom switch_core.delivery.router import GROUP_SWEEP_SECONDS, MessageRouter+from switch_core.feature_flags import AGENT_MANAGEMENT, SWITCH_BUDDYfrom switch_core.gateway.app import create_gateway_appfrom switch_core.gateway.auth import hash_passwordfrom switch_core.gateway.invite_mail import SmtpInviteMailerfrom switch_core.gateway.ui import GatewayUifrom switch_core.logging_config import configure_logging+from switch_core.management.template_updates import TemplateUpdatesfrom switch_core.management.wiring import Management, create_managementfrom switch_core.messages.notify import MessageListenerfrom switch_core.observability.bootstrap import (@@ -1416,6 +1418,22 @@ async def run(config: SwitchConfig, process_id: str) -> None:if management is not Noneelse None)+ # Once per start, in the background: a new release may bring a+ # new revision of an official template, and the agents an older+ # one created are brought up to it (`template_updates`).+ template_updates_task = (+ asyncio.create_task(+ TemplateUpdates(+ session_factory=session_factory,+ management=management.service,+ protocol=protocol,+ agent_management=config.feature_flags[AGENT_MANAGEMENT],+ switch_buddy=config.feature_flags[SWITCH_BUDDY],+ ).run(tenant_ids)+ )+ if management is not None+ else None+ )# Only when telemetry is on: the chart tells a customer that off# means nothing is collected, and the fan-out is not free.snapshot_task = (@@ -1442,6 +1460,8 @@ async def run(config: SwitchConfig, process_id: str) -> None:shared_connections_task.cancel()if management_task is not None:management_task.cancel()+ if template_updates_task is not None:+ template_updates_task.cancel()ownership_task.cancel()# The lease goes on being renewed while the owned work is# handed over, which can take a few seconds: it must not lapsediff --git a/core/switch_core/management/agent_operations.py b/core/switch_core/management/agent_operations.pyindex 9fdbac904..b16a660e5 100644--- a/core/switch_core/management/agent_operations.py+++ b/core/switch_core/management/agent_operations.py@@ -447,6 +447,7 @@ class ManagementAgentOperations:controller_id=request.controller_id,controller_id_given="controller_id" in request.model_fields_set,protocol=protocol,+ expected_revision=None,)except ManagementError as exc:machine = controller.name if controller is not None else "(none)"diff --git a/core/switch_core/management/gateway_routes.py b/core/switch_core/management/gateway_routes.pyindex 1e0af4e6d..dbcaeefea 100644--- a/core/switch_core/management/gateway_routes.py+++ b/core/switch_core/management/gateway_routes.py@@ -253,6 +253,7 @@ async def patch_managed_agent(controller_id=body.controller_id,controller_id_given="controller_id" in body.model_fields_set,protocol=protocol,+ expected_revision=None,)await _revoke_controller_tokens(session, broker, ServiceTokenIssuance.agent_id == agent_iddiff --git a/core/switch_core/management/service.py b/core/switch_core/management/service.pyindex 06ed6fbda..34bde61f8 100644--- a/core/switch_core/management/service.py+++ b/core/switch_core/management/service.py@@ -962,6 +962,7 @@ class ManagementService:controller_id=target,desired_state=row.desired_state,definition=row.definition,+ expected_revision=None,))return moved@@ -1364,7 +1365,14 @@ class ManagementService:agent = await self._owned_agent(session, owner_id, agent_id)existing = await self.definitions.get_for_agent(session, tenant_id, agent_id)return await self._apply(- session, tenant_id, owner_id, agent, existing, target, protocol+ session,+ tenant_id,+ owner_id,+ agent,+ existing,+ target,+ protocol,+ expected_revision=None,)async def patch_managed_agent(@@ -1379,6 +1387,7 @@ class ManagementService:controller_id: str | None,controller_id_given: bool,protocol: AgentCore,+ expected_revision: int | None,) -> dict[str, Any]:existing, agent = await self._owned_definition(session, tenant_id, owner_id, agent_id@@ -1395,7 +1404,14 @@ class ManagementService:),)return await self._apply(- session, tenant_id, owner_id, agent, existing, target, protocol+ session,+ tenant_id,+ owner_id,+ agent,+ existing,+ target,+ protocol,+ expected_revision=expected_revision,)async def _apply(@@ -1407,7 +1423,11 @@ class ManagementService:existing: AgentDefinitionRow | None,target: _Placement,protocol: AgentCore,+ expected_revision: int | None,) -> dict[str, Any]:+ """Write `target` over `existing`. With `expected_revision`, only+ while the definition is still at that revision (`DefinitionChanged`+ otherwise), for a change worked out from what it was."""definition = DefinitionV1.model_validate(target.definition)moved = existing is None or existing.controller_id != target.controller_idto_running = target.desired_state == "running" and (@@ -1482,6 +1502,7 @@ class ManagementService:controller_id=target.controller_id,desired_state=target.desired_state,definition=target.definition,+ expected_revision=expected_revision,)affected = {previous_controller_id, target.controller_id}if previous_controller_id is not None and moved:@@ -1550,6 +1571,7 @@ class ManagementService:controller_id=row.controller_id,desired_state=row.desired_state,definition=definition,+ expected_revision=None,)revisions = await self._bump_and_collect(session, tenant_id, {row.controller_id}diff --git a/core/switch_core/management/template_updates.py b/core/switch_core/management/template_updates.pynew file mode 100644index 000000000..e615c0c0a--- /dev/null+++ b/core/switch_core/management/template_updates.py@@ -0,0 +1,480 @@+"""Bringing the agents an official template created up to its current+revision, when the server starts.++A new release can ship a new revision of an official template (see+``official_templates/revisions.py``). Every agent an older revision created+(its install, ``db.models.TemplateInstall``) is then brought up to it:++- A value the template set that nobody has changed since (its fingerprint+ still matches) takes the new revision's value.+- A value somebody changed is theirs, and is left as it is.+- Who may address the agent and whether it can manage agents are never+ changed, whichever way the new revision would move them.++When anything was left as it is, the agent is left a notice (see+``template_status``): it is told, before the next message it receives, to+read how it differs from its template and tell its owner, who decides.++Every write is conditional on what was read, so servers starting together+each update an agent once at most: the one that loses a race leaves the+agent to the one that won, and the install's revision moves only once.++The agents switch-buddy created before installs were recorded are recorded+first (``record_existing_buddies``), matched against the fingerprints of+every revision of it released.+"""++from __future__ import annotations++import logging+import re+from collections.abc import Sequence+from dataclasses import dataclass+from typing import TYPE_CHECKING, Any++from sqlalchemy import select, update+from sqlalchemy.exc import IntegrityError+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.agent.protocol.agent_detail import addressing_policy_for+from switch_core.db.models import (+ Agent,+ AgentDefinition,+ TemplateInstall,+ TemplateInstallResource,+)+from switch_core.db.session_scope import tenant_session+from switch_core.db.stores.agent_definition_store import DefinitionChanged+from switch_core.db.stores.template_install_store import (+ NewInstallResource,+ TemplateInstallStore,+)+from switch_core.management.schemas import DefinitionV1, stored_definition+from switch_core.official_templates import (+ OFFICIAL_PREFIX,+ OfficialTemplate,+ official_template,+ official_templates,+ released_agent_fingerprints,+ slug_of,+)+from switch_core.template_installs import (+ AGENT_FIELDS,+ fingerprint,+ render_plans,+)+from switch_core.template_runs import TEMPLATE_ADDRESSING, NewAgentPlan++if TYPE_CHECKING:+ from switch_core.bridges.agent.protocol.agent_core import AgentCore+ from switch_core.management.service import ManagementService++logger = logging.getLogger(__name__)++BUDDY_ID = f"{OFFICIAL_PREFIX}switch-buddy"+BUDDY_KEY = "buddy"+_BUDDY_NAME = re.compile(r"^switch-buddy(-[a-z0-9._-]+)?$")+++@dataclass(frozen=True)+class Held:+ """A permission the template's current revision sets differently from+ the agent's own, which no update changes."""++ setting: str+ yours: Any+ recommended: Any+++@dataclass(frozen=True)+class Differs:+ """A value somebody changed from what the template set, with what the+ template's current revision would set instead."""++ field: str+ yours: str | None+ recommended: str | None+++class LostRace(Exception):+ """Something changed the agent between it being read and written."""+++def agent_values(agent: Agent, row: AgentDefinition | None) -> dict[str, str | None]:+ """An agent's own values of the fields a template sets; no+ ``instructions`` for an agent with no managed definition."""+ values: dict[str, str | None] = {+ "description": agent.description,+ "icon_url": agent.icon_url,+ "display_name": agent.display_name,+ }+ if row is not None:+ values["instructions"] = str(row.definition.get("instructions") or "")+ return values+++def plan_values(plan: NewAgentPlan) -> dict[str, str | None]:+ return {+ "instructions": plan.instructions,+ "description": plan.description,+ "icon_url": plan.icon_url,+ "display_name": plan.display_name,+ }+++def held_permissions(plan: NewAgentPlan, agent: Agent) -> list[Held]:+ """The permissions `plan` sets that differ from the agent's own."""+ held: list[Held] = []+ if plan.can_manage_agents != agent.can_manage_agents:+ held.append(+ Held("can_manage_agents", agent.can_manage_agents, plan.can_manage_agents)+ )+ choice = TEMPLATE_ADDRESSING.get(plan.addressing)+ if choice is not None and addressing_policy_for(choice) != agent.addressing_policy:+ held.append(Held("addressing", _addressing_word(agent), choice))+ return held+++def _addressing_word(agent: Agent) -> str:+ for choice in TEMPLATE_ADDRESSING.values():+ if addressing_policy_for(choice) == agent.addressing_policy:+ return choice+ return "custom"+++def notice_text(+ template: OfficialTemplate,+ updated: Sequence[str],+ differs: Sequence[str],+ held: Sequence[Held],+) -> str:+ """What the agent is told when it was not brought fully up to a new+ revision of its template."""+ parts = [+ f"Your template, {template.name}, has a new revision ({template.version})."+ ]+ if updated:+ parts.append(f"Switch updated your {', '.join(updated)} to it.")+ if differs:+ parts.append(+ f"Your {', '.join(differs)} had been changed from the template, so "+ "they were left as they are."+ )+ if held:+ parts.append(+ "It also sets "+ + ", ".join(h.setting for h in held)+ + " differently, which Switch never changes for you."+ )+ parts.append(+ "Call get_template_status to see what differs, then tell your owner "+ "what they would gain and what they would lose by taking the new "+ "version. They decide, and make any change themselves."+ )+ return " ".join(parts)+++class TemplateUpdates:+ def __init__(+ self,+ *,+ session_factory: async_sessionmaker[AsyncSession],+ management: ManagementService,+ protocol: AgentCore,+ agent_management: bool,+ switch_buddy: bool,+ ) -> None:+ self._session_factory = session_factory+ self._management = management+ self._protocol = protocol+ self._agent_management = agent_management+ self._switch_buddy = switch_buddy+ self._store = TemplateInstallStore()++ async def run(self, tenant_ids: Sequence[str]) -> None:+ """Record old buddies and update every install, tenant by tenant. One+ tenant's failure is logged and the next is still updated."""+ for tenant_id in tenant_ids:+ try:+ await self.record_existing_buddies(tenant_id)+ for template in official_templates(+ self._agent_management, self._switch_buddy+ ):+ await self.update_installs(tenant_id, template)+ except Exception:+ logger.error(+ "Could not update the agents of official templates in tenant %s",+ tenant_id,+ exc_info=True,+ )++ # ── Buddies created before installs were recorded ───────────────────────++ async def record_existing_buddies(self, tenant_id: str) -> int:+ """Record each managed agent that is relatively surely someone's+ switch-buddy, with no install yet, as an install of the revision it+ matches best. Returns how many it recorded.++ Relatively surely: named as buddies are (``switch-buddy`` or+ ``switch-buddy-…``), and still carrying the buddy's icon or+ description from some revision. A name alone is anyone's to take.+ """+ buddy = official_template(BUDDY_ID, self._agent_management, self._switch_buddy)+ if buddy is None:+ return 0+ released = [+ (revision, agents[BUDDY_KEY])+ for revision, agents in released_agent_fingerprints(slug_of(BUDDY_ID))+ if BUDDY_KEY in agents+ ]+ icons = {fps["icon_url"] for _, fps in released}+ descriptions = {fps["description"] for _, fps in released}+ async with tenant_session(self._session_factory, tenant_id) as session:+ candidates = await self._unrecorded_buddies(session, tenant_id)+ recorded = 0+ for agent, row in candidates:+ mine = {+ name: fingerprint(value)+ for name, value in agent_values(agent, row).items()+ }+ if (+ mine["icon_url"] not in icons+ and mine["description"] not in descriptions+ ):+ continue+ # The newest revision it matches most fields of; a buddy whose+ # instructions match none is recorded too, as one somebody changed.+ revision, fps = max(+ released,+ key=lambda entry: (+ sum(mine.get(k) == v for k, v in entry[1].items()),+ entry[0],+ ),+ )+ try:+ async with tenant_session(self._session_factory, tenant_id) as session:+ await self._store.create(+ session,+ owner_id=str(agent.owner_id),+ source="official",+ template_id=BUDDY_ID,+ template_name=buddy.name,+ revision=revision,+ inputs={"agent_name": agent.name},+ builtins={},+ resources=[+ NewInstallResource(+ key=BUDDY_KEY,+ agent_id=agent.id,+ room_id=None,+ fingerprints=dict(fps),+ )+ ],+ )+ await session.commit()+ except IntegrityError:+ # Another server recorded it first.+ continue+ recorded += 1+ logger.info(+ "Recorded agent %s as switch-buddy revision %s", agent.name, revision+ )+ return recorded++ async def _unrecorded_buddies(+ self, session: AsyncSession, tenant_id: str+ ) -> list[tuple[Agent, AgentDefinition]]:+ rows = await session.execute(+ select(Agent, AgentDefinition)+ .join(+ AgentDefinition,+ (AgentDefinition.agent_id == Agent.id)+ & (AgentDefinition.tenant_id == Agent.tenant_id),+ )+ .outerjoin(+ TemplateInstallResource,+ (TemplateInstallResource.agent_id == Agent.id)+ & (TemplateInstallResource.tenant_id == Agent.tenant_id),+ )+ .where(+ Agent.tenant_id == tenant_id,+ Agent.name.like("switch-buddy%"),+ Agent.owner_id.is_not(None),+ TemplateInstallResource.id.is_(None),+ )+ )+ return [+ (agent, row)+ for agent, row in rows.tuples()+ if _BUDDY_NAME.match(agent.name)+ ]++ # ── Updating installs ───────────────────────────────────────────────────++ async def update_installs(self, tenant_id: str, template: OfficialTemplate) -> None:+ async with tenant_session(self._session_factory, tenant_id) as session:+ installs = [+ install+ for install in await self._store.of_template(session, template.id)+ if install.revision < template.version+ ]+ for install in installs:+ try:+ await self.update_install(tenant_id, template, install)+ except Exception:+ logger.error(+ "Could not update install %s of %s to revision %s",+ install.id,+ template.id,+ template.version,+ exc_info=True,+ )++ async def update_install(+ self, tenant_id: str, template: OfficialTemplate, install: TemplateInstall+ ) -> None:+ """Bring one install's agents up to `template`'s revision, then move+ the install to it, unless another server is doing the same."""+ try:+ plans = render_plans(template.content, install.inputs, install.builtins)+ except Exception as error:+ logger.warning(+ "Revision %s of %s cannot be rendered with what install %s was "+ "run with (%s): its agents stay as they are",+ template.version,+ template.id,+ install.id,+ error,+ )+ return+ async with tenant_session(self._session_factory, tenant_id) as session:+ resources = await self._store.resources(session, install.id)+ complete = True+ for resource in resources:+ plan = plans.get(resource.key)+ if resource.agent_id is None or plan is None:+ continue+ try:+ await self._update_agent(tenant_id, template, resource, plan)+ except LostRace:+ complete = False+ if not complete:+ return+ async with tenant_session(self._session_factory, tenant_id) as session:+ if await self._store.move_to_revision(+ session, install.id, from_revision=install.revision, to=template.version+ ):+ logger.info(+ "Updated install %s of %s from revision %s to %s",+ install.id,+ template.id,+ install.revision,+ template.version,+ )+ await session.commit()++ async def _update_agent(+ self,+ tenant_id: str,+ template: OfficialTemplate,+ resource: TemplateInstallResource,+ plan: NewAgentPlan,+ ) -> None:+ assert resource.agent_id is not None+ async with tenant_session(self._session_factory, tenant_id) as session:+ agent = await session.get(Agent, resource.agent_id)+ row = (+ await session.execute(+ select(AgentDefinition).where(+ AgentDefinition.tenant_id == tenant_id,+ AgentDefinition.agent_id == resource.agent_id,+ )+ )+ ).scalar_one_or_none()+ if agent is None:+ return+ current = agent_values(agent, row)+ new = plan_values(plan)+ changes: dict[str, str | None] = {}+ differs: list[str] = []+ fingerprints = dict(resource.fingerprints)+ for name in AGENT_FIELDS:+ if name not in current:+ continue+ if current[name] == new[name]:+ fingerprints[name] = fingerprint(new[name])+ elif fingerprints.get(name) == fingerprint(current[name]):+ changes[name] = new[name]+ fingerprints[name] = fingerprint(new[name])+ else:+ differs.append(name)+ await self._apply(tenant_id, agent, row, current, changes)+ held = held_permissions(plan, agent)+ notice = (+ notice_text(template, sorted(changes), differs, held)+ if differs or held+ else None+ )+ async with tenant_session(self._session_factory, tenant_id) as session:+ await self._store.set_fingerprints(session, resource.id, fingerprints)+ await self._store.set_notice(session, resource.id, notice)+ await session.commit()++ async def _apply(+ self,+ tenant_id: str,+ agent: Agent,+ row: AgentDefinition | None,+ current: dict[str, str | None],+ changes: dict[str, str | None],+ ) -> None:+ """Write `changes`, each only while the agent still has the value it+ was read with; `LostRace` when it no longer does."""+ profile = {k: v for k, v in changes.items() if k != "instructions"}+ if profile:+ async with tenant_session(self._session_factory, tenant_id) as session:+ written = await session.execute(+ update(Agent)+ .where(+ Agent.tenant_id == tenant_id,+ Agent.id == agent.id,+ *(+ getattr(Agent, k).is_(None)+ if current[k] is None+ else getattr(Agent, k) == current[k]+ for k in profile+ ),+ )+ .values(**profile)+ )+ if not written.rowcount: # type: ignore[attr-defined]+ raise LostRace(agent.id)+ await session.commit()+ async with tenant_session(self._session_factory, tenant_id):+ if {"description", "display_name"} & profile.keys():+ await self._protocol.update_bridge_identities(agent.id)+ if {"icon_url", "display_name"} & profile.keys():+ await self._protocol.agent_profile_changed(agent.id)+ if "instructions" in changes and row is not None:+ definition = DefinitionV1.model_validate(+ {+ **stored_definition(row.definition),+ "instructions": changes["instructions"],+ }+ )+ try:+ async with tenant_session(self._session_factory, tenant_id) as session:+ await self._management.patch_managed_agent(+ session,+ tenant_id,+ str(agent.owner_id),+ agent.id,+ definition=definition,+ desired_state=None,+ controller_id=None,+ controller_id_given=False,+ protocol=self._protocol,+ expected_revision=row.revision,+ )+ except DefinitionChanged as error:+ raise LostRace(agent.id) from errordiff --git a/core/switch_core/migrations/versions/a4c1e7b93d20_template_installs.py b/core/switch_core/migrations/versions/a4c1e7b93d20_template_installs.pyindex 16a564dc9..4f2924f39 100644--- a/core/switch_core/migrations/versions/a4c1e7b93d20_template_installs.py+++ b/core/switch_core/migrations/versions/a4c1e7b93d20_template_installs.py@@ -95,6 +95,7 @@ def upgrade() -> None:sa.Column("agent_id", sa.Text(), nullable=True),sa.Column("room_id", sa.Text(), nullable=True),sa.Column("fingerprints", JSONB(), nullable=False),+ sa.Column("notice", sa.Text(), nullable=True),sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], name="fk_template_install_resources_tenant"),diff --git a/core/switch_core/official_templates/__init__.py b/core/switch_core/official_templates/__init__.pyindex f1d7a316f..1008e1893 100644--- a/core/switch_core/official_templates/__init__.py+++ b/core/switch_core/official_templates/__init__.py@@ -21,7 +21,7 @@ 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-(``template_updates``). Changing a template means adding a revision, which+(``management/template_updates.py``). Changing a template means adding a revision, which``python -m switch_core.official_templates.revisions record <slug>`` does; atest fails while the files and the last revision disagree."""diff --git a/core/switch_core/template_installs.py b/core/switch_core/template_installs.pyindex e97e6b2b3..d8df44146 100644--- a/core/switch_core/template_installs.py+++ b/core/switch_core/template_installs.py@@ -84,11 +84,11 @@ def key_of(plan: NewAgentPlan, keys: dict[str, str]) -> str:return keys.get(plan.name, plan.name)-def render_agents(+def render_plans(text: str, inputs: dict[str, Any], builtins: dict[str, str]-) -> dict[str, dict[str, str | None]]:- """The values `text` sets on each agent it creates, by key, rendered with- the inputs and builtins a run used.+) -> dict[str, NewAgentPlan]:+ """Each agent `text` creates, by key, rendered with the inputs and+ builtins a run used.Where an agent runs does not change what it is told, so the run's machinestands in as the only one, ready for every provider: a machine since@@ -108,7 +108,18 @@ def render_agents(]plan = plan_template(text, {}, inputs, builtins=builtins, machines=machines)keys = resource_keys(text, inputs, builtins)- return {key_of(agent, keys): agent_fields(agent) for agent in plan.new_agents}+ return {key_of(agent, keys): agent for agent in plan.new_agents}+++def render_agents(+ text: str, inputs: dict[str, Any], builtins: dict[str, str]+) -> dict[str, dict[str, str | None]]:+ """The values `text` sets on each agent it creates, by key (see+ `render_plans`)."""+ return {+ key: agent_fields(plan)+ for key, plan in render_plans(text, inputs, builtins).items()+ }@dataclass(frozen=True)diff --git a/core/tests/switch_core/db/stores/test_agent_management_stores.py b/core/tests/switch_core/db/stores/test_agent_management_stores.pyindex 426bce638..0b39582c7 100644--- a/core/tests/switch_core/db/stores/test_agent_management_stores.py+++ b/core/tests/switch_core/db/stores/test_agent_management_stores.py@@ -282,6 +282,7 @@ class TestDefinitions:controller_id=None,desired_state="stopped",definition={"provider": "claude", "model": "m"},+ expected_revision=None,)assert updated.revision == 2assert updated.controller_id is Nonediff --git a/core/tests/switch_core/management/test_template_updates.py b/core/tests/switch_core/management/test_template_updates.pynew file mode 100644index 000000000..cf302665b--- /dev/null+++ b/core/tests/switch_core/management/test_template_updates.py@@ -0,0 +1,334 @@+"""Bringing the agents an official template created up to a new revision of+it, through the real management service: values nobody changed follow the+template, values somebody changed stay theirs, permissions never move, and+two servers updating at once update each agent once."""++from __future__ import annotations++import asyncio+from collections.abc import AsyncIterator, Iterator+from dataclasses import replace+from typing import Any++import httpx+import pytest+from sqlalchemy import select, update+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.agent.operations import context as op_context+from switch_core.db.models import (+ TENANT_ZERO_ID,+ Agent,+ AgentDefinition,+ TemplateInstall,+ User,+)+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.template_updates import BUDDY_ID, TemplateUpdates+from switch_core.official_templates import (+ OfficialTemplate,+ official_template,+ released_agent_fingerprints,+)+from tests.switch_core.management.harness import (+ Harness,+ add_member,+ build_harness,+ cookies_for,+ enroll_console,+)+from tests.switch_core.management.test_agent_operations import _NoRooms, _online++pytestmark = pytest.mark.usefixtures("_short_listen")+++def _short_listen(monkeypatch: pytest.MonkeyPatch) -> None:+ from switch_core.gateway import rooms as gateway_rooms++ monkeypatch.setattr(gateway_rooms, "LISTEN_TIMEOUT_SECONDS", 0.1)+++def harness(session_factory: async_sessionmaker[AsyncSession]) -> Iterator[Harness]:+ harness = build_harness(session_factory)+ previous = op_context._protocol+ op_context.init_operations_protocol(harness.protocol)+ harness.gateway_app.include_router(rooms_router, prefix="/rooms")+ harness.gateway_app.dependency_overrides[gw_deps.get_room_yaml_service] = lambda: (+ _NoRooms()+ )+ try:+ yield harness+ finally:+ op_context._protocol = previous+++async def client(harness: Harness) -> AsyncIterator[httpx.AsyncClient]:+ async with harness.client() as client:+ yield client+++def _buddy() -> OfficialTemplate:+ buddy = official_template(BUDDY_ID, True, switch_buddy=True)+ assert buddy is not None+ return buddy+++def _next_revision(+ *, edit: str = "", can_manage_agents: bool = True+) -> OfficialTemplate:+ """switch-buddy as a release after this one might ship it."""+ buddy = _buddy()+ content = buddy.content.replace(+ "Your assistant in Switch.", "Your assistant in Switch, revised."+ ).replace("You are **switch-buddy**", "You are **switch-buddy** (revised)" + edit)+ if not can_manage_agents:+ content = content.replace("can_manage_agents: true", "can_manage_agents: false")+ assert content != buddy.content+ return replace(buddy, content=content, version=buddy.version + 1)+++def _updates(harness: Harness) -> TemplateUpdates:+ return TemplateUpdates(+ session_factory=harness.session_factory,+ management=harness.management.service,+ protocol=harness.protocol,+ agent_management=True,+ switch_buddy=True,+ )+++async def _create_buddy(+ harness: Harness, client: httpx.AsyncClient, owner: User, name: str+) -> str:+ controller = await enroll_console(harness, client, owner, name=f"laptop-{name}")+ await _online(client, controller)+ response = await client.post(+ "/gateway/rooms/from-template-document",+ json={+ "template": _buddy().content,+ "template_name": "switch-buddy",+ "inputs": {"agent_name": name, "provider": "claude"},+ },+ cookies=cookies_for(owner),+ )+ assert response.status_code == 201, response.text+ return str(response.json()["created_agents"][0]["agent_id"])+++async def _agent(harness: Harness, agent_id: str) -> tuple[Agent, AgentDefinition]:+ async with harness.session_factory() as session:+ agent = await session.get(Agent, agent_id)+ row = (+ await session.execute(+ select(AgentDefinition).where(AgentDefinition.agent_id == agent_id)+ )+ ).scalar_one()+ assert agent is not None+ return agent, row+++async def _install(harness: Harness, agent_id: str) -> tuple[TemplateInstall, Any]:+ async with harness.session_factory() as session:+ found = await TemplateInstallStore().for_agent(session, agent_id)+ assert found is not None+ return found+++async def _owner_edits_instructions(harness: Harness, agent_id: str, text: str) -> None:+ _, row = await _agent(harness, agent_id)+ async with harness.session_factory() as session:+ await session.execute(+ update(AgentDefinition)+ .where(AgentDefinition.agent_id == agent_id)+ .values(+ definition={**row.definition, "instructions": text},+ revision=row.revision + 1,+ )+ )+ await session.commit()+++async def test_values_nobody_changed_follow_the_new_revision(+ harness: Harness, client: httpx.AsyncClient+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "switch-buddy-ada")+ _, before = await _agent(harness, agent_id)+ install, _ = await _install(harness, agent_id)+ new = _next_revision()++ await _updates(harness).update_install(TENANT_ZERO_ID, new, install)++ agent, row = await _agent(harness, agent_id)+ assert agent.description.startswith("Your assistant in Switch, revised.")+ assert "(revised)" in row.definition["instructions"]+ assert row.revision == before.revision + 1+ assert row.definition["provider"] == before.definition["provider"]+ install, resource = await _install(harness, agent_id)+ assert install.revision == new.version+ assert resource.notice is None+++async def test_values_somebody_changed_stay_theirs_and_the_agent_is_told(+ harness: Harness, client: httpx.AsyncClient+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "switch-buddy-ada")+ await _owner_edits_instructions(harness, agent_id, "Mine, all mine.")+ install, _ = await _install(harness, agent_id)+ new = _next_revision()++ await _updates(harness).update_install(TENANT_ZERO_ID, new, install)++ agent, row = await _agent(harness, agent_id)+ assert row.definition["instructions"] == "Mine, all mine."+ assert agent.description.startswith("Your assistant in Switch, revised.")+ install, resource = await _install(harness, agent_id)+ assert install.revision == new.version+ assert resource.notice is not None+ assert "instructions" in resource.notice+ assert "get_template_status" in resource.notice+++async def test_permissions_never_move_and_the_agent_is_told(+ harness: Harness, client: httpx.AsyncClient+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "switch-buddy-ada")+ install, _ = await _install(harness, agent_id)++ await _updates(harness).update_install(+ TENANT_ZERO_ID, _next_revision(can_manage_agents=False), install+ )++ agent, _ = await _agent(harness, agent_id)+ assert agent.can_manage_agents is True+ _, resource = await _install(harness, agent_id)+ assert resource.notice is not None and "can_manage_agents" in resource.notice+++async def test_an_install_at_the_current_revision_is_left_alone(+ harness: Harness, client: httpx.AsyncClient+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "switch-buddy-ada")+ _, before = await _agent(harness, agent_id)++ await _updates(harness).update_installs(TENANT_ZERO_ID, _buddy())++ _, after = await _agent(harness, agent_id)+ assert after.revision == before.revision+++async def test_an_agent_changed_mid_update_is_left_to_the_next_start(+ harness: Harness, client: httpx.AsyncClient, monkeypatch: pytest.MonkeyPatch+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "switch-buddy-ada")+ install, _ = await _install(harness, agent_id)++ async def changed(*args: Any, **kwargs: Any) -> None:+ raise DefinitionChanged("changed meanwhile")++ monkeypatch.setattr(harness.management.service, "patch_managed_agent", changed)+ await _updates(harness).update_install(TENANT_ZERO_ID, _next_revision(), install)++ install, _ = await _install(harness, agent_id)+ assert install.revision == _buddy().version+++async def test_two_servers_updating_at_once_update_each_agent_once(+ harness: Harness, client: httpx.AsyncClient+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "switch-buddy-ada")+ _, before = await _agent(harness, agent_id)+ install, _ = await _install(harness, agent_id)+ new = _next_revision()++ await asyncio.gather(+ _updates(harness).update_install(TENANT_ZERO_ID, new, install),+ _updates(harness).update_install(TENANT_ZERO_ID, new, install),+ )++ _, row = await _agent(harness, agent_id)+ assert "(revised)" in row.definition["instructions"]+ assert row.revision == before.revision + 1+ install, _ = await _install(harness, agent_id)+ assert install.revision == new.version+++async def _forget_install(harness: Harness, agent_id: str) -> None:+ install, _ = await _install(harness, agent_id)+ async with harness.session_factory() as session:+ await session.delete(await session.get(TemplateInstall, install.id))+ await session.commit()+++async def test_an_old_buddy_is_recorded_as_the_revision_it_matches(+ harness: Harness, client: httpx.AsyncClient+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "switch-buddy-ada")+ await _forget_install(harness, agent_id)++ assert await _updates(harness).record_existing_buddies(TENANT_ZERO_ID) == 1++ install, resource = await _install(harness, agent_id)+ assert (install.template_id, install.revision) == (BUDDY_ID, _buddy().version)+ assert resource.key == "buddy"+ assert (+ resource.fingerprints+ == released_agent_fingerprints("switch-buddy")[0][1]["buddy"]+ )+ assert await _updates(harness).record_existing_buddies(TENANT_ZERO_ID) == 0+++async def test_an_old_buddy_somebody_changed_is_recorded_and_its_changes_kept(+ harness: Harness, client: httpx.AsyncClient+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "switch-buddy-ada")+ await _forget_install(harness, agent_id)+ await _owner_edits_instructions(harness, agent_id, "Mine, all mine.")+ await _updates(harness).record_existing_buddies(TENANT_ZERO_ID)+ install, _ = await _install(harness, agent_id)++ await _updates(harness).update_install(TENANT_ZERO_ID, _next_revision(), install)++ agent, row = await _agent(harness, agent_id)+ assert row.definition["instructions"] == "Mine, all mine."+ assert agent.description.startswith("Your assistant in Switch, revised.")+++async def test_a_name_alone_does_not_make_an_agent_a_buddy(+ harness: Harness, client: httpx.AsyncClient+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "switch-buddy-ada")+ await _forget_install(harness, agent_id)+ async with harness.session_factory() as session:+ await session.execute(+ update(Agent)+ .where(Agent.id == agent_id)+ .values(description="My own thing.", icon_url=None)+ )+ await session.commit()++ assert await _updates(harness).record_existing_buddies(TENANT_ZERO_ID) == 0+++async def test_an_agent_not_named_as_a_buddy_is_never_taken_for_one(+ harness: Harness, client: httpx.AsyncClient+) -> None:+ owner = await add_member(harness.session_factory, "ada")+ agent_id = await _create_buddy(harness, client, owner, "my-helper")+ await _forget_install(harness, agent_id)++ assert await _updates(harness).record_existing_buddies(TENANT_ZERO_ID) == 0