Skip to content

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

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.py
index 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 the
underlying 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 + instructions
only; call `load_internal_documents` to fetch their content.
@@ -1202,18 +1205,22 @@ async def release_role() -> dict[str, Any]:
@operation
async 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 reference
points 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 in
their 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) or
diff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.py
index 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.py
new file mode 100644
index 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