Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
feat(agent): per-principal reference types over the agent protocol
raullopez-sandboxe30413bfafbc
diff --git a/core/switch_core/bridges/agent/operations/definitions.py b/core/switch_core/bridges/agent/operations/definitions.pyindex 7930bc4d4..3119936d0 100644--- a/core/switch_core/bridges/agent/operations/definitions.py+++ b/core/switch_core/bridges/agent/operations/definitions.py@@ -356,7 +356,10 @@ async def list_references() -> dict[str, Any]:External references carry their `value` inline (URLs / IDs); fetch theunderlying content using your own tools as described in- `reference_types[<type>].instructions`.+ `reference_types[<type>].instructions`. An entry may instead carry+ `"missing": true`, meaning that type could not be resolved on this+ instance: treat its instructions as absent and say so rather than+ guessing at how to use the reference.Internal documents are advertised by id + description + instructionsonly; call `load_internal_documents` to fetch their content.@@ -1202,18 +1205,22 @@ async def release_role() -> dict[str, Any]:@operationasync def list_reference_types() -> list[dict[str, Any]]:- """List the Reference sub-types this Switch instance supports.+ """List the Reference types you can use on this Switch instance.- Call this before `create_reference` to discover which `type` values- are valid and what shape the `value` payload must have.+ The set is open and per-caller: it is the types built into Switch plus+ the user-defined ones your owner can read, so another agent may see a+ different list. Call this before `create_reference` and pick a `type`+ from what it returns for you.Returns:- List of `{type, display_name, instructions, value_schema}`.- `value_schema` is the JSON Schema for the per-type value- payload — use it to build the `value` dict for `create_reference`.+ List of `{type, display_name, instructions, value_schema,+ value_hint, origin}`. `value_schema` is the JSON Schema for the+ `value` dict `create_reference` expects, `value_hint` says what the+ URLs in it should point at, and `origin` is `"builtin"` for a type+ that ships with Switch or `"user"` for one someone defined here."""protocol = get_protocol()- return protocol.list_reference_types()+ return await protocol.list_reference_types(get_agent_id())@operation@@ -1234,10 +1241,10 @@ async def create_reference(and access it.Args:- type: Reference type. Supported values: "google_drive",- "confluence", "github", "jira". Each type expects a specific- `value` shape. Call `list_reference_types` for the authoritative- list and each type's `value_schema`.+ type: Reference type — a slug `list_reference_types` returned for+ YOU. The set is open (users define their own types) and+ per-caller, so call `list_reference_types` first rather than+ guessing a slug; an unknown or unreadable one is rejected.name: Short display name.description: One-or-two sentence summary of what this referencepoints at, shown in listings.@@ -1245,10 +1252,10 @@ async def create_reference(reference — what's in it, when to consult it, any caveats.This is the field agents read when the reference shows up intheir room context.- value: Type-specific payload. For every built-in type today the- shape is `{"urls": ["https://...", ...]}` — `min_length=1`. For- "jira" the URLs point at projects, issues, or boards (e.g.- `https://your-org.atlassian.net/browse/PROJ-123`).+ value: `{"urls": ["https://...", ...]}` — the shape every type+ shares, with at least one URL. What those URLs should point at+ is the type's `value_hint` from `list_reference_types` (for+ "jira", say, projects, issues, or boards).read_visibility: "private" (default — only you can read/attach it) or"public" (anyone can read/attach).write_visibility: "private" (default — only you can edit it) ordiff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.pyindex d079eb3a0..476e47b19 100644--- a/core/switch_core/bridges/agent/protocol/service.py+++ b/core/switch_core/bridges/agent/protocol/service.py@@ -2660,15 +2660,28 @@ class ProtocolService:await self.agent_session_store.touch_heartbeat(session, agent_id, room_id)await session.commit()- def list_reference_types(self) -> list[dict[str, Any]]:- """Enumerate the Reference sub-types registered on this Switch- instance. Each entry carries `type`, `display_name`,- `instructions`, and `value_schema` (JSON Schema for the- per-type value payload). Used by agents preparing a- `create_reference` call."""- from switch_core.bridges.resource.registry import REFERENCE_TYPES-- return [spec.to_public_dict() for spec in REFERENCE_TYPES.values()]+ async def list_reference_types(self, agent_id: str) -> list[dict[str, Any]]:+ """Enumerate the Reference types the calling agent may pick from.++ The set is per-caller: every built-in, plus every user-defined type+ the agent's owner can read. Each entry carries `type`,+ `display_name`, `instructions`, `value_schema`, `value_hint` and+ `origin`. Used by agents preparing a `create_reference` call.++ An ownerless agent resolves as an anonymous principal and sees the+ built-ins plus the public types; reading the list needs no owner.+ """+ async with self.session_factory() as session:+ _agent, owner_id, is_admin = await self._resolve_acting_identity(+ session, agent_id+ )+ views = await self.resource_service.list_reference_types_for_principal(+ session, user_id=owner_id, is_admin=is_admin+ )+ return [+ view.spec.to_public_dict(origin="builtin" if view.is_builtin else "user")+ for view in views+ ]async def create_reference(self,diff --git a/core/tests/switch_core/bridges/agent/protocol/test_reference_type_parity.py b/core/tests/switch_core/bridges/agent/protocol/test_reference_type_parity.pynew file mode 100644index 000000000..8f47b683a--- /dev/null+++ b/core/tests/switch_core/bridges/agent/protocol/test_reference_type_parity.py@@ -0,0 +1,235 @@+"""`list_reference_types` resolves per-principal in two independent code paths+— the agent protocol op (the agent's owner) and the gateway route (the signed-in+user). They are separate implementations over the same service, so this file+pins them to the same answer for the same principal: a filter added to one and+not the other is a drift bug that no other test would catch.++`ProtocolService.__init__` takes 17 required collaborators, so the service is+built with `object.__new__` and the three attributes this method touches, per+`test_agent_detail_mcp_tools.py`. `_resolve_acting_identity` loads the owner+with `session.get(User, ...)` on the live session rather than through+`user_store`, so no `user_store` is needed here.+"""++from __future__ import annotations++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.agent.protocol.service import ProtocolService+from switch_core.bridges.resource.registry import BUILTIN_REFERENCE_TYPES+from switch_core.bridges.resource.service import ResourceService+from switch_core.db.models import Agent, ApiKey, Client, User+from switch_core.db.stores.agent_store import AgentStore+from switch_core.db.stores.document_store import DocumentStore+from switch_core.db.stores.package_store import PackageStore+from switch_core.db.stores.reference_store import ReferenceStore+from switch_core.db.stores.reference_type_store import ReferenceTypeStore+from switch_core.db.stores.room_link_store import RoomLinkStore+from switch_core.db.stores.user_store import UserStore+from switch_core.gateway.references import list_reference_types as route_list_types++_USER_STORE = UserStore()+++def _resource_service(+ session_factory: async_sessionmaker[AsyncSession],+) -> ResourceService:+ return ResourceService(+ reference_store=ReferenceStore(),+ reference_type_store=ReferenceTypeStore(),+ document_store=DocumentStore(),+ package_store=PackageStore(),+ room_link_store=RoomLinkStore(),+ session_factory=session_factory,+ )+++def _protocol_service(+ session_factory: async_sessionmaker[AsyncSession],+ resource_service: ResourceService,+) -> ProtocolService:+ svc = object.__new__(ProtocolService)+ svc.session_factory = session_factory # type: ignore[attr-defined]+ svc.agent_store = AgentStore() # type: ignore[attr-defined]+ svc.resource_service = resource_service # type: ignore[attr-defined]+ return svc+++async def _make_user(session: AsyncSession, name: str, role: str = "user") -> User:+ user = User(name=name, email=f"{name}@example.invalid", role=role)+ session.add(user)+ await session.flush()+ return user+++async def _make_agent(+ session: AsyncSession, name: str, *, owner_id: str | None, api_key_user_id: str+) -> Agent:+ # `agents.owner_id` is nullable but `api_keys.user_id` is not, so an+ # ownerless agent still has a key belonging to whoever registered it.+ api_key = ApiKey(+ user_id=api_key_user_id,+ key_hash=f"hash-{name}",+ encrypted_key="enc",+ label=name,+ type="agent",+ )+ client = Client(+ matrix_user_id=f"@{name}:example.invalid",+ display_name=name,+ type="agent",+ password="x",+ )+ session.add_all([api_key, client])+ await session.flush()+ agent = Agent(+ name=name,+ description=f"{name} desc",+ agent_type="session_addressable",+ connector_type="Claude Code",+ integration_profile={"connection_model": "session_passive"},+ client_id=client.id,+ api_key_id=api_key.id,+ owner_id=owner_id,+ )+ session.add(agent)+ await session.flush()+ return agent+++async def _make_type(+ session: AsyncSession,+ service: ResourceService,+ slug: str,+ *,+ owner_id: str,+ read_visibility: str,+) -> None:+ await service.create_reference_type(+ session,+ owner_id=owner_id,+ type=slug,+ display_name=slug.replace("_", " ").title(),+ instructions=f"Use the {slug} links as {slug} material.",+ value_hint=f"Paste {slug} links.",+ read_visibility=read_visibility,+ write_visibility="private",+ )+++async def _seed(+ session: AsyncSession, service: ResourceService+) -> tuple[User, User, Agent]:+ """alice owns an agent and a private type; bob owns one of each visibility."""+ alice = await _make_user(session, "alice")+ bob = await _make_user(session, "bob")+ await _make_type(+ session, service, "alice_private", owner_id=alice.id, read_visibility="private"+ )+ await _make_type(+ session, service, "bob_private", owner_id=bob.id, read_visibility="private"+ )+ await _make_type(+ session, service, "bob_public", owner_id=bob.id, read_visibility="public"+ )+ agent = await _make_agent(+ session, "alice-agent", owner_id=alice.id, api_key_user_id=alice.id+ )+ return alice, bob, agent+++async def _slugs_from_route(+ session: AsyncSession, service: ResourceService, user: User+) -> set[str]:+ listed = await route_list_types(session, service, _USER_STORE, user)+ return {info.type for info in listed}+++class TestAgentAndGatewayAgree:+ async def test_same_principal_sees_the_same_slugs(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service = _resource_service(session_factory)+ svc = _protocol_service(session_factory, service)+ async with session_factory() as session:+ alice, _bob, agent = await _seed(session, service)+ await session.commit()+ alice_id, agent_id = alice.id, agent.id++ agent_slugs = {e["type"] for e in await svc.list_reference_types(agent_id)}+ async with session_factory() as session:+ alice = await _USER_STORE.get(session, alice_id) # type: ignore[assignment]+ route_slugs = await _slugs_from_route(session, service, alice)++ assert agent_slugs == route_slugs+ assert agent_slugs == set(BUILTIN_REFERENCE_TYPES) | {+ "alice_private",+ "bob_public",+ }++ async def test_admin_owner_sees_every_type_on_both_paths(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service = _resource_service(session_factory)+ svc = _protocol_service(session_factory, service)+ async with session_factory() as session:+ _alice, _bob, _agent = await _seed(session, service)+ root = await _make_user(session, "root", role="admin")+ agent = await _make_agent(+ session, "root-agent", owner_id=root.id, api_key_user_id=root.id+ )+ await session.commit()+ root_id, agent_id = root.id, agent.id++ agent_slugs = {e["type"] for e in await svc.list_reference_types(agent_id)}+ async with session_factory() as session:+ root = await _USER_STORE.get(session, root_id) # type: ignore[assignment]+ route_slugs = await _slugs_from_route(session, service, root)++ assert agent_slugs == route_slugs+ assert {"alice_private", "bob_private", "bob_public"} <= agent_slugs+++class TestOwnerlessAgent:+ """A read tool must not require an owner: `create_reference` refuses an+ ownerless agent, `list_reference_types` resolves it as an anonymous+ principal and returns the built-ins plus the public types.+ """++ async def test_sees_builtins_and_public_types_only(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service = _resource_service(session_factory)+ svc = _protocol_service(session_factory, service)+ async with session_factory() as session:+ _alice, bob, _agent = await _seed(session, service)+ agent = await _make_agent(+ session, "ownerless", owner_id=None, api_key_user_id=bob.id+ )+ await session.commit()+ agent_id = agent.id++ slugs = {e["type"] for e in await svc.list_reference_types(agent_id)}+ assert slugs == set(BUILTIN_REFERENCE_TYPES) | {"bob_public"}+++class TestEntryShape:+ async def test_entries_carry_origin_and_value_hint(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service = _resource_service(session_factory)+ svc = _protocol_service(session_factory, service)+ async with session_factory() as session:+ _alice, _bob, agent = await _seed(session, service)+ await session.commit()+ agent_id = agent.id++ entries = {e["type"]: e for e in await svc.list_reference_types(agent_id)}+ custom = entries["alice_private"]+ assert custom["origin"] == "user"+ assert custom["display_name"] == "Alice Private"+ assert custom["value_hint"] == "Paste alice_private links."+ assert custom["value_schema"]["properties"]["urls"]["type"] == "array"+ assert entries["github"]["origin"] == "builtin"+ # The owner never reaches an agent: only the gateway picker discloses it.+ assert "owner_id" not in custom