Skip to content

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

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.py
index 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.py
index 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.py
index 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 AsyncSession
from 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 row
diff --git a/core/switch_core/db/stores/template_install_store.py b/core/switch_core/db/stores/template_install_store.py
index 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.py
index 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_ids
from switch_core.delivery.conversation import ConversationRules, ConversationSettings
from switch_core.delivery.recipient import RecipientServices
from switch_core.delivery.router import GROUP_SWEEP_SECONDS, MessageRouter
+from switch_core.feature_flags import AGENT_MANAGEMENT, SWITCH_BUDDY
from switch_core.gateway.app import create_gateway_app
from switch_core.gateway.auth import hash_password
from switch_core.gateway.invite_mail import SmtpInviteMailer
from switch_core.gateway.ui import GatewayUi
from switch_core.logging_config import configure_logging
+from switch_core.management.template_updates import TemplateUpdates
from switch_core.management.wiring import Management, create_management
from switch_core.messages.notify import MessageListener
from switch_core.observability.bootstrap import (
@@ -1416,6 +1418,22 @@ async def run(config: SwitchConfig, process_id: str) -> None:
if management is not None
else 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 lapse
diff --git a/core/switch_core/management/agent_operations.py b/core/switch_core/management/agent_operations.py
index 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.py
index 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_id
diff --git a/core/switch_core/management/service.py b/core/switch_core/management/service.py
index 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_id
to_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.py
new file mode 100644
index 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 error
diff --git a/core/switch_core/migrations/versions/a4c1e7b93d20_template_installs.py b/core/switch_core/migrations/versions/a4c1e7b93d20_template_installs.py
index 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__.py
index 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, 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
-(``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; a
test fails while the files and the last revision disagree.
"""
diff --git a/core/switch_core/template_installs.py b/core/switch_core/template_installs.py
index 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 machine
stands 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.py
index 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 == 2
assert updated.controller_id is None
diff --git a/core/tests/switch_core/management/test_template_updates.py b/core/tests/switch_core/management/test_template_updates.py
new file mode 100644
index 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