Skip to content

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

Document template revisions, installs and updates

Simon Flackef9303ec7c0a
diff --git a/core/switch_core/template_guide.py b/core/switch_core/template_guide.py
index 189f1bea9..178741931 100644
--- a/core/switch_core/template_guide.py
+++ b/core/switch_core/template_guide.py
@@ -203,6 +203,14 @@ anything is created (leave a new agent on the default, owner-agents, or give
it anyone_in its room; owner shuts you out). Asking again for a room with the same kickoff you already used
further up the same path pauses the run until your owner lets it continue.
+## Revisions and updates
+
+A template's revision is its own edit count, not the language version.
+Running a saved or official template by id records which agents that run
+created; an agent created from an official template is brought up to each new
+revision of it when the server starts, except for what someone changed and its
+permissions. get_template_status tells an agent how it differs from its own.
+
## Example
version: 2
diff --git a/docs/TEMPLATES.md b/docs/TEMPLATES.md
index f56f895b5..e56311456 100644
--- a/docs/TEMPLATES.md
+++ b/docs/TEMPLATES.md
@@ -25,8 +25,9 @@ root is the worked example, and `examples/` holds more.
10. [The form block](#the-form-block)
11. [Version 2](#version-2)
12. [Agents and saved templates](#agents-and-saved-templates)
-13. [Validation](#validation)
-14. [Versioning](#versioning)
+13. [Installs and updates](#installs-and-updates)
+14. [Validation](#validation)
+15. [Versioning](#versioning)
## A first template
@@ -710,6 +711,46 @@ documents against (`core/switch_core/template_guide.py`; keep it in step).
A refusal tells the agent why. The server logs it, naming the agent, and
counts it in telemetry by operation and reason.
+## Installs and updates
+
+A template's **revision** is its own edit count, not the language version
+(`version: 2`): a saved template's goes up each time its document is
+replaced, and an official template's is the last entry in its
+`revisions.json`, beside its files. Changing an official template means
+adding a revision (`python -m switch_core.official_templates.revisions record
+<slug>`); a test fails while its files and its last revision disagree.
+
+When the server runs a template whose source it can vouch for, it records
+the run as an **install**: the template's id and revision, the inputs it was
+rendered with, and, for each agent it created, the template's key for it (a
+version 2 resource key) and a fingerprint of each value the template set on
+it: instructions, description, icon and display name. It vouches for an
+agent's `run_template`, which names the template by id, and for a document
+the Console sends with a `template_id`, when the document is exactly that
+template's. A document that is an official template's word for word is
+recognised without one. A document someone wrote or changed has no install.
+The managed agent API returns the install as `template` (`{id, key,
+revision}`, or null).
+
+When the server starts, every install of an official template at an older
+revision is brought up to the current one:
+
+- A value whose fingerprint still matches (nobody changed it) takes the new
+ revision's value. A running agent is told its instructions changed.
+- A value somebody changed is left as it is.
+- Who may address the agent and whether it can manage agents never change,
+ whichever way the new revision would move them.
+
+When anything was left, the agent is told before each message, until it
+calls `get_template_status`, which lists what differs from the current
+revision and what the template recommends. switch-buddy's instructions have
+it explain that to its owner, who decides and makes any change. Every write
+is conditional on what was read, so servers starting together update each
+agent once. switch-buddies created before installs were recorded are
+recorded first, when named as buddies are and still carrying a released
+revision's icon or description, as the revision they match most. Saved
+templates are recorded but not updated yet.
+
## Validation
The server checks a document on upload and before provisioning, and the