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
"""Declarative provisioning of rooms from YAML, and export back.
Two document shapes are supported, told apart by their top-level key:
* **Single room** (``room:``): one room with its attachments, and an optional
top-level ``kickoff:`` posted once it exists.
* **Group** (``group:`` + ``rooms:``): a room group, several rooms filed under
it, and optional directed ``links:`` between them. A kickoff belongs to the
room it is for, so in a group it sits inside each room entry.
v0 supports a ``params:`` block that declares typed, defaultable
placeholders. ``parse_template(text, inputs)`` resolves them and interpolates
``{name}`` throughout the document before validation, so one file can stamp
out many rooms with different inputs. A literal ``{word}`` that collides
with a declared param name *is* substituted — this is accepted for v0;
``sensitive: true`` is deferred to a later version.
An optional top-level ``version:`` key (default ``0``) is accepted and
validated as an integer, but not acted on yet.
Provisioning is room-first and best-effort: the room is created first (which
fails loud on bad agents / refs / config), then inline references and docs are
attached, with any post-creation failures collected into ``failed_attachments``
rather than silently dropped. A group is provisioned room by room in order; a
room that fails is reported in ``errors`` and does not roll back the others.
Export emits resolved rooms and never emits ``params:``.
"""
from __future__ import annotations
import logging
import re
import time
from dataclasses import dataclass
from datetime import date
from typing import TYPE_CHECKING, Any, Literal, cast
import yaml
from pydantic import BaseModel, Field, TypeAdapter, ValidationError, model_validator
from switch_core.agent_runs import AgentOrigin, kickoff_fingerprint
from switch_core.authz import Principal, can, require_group_filing
from switch_core.bridges.collaboration.models import ChannelType
from switch_core.bridges.resource.registry import validate_reference_value
from switch_core.clients.actor import SystemActor
from switch_core.clients.admin_messages import OnBehalfOf
from switch_core.room_service import RoleSpec, RoomCreateConfig
if TYPE_CHECKING:
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from switch_core.bridges.resource.service import ResourceService
from switch_core.clients.client_lifecycle_service import ClientLifecycleService
from switch_core.db.models import Room
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.collaboration_bridge_store import (
CollaborationBridgeStore,
)
from switch_core.db.stores.external_user_store import ExternalUserStore
from switch_core.db.stores.room_group_store import RoomGroupStore
from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.room_service import RoomService
logger = logging.getLogger(__name__)
# ── Template parameters (v0) ─────────────────────────────────────────────
# How long a kickoff waits for the room's members to join before posting.
KICKOFF_JOIN_TIMEOUT = 30.0
PLACEHOLDER_RE = re.compile(r"\{(\$?[A-Za-z_][A-Za-z0-9_]*)\}")
# Param types whose value names something the server already has. They
# interpolate as plain strings; the difference is that the server checks the
# name before provisioning and the Console offers a picker instead of a text
# box. The value is the name a template would write: an agent's name, a
# bridge's display name, a room's name, a platform username.
ENTITY_PARAM_TYPES = ("agent", "bridge", "room", "user")
@dataclass(frozen=True)
class RoomReader:
"""Who a template runs as, which decides the rooms its `room` params may
name: the rooms `principal` may read, plus the rooms `agent_id` is in when
an agent runs it. Any other room reads as missing, so a template cannot
confirm or fill in the name of a room its runner cannot see."""
principal: Principal
agent_id: str | None = None
# Param types that say how an agent the template creates runs: the coding
# agent that runs it, where it runs (`location`, a Console answer: this
# computer or an SSH host; `machine`, one of the owner's machines on the
# server), and its working directory. They are read when the agents are
# created and removed before the rooms are provisioned; if one does reach
# provisioning it is treated as a string.
CONSOLE_PARAM_TYPES = ("provider", "location", "machine", "directory")
# Param types whose ``default`` may be a list of candidates, tried in order
# until one names something the server (or, for the Console's types, the
# Console) has. ``$first`` in such a list stands for the first thing of the
# param's type: the default messaging app, the first agent or room by name,
# the first coding agent available where the agent runs. A `user` param has no "first":
# which account is meant depends on who asks, and ``{$creator}`` already
# covers the deployer.
CHAIN_PARAM_TYPES = ("agent", "bridge", "room", "provider", "location", "machine")
FIRST = "$first"
# In a `room` param's chain: the room the template's own ``room:`` block
# describes. Resolved by the Console, which decides between creating that
# room and joining a chosen one; it never reaches the server.
NEW = "$new"
# The types whose param may be left without a value when the template marks
# it ``required: false`` and gives no default: a string is empty, a room
# with no bridge lands on the server's default messaging app, and an unset
# room drops out of the list it was written in (an agent's ``join``, where
# it means "no room").
OPTIONAL_WITHOUT_DEFAULT_TYPES = ("string", "bridge", "room")
ParamType = Literal[
"string",
"number",
"boolean",
"enum",
"agent",
"bridge",
"room",
"user",
"provider",
"location",
"machine",
"directory",
]
# How a form presents a param. ``ask`` is a visible input. ``advanced`` is
# prefilled from the default and folded away for the deployer who wants it.
# ``fixed`` is the default, shown but not editable: the template author has
# decided, and wrote it as a param to name and describe the value.
ParamInput = Literal["ask", "advanced", "fixed"]
class ParamSpec(BaseModel):
model_config = {"extra": "forbid"}
type: ParamType = "string"
description: str | None = None
# The human name of the input on a form, when the key is not one.
label: str | None = None
# A value, or for a type in CHAIN_PARAM_TYPES a list of candidates tried
# in order (see ``resolve_defaults``).
default: str | int | float | bool | list[str] | None = None
# Whether the value may be empty when the template is used. Unset means
# "required unless there is a default"; a chain is not one, since every
# candidate can be absent, so a param with a chain stays required unless
# the template says otherwise.
required: bool | None = None
input: ParamInput = "ask"
enum: list[str] | None = None
# Rendering hint for string params that carry long text (a task brief,
# instructions): the form shows a textarea instead of a one-line input,
# which would strip the pasted text's newlines.
multiline: bool = False
# A regular expression the whole value of a string param must match.
pattern: str | None = None
# Bounds of a number param, inclusive.
min: float | None = None
max: float | None = None
@property
def is_required(self) -> bool:
if self.required is not None:
return self.required
return self.default is None or isinstance(self.default, list)
@model_validator(mode="after")
def _fields_fit_the_type(self) -> ParamSpec:
if isinstance(self.default, list):
if self.type not in CHAIN_PARAM_TYPES:
raise ValueError(
"a list default applies to params of type "
+ ", ".join(CHAIN_PARAM_TYPES)
)
if not self.default:
raise ValueError("a list default must name at least one candidate")
if NEW in self.default and self.type != "room":
raise ValueError(f"{NEW!r} applies to params of type room")
if self.input == "fixed" and self.default is None:
raise ValueError("a fixed param needs a default: that is its value")
if (
self.required is False
and self.default is None
and self.type not in OPTIONAL_WITHOUT_DEFAULT_TYPES
):
raise ValueError(
f"a {self.type} param without a default cannot be optional; "
"give it a default or leave it required"
)
if self.pattern is not None:
if self.type != "string":
raise ValueError("'pattern' applies to params of type string")
try:
re.compile(self.pattern)
except re.error as e:
raise ValueError(
f"'pattern' is not a valid regular expression: {e}"
) from e
if (self.min is not None or self.max is not None) and self.type != "number":
raise ValueError("'min' and 'max' apply to params of type number")
if self.min is not None and self.max is not None and self.min > self.max:
raise ValueError("'min' must not exceed 'max'")
return self
def coerce_param(value: Any, spec: ParamSpec, name: str) -> str | int | float | bool:
"""Coerce a raw input value to the declared type."""
t = spec.type
if t == "string":
s = str(value)
if spec.pattern is not None and re.fullmatch(spec.pattern, s) is None:
raise ValueError(
f"param {name!r}: {s!r} does not match the pattern {spec.pattern!r}"
)
return s
if t in ENTITY_PARAM_TYPES or t in CONSOLE_PARAM_TYPES:
return str(value)
if t == "number":
if isinstance(value, bool):
raise ValueError(f"param {name!r}: expected a number, got {value!r}")
n: int | float
if isinstance(value, int):
n = value # keep int as int; no float roundtrip, no precision loss
else:
try:
f = float(value)
n = int(f) if f == int(f) else f
except (ValueError, TypeError, OverflowError) as e:
raise ValueError(
f"param {name!r}: expected a number, got {value!r}"
) from e
if spec.min is not None and n < spec.min:
raise ValueError(f"param {name!r}: {n} is below the minimum {spec.min:g}")
if spec.max is not None and n > spec.max:
raise ValueError(f"param {name!r}: {n} is above the maximum {spec.max:g}")
return n
if t == "boolean":
if isinstance(value, bool):
return value
if isinstance(value, str):
low = value.lower()
if low in ("true", "1", "yes"):
return True
if low in ("false", "0", "no"):
return False
raise ValueError(f"param {name!r}: expected a boolean, got {value!r}")
# enum
s = str(value)
if spec.enum and s not in spec.enum:
raise ValueError(f"param {name!r}: {s!r} is not one of {spec.enum}")
return s
def resolve_params(
declared: dict[str, ParamSpec],
inputs: dict[str, Any] | None,
) -> dict[str, str | int | float | bool]:
"""Merge inputs over defaults, enforce required, coerce types.
A list default is a chain that ``resolve_defaults`` turns into an input
before this runs; one still here has no candidate the server has, and
counts as no value. An optional param left without a value is a string
left empty, or an entity name left out of the result altogether so that
``drop_unset`` can clear the field it was written into.
"""
if inputs is not None and not isinstance(inputs, dict):
raise ValueError("'inputs' must be a mapping of param name to value")
inputs = inputs or {}
undeclared = set(inputs) - set(declared)
if undeclared:
raise ValueError(f"Undeclared input(s): {', '.join(sorted(undeclared))}")
resolved: dict[str, str | int | float | bool] = {}
missing: list[str] = []
for name, spec in declared.items():
if name in inputs and inputs[name] is not None:
resolved[name] = coerce_param(inputs[name], spec, name)
elif spec.default is not None and not isinstance(spec.default, list):
resolved[name] = coerce_param(spec.default, spec, name)
elif spec.is_required:
missing.append(name)
elif spec.type == "string":
resolved[name] = ""
if missing:
chains = [n for n in missing if isinstance(declared[n].default, list)]
if chains:
raise ValueError(
"Missing required param(s): "
+ ", ".join(missing)
+ " (none of the candidates listed for "
+ ", ".join(chains)
+ " is set up here)"
)
raise ValueError(f"Missing required param(s): {', '.join(missing)}")
return resolved
def unset_params(declared: dict[str, ParamSpec], values: dict[str, Any]) -> set[str]:
"""The declared params ``resolve_params`` gave no value: optional entity
params the caller left empty."""
return {name for name in declared if name not in values}
def drop_unset(node: Any, names: set[str]) -> Any:
"""Clear the fields written as exactly ``{name}`` for an unset param.
A mapping value becomes null (a room's ``bridge: null`` lands on the
default messaging app); a list entry is removed. A placeholder inside a
longer string is left as written, since there is nothing sensible to put
there.
"""
if not names:
return node
def _is_unset(value: Any) -> bool:
if not isinstance(value, str):
return False
m = PLACEHOLDER_RE.fullmatch(value)
return m is not None and m.group(1) in names
if isinstance(node, dict):
return {
k: (None if _is_unset(v) else drop_unset(v, names)) for k, v in node.items()
}
if isinstance(node, list):
return [drop_unset(v, names) for v in node if not _is_unset(v)]
return node
def interpolate(
node: Any,
values: dict[str, str | int | float | bool],
) -> Any:
"""Recursively substitute ``{name}`` placeholders in *node*.
If an entire string is exactly one placeholder for a declared param the
typed value is returned unchanged (so a boolean/enum param can fill a
non-string field). Otherwise each declared placeholder in the string is
replaced with ``str(value)``. Undeclared ``{word}`` patterns are left
untouched so that JSON braces and other non-param patterns survive.
"""
if isinstance(node, str):
# Whole-field substitution: the entire string is one placeholder.
m = PLACEHOLDER_RE.fullmatch(node)
if m and m.group(1) in values:
return values[m.group(1)]
# Partial substitution within the string.
def _replace(m: re.Match[str]) -> str:
key = m.group(1)
if key in values:
return str(values[key])
return m.group(0) # leave undeclared placeholders intact
return PLACEHOLDER_RE.sub(_replace, node)
if isinstance(node, dict):
# Keys are interpolated as well as values. An alias map is written
# `"{bot}": helper`, where the key is the agent name a param provides.
return {interpolate(k, values): interpolate(v, values) for k, v in node.items()}
if isinstance(node, list):
return [interpolate(item, values) for item in node]
return node
# ── Spec models ───────────────────────────────────────────────────────────
#
# An external reference in a room spec is one of three distinct shapes. They
# are kept as separate models (rather than one model with a discriminating
# validator) so each carries exactly its own fields; ``extra="forbid"`` makes
# the union unambiguous — the presence of ``id`` / ``name`` / ``type`` selects
# the variant.
class ExistingReferenceById(BaseModel):
"""Attach an existing external reference by id (exact, unambiguous)."""
model_config = {"extra": "forbid"}
id: str
class ExistingReferenceByName(BaseModel):
"""Attach an existing external reference by name (resolved over the
caller's owned + public references; ambiguity is an error)."""
model_config = {"extra": "forbid"}
name: str
class InlineExternalReference(BaseModel):
"""Define a brand-new external reference inline; always creates one. Mirrors
the fields of ``ResourceService.create_reference`` for an external ref."""
model_config = {"extra": "forbid"}
type: str
name: str
description: str
instructions: str
value: dict[str, Any]
read_visibility: str = "private"
write_visibility: str = "private"
@model_validator(mode="after")
def _validate_value(self) -> InlineExternalReference:
# Only the value bag's shape can be checked here: parse() is
# synchronous and holds neither a session nor a principal, so whether
# the type exists and is readable is settled in _resolve_references.
self.value = validate_reference_value(self.value)
return self
ExternalReferenceEntry = (
ExistingReferenceById | ExistingReferenceByName | InlineExternalReference
)
# A package in a room spec is always one that exists: a template attaches
# packages but never defines or changes one, so there is no inline shape.
class ExistingPackageById(BaseModel):
"""Attach an existing package by id (exact, unambiguous)."""
model_config = {"extra": "forbid"}
id: str
class ExistingPackageByName(BaseModel):
"""Attach an existing package by name (resolved over the caller's owned +
public packages; ambiguity is an error)."""
model_config = {"extra": "forbid"}
name: str
PackageEntry = ExistingPackageById | ExistingPackageByName
class DocSpec(BaseModel):
name: str
description: str
instructions: str
content: str
class RoomSpec(BaseModel):
name: str
description: str
instructions: str | None = None
# Collaboration bridge display name; omit for an internal-only room.
bridge: str | None = None
channel_type: Literal["channel_public", "channel_private"] = "channel_public"
read_visibility: str = "public"
write_visibility: str = "public"
agents: list[str] = []
users: list[str] = []
roles: list[RoleSpec] = []
references: list[ExternalReferenceEntry] = []
packages: list[PackageEntry] = []
docs: list[DocSpec] = []
# Agent name to the alias it can be addressed by in this room.
aliases: dict[str, str] | None = None
# Used only for a room inside a group's ``rooms:`` list, where each room
# has its own kickoff. A single-room document puts ``kickoff:`` at the
# top level, next to ``room:``.
kickoff: str | None = None
# ── Group document models ────────────────────────────────────────────────
class GroupLinkSpec(BaseModel):
model_config = {"extra": "forbid", "populate_by_name": True}
from_: str = Field(alias="from")
to: str
label: str
class GroupMeta(BaseModel):
model_config = {"extra": "forbid"}
name: str
description: str | None = None
color: str | None = None
class GroupSpec(BaseModel):
group: GroupMeta
rooms: list[RoomSpec]
links: list[GroupLinkSpec] = []
class RoomTemplateDocument(BaseModel):
"""Top-level shape of a single-room template file."""
room: RoomSpec
params: dict[str, ParamSpec] | None = None
kickoff: str | None = None
class GroupTemplateDocument(BaseModel):
"""Top-level shape of a group template file."""
group: GroupMeta
rooms: list[RoomSpec]
links: list[GroupLinkSpec] = []
params: dict[str, ParamSpec] | None = None
# Both document shapes, for the JSON Schema served by ``GET /rooms/template-schema``.
TemplateDocument = RoomTemplateDocument | GroupTemplateDocument
def template_json_schema() -> dict[str, Any]:
"""The schema a client validates a template against, either shape."""
return TypeAdapter(TemplateDocument).json_schema()
@dataclass(frozen=True)
class ParsedTemplate:
"""What ``parse_template`` makes of one template plus one set of inputs."""
spec: RoomSpec | GroupSpec
#: The kickoff of a single-room document. A group's kickoffs are on its rooms.
kickoff: str | None
#: The template's declared params, by name.
params: dict[str, ParamSpec]
#: The value each declared param resolved to (input or default), coerced.
values: dict[str, str | int | float | bool]
class ProvisionResult(BaseModel):
room_id: str
room_name: str
attached_reference_ids: list[str] = []
attached_package_ids: list[str] = []
created_reference_ids: list[str] = []
created_document_ids: list[str] = []
role_names: list[str] = []
failed_attachments: list[dict[str, Any]] = []
class GroupProvisionResult(BaseModel):
group_id: str
group_name: str
rooms: list[ProvisionResult] = []
errors: list[dict[str, Any]] = []
# ── YAML literal-block dumper (keeps multiline doc content readable) ────────
class _SpecDumper(yaml.SafeDumper):
pass
def _str_representer(dumper: yaml.SafeDumper, data: str) -> Any:
style = "|" if "\n" in data else None
return dumper.represent_scalar("tag:yaml.org,2002:str", data, style=style)
_SpecDumper.add_representer(str, _str_representer)
class RoomYamlService:
"""Parse / provision / export rooms as YAML. Free of HTTP concerns so it
is unit-testable and reusable for future MCP / CLI surfaces."""
def __init__(
self,
*,
room_service: RoomService,
resource_service: ResourceService,
room_store: RoomStore,
agent_store: AgentStore,
bridge_store: CollaborationBridgeStore,
external_user_store: ExternalUserStore,
room_role_store: RoomRoleStore,
session_factory: async_sessionmaker[AsyncSession],
room_group_store: RoomGroupStore,
client_lifecycle: ClientLifecycleService | None = None,
) -> None:
self._rooms = room_service
self._resources = resource_service
self._room_store = room_store
self._agent_store = agent_store
self._bridge_store = bridge_store
self._external_users = external_user_store
self._room_roles = room_role_store
self._room_groups = room_group_store
self._session_factory = session_factory
self._client_lifecycle = client_lifecycle
# ── Parse ─────────────────────────────────────────────────────────────
def parse(
self,
text: str,
inputs: dict[str, Any] | None = None,
builtins: dict[str, str] | None = None,
) -> tuple[RoomSpec, str | None]:
"""Parse a YAML template into a ``RoomSpec`` and optional kickoff message.
The short form of ``parse_template`` for callers that only need the
room; the gateway uses the long form so it can also check the
entity-typed params before provisioning.
"""
parsed = self.parse_template(text, inputs=inputs, builtins=builtins)
if isinstance(parsed.spec, GroupSpec):
raise ValueError(
"this is a group template; parse_template handles both shapes"
)
return parsed.spec, parsed.kickoff
def parse_template(
self,
text: str,
inputs: dict[str, Any] | None = None,
builtins: dict[str, str] | None = None,
) -> ParsedTemplate:
"""Parse a YAML template into its spec, kickoff, and resolved params.
The top-level key tells the shapes apart: ``room:`` gives a
``RoomSpec``, ``group:`` + ``rooms:`` a ``GroupSpec``.
``builtins`` are server-injected variables (e.g. ``{creator}``) that
are always available for interpolation alongside user-supplied
``inputs``. They are resolved first and never collide with declared
params; a param named ``creator`` would shadow the built-in, which is
intentional (the template author owns the namespace).
"""
try:
data = yaml.safe_load(text)
except yaml.YAMLError as e:
raise ValueError(f"Invalid YAML: {e}") from e
if not isinstance(data, dict):
raise ValueError("YAML must have a single top-level 'room:' mapping")
is_group = "group" in data
if not is_group and "room" not in data:
raise ValueError("YAML must have a top-level 'room:' or 'group:' mapping")
allowed_keys = (
{"group", "rooms", "links", "params", "version"}
if is_group
else {"room", "params", "version", "kickoff"}
)
extra = set(data) - allowed_keys
if extra:
if is_group and extra == {"kickoff"}:
raise ValueError(
"a group template's kickoff goes on the room it is for: "
"put 'kickoff:' inside each entry of 'rooms:'"
)
raise ValueError(f"Unknown top-level key(s): {', '.join(sorted(extra))}")
# version: accepted, not acted on yet.
version = data.get("version", 0)
if not isinstance(version, int):
raise ValueError(
f"'version' must be an integer, got {type(version).__name__}"
)
raw_params = data.get("params")
if raw_params is not None:
if not isinstance(raw_params, dict):
raise ValueError("'params' must be a mapping")
try:
declared = {
k: ParamSpec.model_validate(v) for k, v in raw_params.items()
}
except ValidationError as e:
raise ValueError(f"Invalid param spec: {e}") from e
else:
declared = {}
if inputs and not declared:
raise ValueError("Inputs supplied but the template declares no params")
# Build the interpolation values: builtins first, then params override
values: dict[str, str | int | float | bool] = dict(builtins or {})
resolved: dict[str, str | int | float | bool] = {}
if declared:
resolved = resolve_params(declared, inputs)
values.update(resolved)
body = {k: v for k, v in data.items() if k not in ("params", "version")}
if values:
body = interpolate(body, values)
if declared:
body = drop_unset(body, unset_params(declared, resolved))
if is_group:
spec: RoomSpec | GroupSpec = self._group_spec(body)
kickoff = None
else:
try:
spec = RoomSpec.model_validate(body["room"])
except ValidationError as e:
raise ValueError(f"Invalid room spec: {e}") from e
if spec.kickoff is not None:
raise ValueError(
"a single-room template's kickoff goes at the top level, "
"beside 'room:'"
)
kickoff_raw = body.get("kickoff")
if kickoff_raw is not None and not isinstance(kickoff_raw, str):
raise ValueError(
f"'kickoff' must be a string, got {type(kickoff_raw).__name__}"
)
kickoff = kickoff_raw
return ParsedTemplate(
spec=spec, kickoff=kickoff, params=declared, values=resolved
)
@staticmethod
def _group_spec(body: dict[str, Any]) -> GroupSpec:
"""Validate an interpolated group document: the meta, every room, and
links that name rooms the document has."""
if "rooms" not in body:
raise ValueError("Group document requires a 'rooms:' list")
try:
group_meta = GroupMeta.model_validate(body["group"])
except ValidationError as e:
raise ValueError(f"Invalid group spec: {e}") from e
raw_rooms = body["rooms"]
if not isinstance(raw_rooms, list) or not raw_rooms:
raise ValueError("'rooms:' must be a non-empty list")
rooms: list[RoomSpec] = []
for i, entry in enumerate(raw_rooms):
try:
rooms.append(RoomSpec.model_validate(entry))
except ValidationError as e:
raise ValueError(f"Invalid room spec at index {i}: {e}") from e
raw_links = body.get("links") or []
if not isinstance(raw_links, list):
raise ValueError("'links:' must be a list")
links: list[GroupLinkSpec] = []
for i, entry in enumerate(raw_links):
try:
links.append(GroupLinkSpec.model_validate(entry))
except ValidationError as e:
raise ValueError(f"Invalid link spec at index {i}: {e}") from e
# Links refer to rooms by name, so room names must be unique in the document.
seen: set[str] = set()
dupes: list[str] = []
for r in rooms:
if r.name in seen and r.name not in dupes:
dupes.append(r.name)
seen.add(r.name)
if dupes:
raise ValueError(f"Duplicate room name(s): {', '.join(dupes)}")
for link in links:
for end, name in (("from", link.from_), ("to", link.to)):
if name not in seen:
raise ValueError(
f"Link {end} {name!r} does not match any room name"
)
return GroupSpec(group=group_meta, rooms=rooms, links=links)
# ── Entity params ─────────────────────────────────────────────────────
async def check_entity_params(
self, parsed: ParsedTemplate, *, reader: RoomReader
) -> None:
"""Every entity-typed param must name something this server has.
Raises ``ValueError`` in the ``param 'x': ...`` form the Console maps
back onto the field. Runs between ``parse_template`` and ``provision``
so a bad name fails at the input, not as a half-built room. A ``user``
param resolves on the bridge the room will land on, hence the parsed
spec rather than the raw inputs.
"""
wanted: dict[str, list[tuple[str, str]]] = {}
for name, spec in parsed.params.items():
# An optional entity param left empty names nothing to check.
if spec.type in ENTITY_PARAM_TYPES and name in parsed.values:
wanted.setdefault(spec.type, []).append(
(name, str(parsed.values[name]))
)
if not wanted:
return
async with self._session_factory() as session:
if "agent" in wanted:
names = [value for _, value in wanted["agent"]]
agents = await self._agent_store.get_by_names(session, names)
known = {a.name for a in agents}
for param, value in wanted["agent"]:
if value not in known:
raise ValueError(
f"param {param!r}: no agent named {value!r} here"
)
if "bridge" in wanted:
bridges = {
b.display_name: b for b in await self._bridge_store.get_all(session)
}
for param, value in wanted["bridge"]:
bridge = bridges.get(value)
if bridge is None:
raise ValueError(
f"param {param!r}: no messaging app named {value!r} here"
)
if bridge.status != "active":
raise ValueError(
f"param {param!r}: messaging app {value!r} is not running"
)
if "room" in wanted:
rooms = set(await self._readable_room_names(session, reader))
for param, value in wanted["room"]:
if value not in rooms:
raise ValueError(
f"param {param!r}: no room named {value!r} here"
)
if "user" in wanted:
# TODO: look users up on each room's messaging app. Only the first
# room's app is checked, so a group whose rooms are on different
# apps passes here and gets a failed attachment when the other
# rooms are provisioned.
first = (
parsed.spec.rooms[0]
if isinstance(parsed.spec, GroupSpec)
else parsed.spec
)
bridge_id = await self._resolve_bridge_id(first.bridge)
if bridge_id is None:
param = wanted["user"][0][0]
raise ValueError(
f"param {param!r}: a user can only be looked up on a messaging "
"app, and this template has none"
)
names = [value for _, value in wanted["user"]]
found = await self._rooms.resolve_bridge_users(bridge_id, names)
for param, value in wanted["user"]:
if value not in found:
raise ValueError(
f"param {param!r}: no user named {value!r} on the "
"room's messaging app"
)
async def resolve_defaults(
self, text: str, inputs: dict[str, Any] | None, *, reader: RoomReader
) -> dict[str, Any] | None:
"""Turn each list default into an input, for params sent no value.
The candidates are tried in order and the first one the server has
wins: a bridge by display name, an agent or room by name, ``$first``
for the default messaging app or the first agent or room by name. Only
rooms `reader` may name count (see ``RoomReader``). A
chain with no hit leaves the param as it was, for ``resolve_params``
to report. Runs before ``builtins_for``, because the bridge decides
which messaging app ``{$creator}`` is looked up on. A document that
does not parse is returned untouched; ``parse_template`` reports the
error. Chains of the Console's types are the Console's to resolve.
"""
try:
data = yaml.safe_load(text)
# A version 2 param's `if:` is the template engine's, not the spec's.
declared = {
name: ParamSpec.model_validate(
{k: v for k, v in spec.items() if k != "if"}
if isinstance(spec, dict)
else spec
)
for name, spec in ((data or {}).get("params") or {}).items()
}
except (yaml.YAMLError, ValidationError, AttributeError, TypeError):
return inputs
given = inputs if isinstance(inputs, dict) else {}
chains = {
name: spec
for name, spec in declared.items()
if isinstance(spec.default, list)
and spec.type in ENTITY_PARAM_TYPES
and given.get(name) is None
}
if not chains:
return inputs
filled = dict(given)
async with self._session_factory() as session:
names: dict[str, list[str]] = {}
for name, spec in chains.items():
if spec.type not in names:
names[spec.type] = await self._names_of(session, spec.type, reader)
have = names[spec.type]
for candidate in spec.default: # type: ignore[union-attr]
if candidate == FIRST and have:
filled[name] = have[0]
break
if candidate in have:
filled[name] = candidate
break
return filled if filled != given else inputs
async def _names_of(
self, session: AsyncSession, param_type: str, reader: RoomReader
) -> list[str]:
"""What the server has of one entity type, the ``$first`` one first."""
if param_type == "bridge":
active = [
b
for b in await self._bridge_store.get_all(session)
if b.status == "active"
]
return sorted(
(b.display_name for b in active),
key=lambda n: (
not any(b.display_name == n and b.is_default for b in active),
n,
),
)
if param_type == "agent":
return sorted(a.name for a in await self._agent_store.get_all(session))
return sorted(await self._readable_room_names(session, reader))
async def _readable_room_names(
self, session: AsyncSession, reader: RoomReader
) -> list[str]:
"""Names of the rooms `reader` may name in a `room` param."""
member_of = (
{
r.id
for r in await self._room_store.get_rooms_for_agent(
session, reader.agent_id
)
}
if reader.agent_id is not None
else set()
)
return [
r.name
for r in await self._room_store.get_all(session)
if r.id in member_of or can(reader.principal, "read", r)
]
async def builtins_for(
self,
*,
user_id: str,
name: str,
email: str,
text: str,
inputs: dict[str, Any] | None = None,
) -> dict[str, str]:
"""The server-injected ``{$...}`` variables for one create call.
``$creator`` is the name the creator goes by on the template's bridge,
the identity they have linked there, which is what ``users:``
resolution and channel invites understand. A bridged template that
uses ``{$creator}`` is refused without such a link rather than guessed
from the gateway account name, which is rarely a platform account.
Without a bridge there is nobody to invite, so the gateway name stands
in.
"""
creator = name
bridge_id = await self._peek_bridge_id(text, inputs)
if bridge_id is not None:
async with self._session_factory() as session:
claimed = await self._external_users.get_by_user(session, user_id)
bridge = await self._bridge_store.get(session, bridge_id)
claim = next((ext for ext in claimed if ext.bridge_id == bridge_id), None)
if claim is not None:
creator = claim.external_username
elif "{$creator}" in text:
app = (
bridge.display_name if bridge is not None else "this messaging app"
)
raise ValueError(
f"this template puts you in the room as {{$creator}}, but you "
f"have no linked account on {app}. Link your account under "
"Identities, then create the room again"
)
return {
"$creator": creator,
"$creator_email": email,
"$date": str(date.today()),
"$timestamp": str(int(time.time())),
}
async def _peek_bridge_id(
self, text: str, inputs: dict[str, Any] | None = None
) -> str | None:
"""The bridge the template will land on, read before interpolation.
A `bridge:` written as `{param}` is filled from `inputs` (or the
param's default) the way provisioning will fill it, so a template
that asks which app to use still finds the creator's account there.
Best-effort: an unparseable template, a bridge name that cannot be
resolved yet, or an unknown bridge all answer None; parse/provision
fails loudly later when it matters. A template naming no bridge lands
on the default one, same as provisioning."""
try:
data = yaml.safe_load(text)
except yaml.YAMLError:
return None
if not isinstance(data, dict):
return None
room = data.get("room")
if room is None:
rooms = data.get("rooms")
room = rooms[0] if isinstance(rooms, list) and rooms else None
if not isinstance(room, dict):
return None
bridge = room.get("bridge")
if isinstance(bridge, str) and PLACEHOLDER_RE.search(bridge):
raw_params = data.get("params")
try:
declared = {
k: ParamSpec.model_validate(v)
for k, v in (raw_params or {}).items()
}
values = resolve_params(declared, inputs)
except (ValueError, ValidationError, AttributeError):
return None
filled = interpolate(bridge, values)
if not isinstance(filled, str) or PLACEHOLDER_RE.search(filled):
return None
bridge = filled
if bridge is not None and not isinstance(bridge, str):
return None
try:
return await self._resolve_bridge_id(bridge)
except ValueError:
return None
# ── Provision ───────────────────────────────────────────────────────────
async def provision(
self,
spec: RoomSpec,
*,
user_id: str,
is_admin: bool,
kickoff: str | None = None,
creator_name: str | None = None,
group_id: str | None = None,
origin: AgentOrigin | None = None,
template_name: str | None = None,
) -> ProvisionResult:
"""Create the room and everything the spec attaches to it.
``kickoff`` is posted once the room exists, by the platform on the
creator's behalf (see ``_send_kickoff``); ``creator_name`` is how the
message names them. ``group_id`` files the room under a group that
already exists (see ``provision_group``).
With ``origin`` an agent is creating the room: it is recorded in that
agent's run (see ``agent_runs``), and the kickoff carries the agent's
authority, not its owner's, with the run so far appended. The checks
that can refuse an agent's room have run before this is called.
``template_name`` is what the room's run is listed under.
"""
bridge_id = await self._resolve_bridge_id(spec.bridge)
if spec.users and bridge_id is None:
raise ValueError(
"Cannot attach users to a room with no bridge "
"(users live on a collaboration bridge)"
)
attached_ref_ids, inline_refs = await self._resolve_references(
spec.references, user_id=user_id, is_admin=is_admin
)
attached_package_ids = await self._resolve_packages(
spec.packages, user_id=user_id, is_admin=is_admin
)
config = RoomCreateConfig(
name=spec.name,
description=spec.description,
instructions=spec.instructions,
channel_type=cast(ChannelType, spec.channel_type),
agent_names=spec.agents or None,
user_names=spec.users or None,
bridge_id=bridge_id,
group_id=group_id,
created_by=user_id,
from_template=True,
created_by_agent_id=origin.agent_id if origin else None,
parent_room_id=origin.parent_room_id if origin else None,
run_id=origin.run_id if origin else None,
kickoff_hash=kickoff_fingerprint(kickoff) if origin and kickoff else None,
template_name=template_name,
owner_id=user_id,
acting_user_id=user_id,
acting_is_admin=is_admin,
read_visibility=spec.read_visibility,
write_visibility=spec.write_visibility,
roles=spec.roles or None,
reference_ids=attached_ref_ids or None,
package_ids=attached_package_ids or None,
aliases=spec.aliases,
)
result = await self._rooms.create_room(config)
room_id = result.room.id
failures: list[dict[str, Any]] = list(result.failed_attachments)
created_ref_ids = await self._create_inline_references(
room_id, inline_refs, user_id=user_id, is_admin=is_admin, failures=failures
)
created_doc_ids = await self._create_inline_docs(
room_id, spec.docs, user_id=user_id, failures=failures
)
if kickoff:
# The room exists at this point. A kickoff failure is recorded on
# the result; raising here would report the room as not created.
try:
await self._send_kickoff(
result.room,
kickoff,
agent_names=spec.agents,
user_id=user_id,
user_name=creator_name,
origin=origin,
failures=failures,
)
except Exception as e: # noqa: BLE001 - reported on the result
failures.append({"kind": "kickoff", "id": "kickoff", "error": str(e)})
return ProvisionResult(
room_id=room_id,
room_name=result.room.name,
attached_reference_ids=attached_ref_ids,
attached_package_ids=attached_package_ids,
created_reference_ids=created_ref_ids,
created_document_ids=created_doc_ids,
role_names=[r.name for r in spec.roles],
failed_attachments=failures,
)
async def provision_group(
self,
spec: GroupSpec,
*,
user_id: str,
is_admin: bool,
creator_name: str | None = None,
origin: AgentOrigin | None = None,
template_name: str | None = None,
) -> GroupProvisionResult:
"""Provision a room group, its rooms, and the links between them.
Order: group row → each room with ``group_id`` (its own kickoff, if
any, posted as it is created) → links by name. A room that fails is
reported in ``errors`` and the rest still go ahead; nothing is rolled
back, so the caller sees exactly what exists.
Creating a group and filing rooms into it both need a workspace admin
(`require_group_filing`), so a non-admin is refused before anything
is made.
"""
require_group_filing(is_admin)
async with self._session_factory() as session:
group = await self._room_groups.create(
session,
name=spec.group.name,
description=spec.group.description,
color=spec.group.color,
parent_group_id=None,
)
await session.commit()
group_id = group.id
room_results: list[ProvisionResult] = []
errors: list[dict[str, Any]] = []
name_to_room_id: dict[str, str] = {}
for i, room_spec in enumerate(spec.rooms):
try:
result = await self.provision(
room_spec,
user_id=user_id,
is_admin=is_admin,
kickoff=room_spec.kickoff,
creator_name=creator_name,
origin=origin,
template_name=template_name,
group_id=group_id,
)
except Exception as e: # noqa: BLE001 - reported, not swallowed
errors.append(
{"room_index": i, "room_name": room_spec.name, "error": str(e)}
)
continue
room_results.append(result)
name_to_room_id[room_spec.name] = result.room_id
for link in spec.links:
from_id = name_to_room_id.get(link.from_)
to_id = name_to_room_id.get(link.to)
if from_id is None or to_id is None:
errors.append(
{
"kind": "link",
"from": link.from_,
"to": link.to,
"error": "one or both rooms were not created",
}
)
continue
try:
async with self._session_factory() as session:
await self._resources.attach_linked_room(
session,
source_room_id=from_id,
target_room_id=to_id,
label=link.label,
)
await session.commit()
except Exception as e: # noqa: BLE001 - reported, not swallowed
errors.append(
{"kind": "link", "from": link.from_, "to": link.to, "error": str(e)}
)
return GroupProvisionResult(
group_id=group_id,
group_name=spec.group.name,
rooms=room_results,
errors=errors,
)
async def check_bridges(self, parsed: ParsedTemplate) -> None:
"""Every messaging app the rooms name must exist, checked before
anything is created: a run that creates agents first would otherwise
find out only once they exist."""
specs = (
list(parsed.spec.rooms)
if isinstance(parsed.spec, GroupSpec)
else [parsed.spec]
)
for spec in specs:
bridge_id = await self._resolve_bridge_id(spec.bridge)
if spec.users and bridge_id is None:
raise ValueError(
f"Room {spec.name!r} names users ({', '.join(spec.users)}), and "
"it is on no messaging app: none is set up here. Leave "
"users out, or make them depend on a bridge."
)
async def _resolve_bridge_id(self, bridge_name: str | None) -> str | None:
if bridge_name is None:
async with self._session_factory() as session:
default = await self._bridge_store.get_default(session)
return default.id if default else None
async with self._session_factory() as session:
bridges = await self._bridge_store.get_all(session)
matches = [b for b in bridges if b.display_name == bridge_name]
if not matches:
raise ValueError(f"Unknown bridge: {bridge_name!r}")
if len(matches) > 1:
raise ValueError(
f"Ambiguous bridge name {bridge_name!r}: {len(matches)} bridges match"
)
return matches[0].id
async def _resolve_references(
self, entries: list[ExternalReferenceEntry], *, user_id: str, is_admin: bool
) -> tuple[list[str], list[InlineExternalReference]]:
"""Resolve attach-existing references up front (fail loud on missing /
ambiguous / no-access) and check every inline entry's type resolves for
this principal. Returns (attach-existing ids, inline entries)."""
attached_ids: list[str] = []
inline: list[InlineExternalReference] = []
async with self._session_factory() as session:
visible = await self._resources.list_references_for_user(session, user_id)
by_name: dict[str, list[str]] = {}
for ref in visible:
by_name.setdefault(ref.name, []).append(ref.id)
for entry in entries:
if isinstance(entry, ExistingReferenceById):
# Raises if missing or the user cannot read it.
await self._resources.get_reference_for_user(
session, entry.id, user_id, is_admin=is_admin
)
attached_ids.append(entry.id)
elif isinstance(entry, ExistingReferenceByName):
matches = by_name.get(entry.name, [])
if not matches:
raise ValueError(
f"No reference named {entry.name!r} is accessible"
)
if len(matches) > 1:
raise ValueError(
f"Ambiguous reference name {entry.name!r}: "
f"{len(matches)} matches; attach by 'id' instead"
)
attached_ids.append(matches[0])
else:
# Raises if the type does not exist or the user cannot
# read it — here, before create_room, so provisioning
# aborts with nothing created.
await self._resources.resolve_type_for_principal(
session, entry.type, user_id=user_id, is_admin=is_admin
)
inline.append(entry)
return attached_ids, inline
async def _resolve_packages(
self, entries: list[PackageEntry], *, user_id: str, is_admin: bool
) -> list[str]:
"""Resolve the packages to attach up front, failing loud on a missing,
ambiguous or unreadable one, so the room is not created without it.
Attaching needs read access, as it does by hand."""
attached_ids: list[str] = []
async with self._session_factory() as session:
visible = await self._resources.list_packages_for_user(session, user_id)
by_name: dict[str, list[str]] = {}
for pkg in visible:
by_name.setdefault(pkg.name, []).append(pkg.id)
for entry in entries:
if isinstance(entry, ExistingPackageById):
try:
await self._resources.get_package_for_user(
session, entry.id, user_id, is_admin=is_admin
)
except PermissionError as e:
raise PermissionError(
f"Cannot attach package {entry.id!r}: {e}"
) from e
attached_ids.append(entry.id)
else:
matches = by_name.get(entry.name, [])
if not matches:
raise ValueError(
f"No package named {entry.name!r} is accessible"
)
if len(matches) > 1:
raise ValueError(
f"Ambiguous package name {entry.name!r}: "
f"{len(matches)} matches; attach by 'id' instead"
)
attached_ids.append(matches[0])
# A package named twice (by id and by name, say) is attached once.
return list(dict.fromkeys(attached_ids))
async def _create_inline_references(
self,
room_id: str,
entries: list[InlineExternalReference],
*,
user_id: str,
is_admin: bool,
failures: list[dict[str, Any]],
) -> list[str]:
created: list[str] = []
async with self._session_factory() as session:
for entry in entries:
try:
ref = await self._resources.create_reference(
session,
owner_id=user_id,
is_admin=is_admin,
read_visibility=entry.read_visibility,
write_visibility=entry.write_visibility,
type=entry.type,
name=entry.name,
description=entry.description,
instructions=entry.instructions,
value=entry.value,
)
await self._resources.attach_reference_to_room(
session, room_id, ref.id, user_id=user_id, is_admin=is_admin
)
created.append(ref.id)
except Exception as e:
failures.append(
{"kind": "reference", "id": entry.name, "error": str(e)}
)
await session.commit()
return created
async def _create_inline_docs(
self,
room_id: str,
docs: list[DocSpec],
*,
user_id: str,
failures: list[dict[str, Any]],
) -> list[str]:
created: list[str] = []
async with self._session_factory() as session:
for doc in docs:
try:
created_doc = await self._resources.create_room_document_for_user(
session,
room_id=room_id,
owner_id=user_id,
name=doc.name,
description=doc.description,
instructions=doc.instructions,
content=doc.content,
)
created.append(created_doc.id)
except Exception as e:
failures.append(
{"kind": "document", "id": doc.name, "error": str(e)}
)
await session.commit()
return created
# ── Kickoff ───────────────────────────────────────────────────────────
async def _send_kickoff(
self,
room: Room,
text: str,
*,
agent_names: list[str],
user_id: str,
user_name: str | None,
failures: list[dict[str, Any]],
origin: AgentOrigin | None = None,
) -> None:
"""Post the kickoff into the room the template just created.
Switch posts it on the creator's behalf, so nobody is impersonated:
the message renders as the app, and each agent it mentions applies
its policy to the creator, for this one event. It goes out as a
one-line headline in the channel plus the text in that headline's
thread, so the channel keeps one line per kickoff.
Best-effort like references and docs: a kickoff that cannot be posted
is reported in ``failures``, not fatal. The agents are waited for
first, because a client drops events that land before its own join.
"""
def fail(error: str) -> None:
failures.append({"kind": "kickoff", "id": "kickoff", "error": error})
if self._client_lifecycle is None:
fail("kickoff posting is not configured here")
return
admins = self._client_lifecycle.get_by_type("admin", room.tenant_id)
admin = next((c for c in admins if isinstance(c, SystemActor)), None)
if admin is None:
fail("the platform has no client to post with")
return
late = await self._wait_for_kickoff_audience(
room.transport_room_id, admin, agent_names
)
if late:
fail("did not join the room in time to see the kickoff: " + ", ".join(late))
if "the platform" in late:
return
if origin is not None:
person = OnBehalfOf(user_id, origin.agent_name, origin.agent_id)
headline = f"Kickoff from {origin.headline_name}"
if origin.trace:
text = f"{text}\n\n{origin.trace}"
else:
person = OnBehalfOf(user_id, user_name or user_id)
headline = f"Template kickoff on behalf of {person.label}"
try:
root_id = await admin.send_platform_message(
room.transport_room_id, headline, on_behalf_of=person
)
if root_id is None:
fail("the platform could not post the kickoff")
return
event_id = await admin.send_platform_message(
room.transport_room_id,
text,
thread_root_id=root_id,
on_behalf_of=person,
reply_in_channel=True,
)
except Exception as e:
fail(str(e))
return
if event_id is None:
fail("the platform posted the kickoff headline but not its thread")
async def _wait_for_kickoff_audience(
self,
transport_room_id: str,
admin: SystemActor,
agent_names: list[str],
) -> list[str]:
"""Wait for the sender and the template's agents to be in the room.
Returns the names of those that were not joined within the timeout:
"the platform" for the sender itself, else the agent's name. An agent
with no running client is not waited for; it is not in the room to
miss anything.
"""
late: list[str] = []
if not await admin.wait_joined(transport_room_id, KICKOFF_JOIN_TIMEOUT):
late.append("the platform")
if not agent_names or self._client_lifecycle is None:
return late
async with self._session_factory() as session:
agents = await self._agent_store.get_by_names(session, agent_names)
for agent in agents:
client = self._client_lifecycle.get_by_agent_id(agent.id)
if client is None:
continue
try:
joined = await client.wait_joined(
transport_room_id, KICKOFF_JOIN_TIMEOUT
)
except RuntimeError:
# Not connected: it is not receiving anything either way.
continue
if not joined:
late.append(agent.name)
return late
# ── Export ────────────────────────────────────────────────────────────
async def export(
self,
room_id: str,
*,
agents: bool = True,
users: bool = True,
references: bool = True,
packages: bool = True,
docs: bool = True,
roles: bool = True,
) -> str:
"""Read a live room back into the import surface and dump it to YAML.
References and packages export as attach-by-``id``. Only room-scoped
documents are exported (as inline docs): they are the only docs the
import surface can recreate. A package's own references and documents
are not exported, since attaching the package brings them. Each
section can be dropped via its toggle.
"""
async with self._session_factory() as session:
room = await self._room_store.get(session, room_id)
if room is None:
raise ValueError(f"Room not found: {room_id}")
bridge_display_name: str | None = None
if room.bridge_id:
bridge = await self._bridge_store.get(session, room.bridge_id)
if bridge:
bridge_display_name = bridge.display_name
name = room.name
if bridge_display_name and name.startswith(f"{bridge_display_name}: "):
name = name[len(bridge_display_name) + 2 :]
data: dict[str, Any] = {
"name": name,
"description": room.description,
}
if room.instructions:
data["instructions"] = room.instructions
if bridge_display_name:
data["bridge"] = bridge_display_name
data["channel_type"] = room.channel_type
data["read_visibility"] = room.read_visibility
data["write_visibility"] = room.write_visibility
if agents:
agent_ids = await self._room_store.get_agent_ids(session, room.id)
id_to_name: dict[str, str] = {}
for aid in agent_ids:
agent = await self._agent_store.get(session, aid)
if agent is not None:
id_to_name[aid] = agent.name
if id_to_name:
data["agents"] = sorted(id_to_name.values())
alias_map = await self._room_store.list_aliases(session, room.id)
if alias_map:
data["aliases"] = {
id_to_name[aid]: alias
for aid, alias in alias_map.items()
if aid in id_to_name
}
if users and room.bridge_id:
client_ids = await self._room_store.get_client_ids(session, room.id)
ext_users = await self._external_users.get_by_bridge(
session, room.bridge_id
)
client_to_name = {
eu.client_id: eu.external_username for eu in ext_users
}
user_names = sorted(
client_to_name[cid] for cid in client_ids if cid in client_to_name
)
if user_names:
data["users"] = user_names
if roles:
role_rows = await self._room_roles.list_roles(session, room.id)
if role_rows:
data["roles"] = [
{
"name": r.name,
"instructions": r.instructions,
"exclusive": r.exclusive,
}
for r in role_rows
]
if references:
refs = await self._resources.list_room_references(session, room.id)
if refs:
data["references"] = [{"id": r.id} for r in refs]
if packages:
pkgs = await self._resources.list_room_packages(session, room.id)
if pkgs:
data["packages"] = [{"id": p.id} for p in pkgs]
if docs:
room_docs = await self._resources.list_room_documents(session, room.id)
scoped = [d for d in room_docs if d.room_id == room.id]
if scoped:
data["docs"] = [
{
"name": d.name,
"description": d.description,
"instructions": d.instructions,
"content": d.content,
}
for d in scoped
]
return cast(
str,
yaml.dump(
{"room": data},
Dumper=_SpecDumper,
sort_keys=False,
allow_unicode=True,
default_flow_style=False,
),
)