Skip to content

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

fix(resources): address review findings for user-defined reference types

raullopez-sandboxcb5089002161
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f8438974f..b16b11d21 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,36 @@ version of their own to them without also giving them a release of their own.
### [Unreleased]
+#### Added
+- **User-defined external reference types.** Reference types are no longer a
+ closed set of four. Any signed-in user can define one — slug, display name,
+ agent-facing instructions, value hint and a read/write visibility pair,
+ exactly like a Reference — from the new **Reference types** tab under
+ Resources, or over `POST /references/reference-types`. The four built-ins
+ (Google Drive, Confluence, GitHub, Jira) stay in code, cannot be edited or
+ deleted, and win any slug collision. Agents see the types their owner can
+ read, via `list_reference_types`; each entry now also carries `value_hint`
+ and `origin` (`builtin` or `user`). A type's visibility gates who may *pick*
+ it, never delivery of its instructions for a reference already attached to a
+ room — the attachment is the grant.
+
+#### Changed
+- **A reference value must now carry at least one URL.** An empty `urls` list
+ was already rejected, but an absent `urls` key silently validated to an empty
+ list and was stored. It is now a 400. Existing rows still read fine; the
+ failure appears the first time someone saves one — including a no-op save
+ from the reference detail page. Find them before upgrading and give each a
+ real URL:
+
+ ```sql
+ SELECT id, type FROM "references"
+ WHERE value->'urls' = '[]'::jsonb OR NOT (value ? 'urls');
+ ```
+- **`GET /references/reference-types` now requires a session** and returns
+ 401 without one. It was the last unauthenticated route on the references
+ router; the set it returns is per-caller now, so it cannot be answered
+ anonymously.
+
### [0.21.1] - 2026-09-01
#### Fixed
diff --git a/core/switch_core/bridges/resource/service.py b/core/switch_core/bridges/resource/service.py
index 1ca408784..d5f5bac38 100644
--- a/core/switch_core/bridges/resource/service.py
+++ b/core/switch_core/bridges/resource/service.py
@@ -140,9 +140,9 @@ class ResourceService:
"""Resolve ``slugs`` to their specs, built-in winning any collision.
Unresolvable slugs are simply absent from the result; the two public
- resolvers below differ in what they do about that. No visibility filter
- — see decision 3: a reference already in a room carries its type's
- metadata to every agent there.
+ resolvers below differ in what they do about that. No visibility filter:
+ a reference already attached to a room carries its type's metadata to
+ every agent there — the attachment is the grant.
"""
resolved: dict[str, tuple[ReferenceTypeSpec, Literal["builtin", "user"]]] = {}
for row in await self._reference_types.get_many(session, sorted(slugs)):
@@ -336,12 +336,17 @@ class ResourceService:
if reference_type is None:
raise ValueError(f"Reference type not found: {type_}")
require(Principal(user_id, is_admin), "delete", reference_type)
- in_use = await self._reference_types.count_references_of_type(session, type_)
- if in_use:
- raise ReferenceTypeInUseError(
- f"Reference type '{type_}' is used by {in_use} reference(s) "
- "and cannot be deleted"
+ if not is_builtin_type(type_):
+ # A shadowed row resolves for nobody — references of the slug are
+ # served by the built-in — so counting them would strand the row.
+ in_use = await self._reference_types.count_references_of_type(
+ session, type_
)
+ if in_use:
+ raise ReferenceTypeInUseError(
+ f"Reference type '{type_}' is used by {in_use} reference(s) "
+ "and cannot be deleted"
+ )
await self._reference_types.delete(session, type_)
async def log_builtin_shadowing(self, session: AsyncSession) -> None:
diff --git a/core/tests/integration/test_reference_types_e2e.py b/core/tests/integration/test_reference_types_e2e.py
index 4e35ec42d..ac6f574c2 100644
--- a/core/tests/integration/test_reference_types_e2e.py
+++ b/core/tests/integration/test_reference_types_e2e.py
@@ -5,8 +5,7 @@ a Reference of it, attaches the Reference to a real room, and an agent runs the
real `connect_to_room` operation. The assertions read the on-connect payload the
agent actually receives, so nothing is inferred from service-level state.
-Three properties are pinned here, each stated as a decision in the
-implementation plan:
+Three properties are pinned here:
* a user-defined type reaches the connected agent with its own `instructions`
and `origin: "user"`;
@@ -142,7 +141,7 @@ async def test_a_user_defined_type_reaches_the_connected_agent(
async def test_a_type_private_to_another_user_still_reaches_the_agent(
harness: Harness,
) -> None:
- """Decision 3: `read_visibility` gates picking and enumerating a type, never
+ """`read_visibility` gates picking and enumerating a type, never
delivery of its metadata for a Reference already attached to a room.
The room attachment is the grant. Do not "fix" this into a visibility filter:
@@ -203,7 +202,7 @@ async def test_a_type_private_to_another_user_still_reaches_the_agent(
async def test_an_unresolvable_type_is_delivered_flagged_missing(
harness: Harness, session_env: SessionEnv
) -> None:
- """Decision 7: `references.type` carries no foreign key and cannot carry one
+ """`references.type` carries no foreign key and cannot carry one
(built-ins are not rows), so a slug registered nowhere is a reachable state —
a built-in retired in a later release, or a row removed by direct SQL.
diff --git a/core/tests/switch_core/bridges/resource/test_reference_types_service.py b/core/tests/switch_core/bridges/resource/test_reference_types_service.py
index 92e6995cf..62ad89d3d 100644
--- a/core/tests/switch_core/bridges/resource/test_reference_types_service.py
+++ b/core/tests/switch_core/bridges/resource/test_reference_types_service.py
@@ -55,9 +55,9 @@ async def users(
async def _shadow_github(session: AsyncSession, owner_id: str) -> ReferenceType:
"""Write a row whose slug a built-in already owns.
- ``create_reference_type`` refuses this, so it can only arise the way
- decision 5 describes: a future release adding a built-in over a slug a user
- already holds. The store is the honest way to reach that state.
+ ``create_reference_type`` refuses this, so it can only arise one way: a
+ future release adding a built-in over a slug a user already holds. The store
+ is the honest way to reach that state.
"""
return await ReferenceTypeStore().create(
session,
@@ -137,6 +137,20 @@ class TestResolution:
) -> None:
async with session_factory() as session:
await _shadow_github(session, users["alice"])
+ # A reference of the *built-in* github resolves against the
+ # built-in, so it must not block deleting the shadowed row.
+ await service.create_reference(
+ session,
+ owner_id=users["bob"],
+ is_admin=False,
+ read_visibility="private",
+ write_visibility="private",
+ type="github",
+ name="A repo",
+ description="",
+ instructions="",
+ value={"urls": ["https://example.invalid/org/repo"]},
+ )
await session.commit()
async with session_factory() as session:
@@ -349,7 +363,7 @@ class TestPrivateTypeStillReachesAgents:
session_factory: async_sessionmaker[AsyncSession],
users: dict[str, str],
) -> None:
- """Decision 3: ``read_visibility`` gates who may *pick* and *enumerate* a
+ """``read_visibility`` gates who may *pick* and *enumerate* a
type, never delivery of its metadata for a reference already attached to
a room. The attachment is the grant. Withholding the instructions would
ship an agent a reference it cannot act on while looking healthy — the
@@ -410,16 +424,15 @@ class TestCreateReferenceType:
session_factory: async_sessionmaker[AsyncSession],
users: dict[str, str],
) -> None:
- """Decision 4: any authenticated user may create a type with the full
- read/write visibility pair, exactly like a Reference. There is no admin
- gate on ``read_visibility="public"``; the only pair rule is the existing
+ """Any authenticated user may create a type with the full read/write
+ visibility pair, exactly like a Reference. There is no admin gate on
+ ``read_visibility="public"``; the only pair rule is the existing
write-implies-read invariant in ``authz.validate_visibility_pair``.
The mitigation for user-authored, agent-facing instructions is
disclosure (owner and built-in marker travel on the picker payload), not
- restriction. An admin gate is the opt-in tightening named under Risks in
- the implementation plan — reversing this behaviour means changing this
- test, deliberately.
+ restriction. Adding an admin gate is a deliberate tightening — it means
+ changing this test, not just the service.
"""
async with session_factory() as session:
created = await service.create_reference_type(
diff --git a/gateway/src/pages/resources/ReferenceDetailPage.tsx b/gateway/src/pages/resources/ReferenceDetailPage.tsx
index 43a8cd1a2..e43d4135d 100644
--- a/gateway/src/pages/resources/ReferenceDetailPage.tsx
+++ b/gateway/src/pages/resources/ReferenceDetailPage.tsx
@@ -231,9 +231,11 @@ function EditFieldsSection({
}
};
- // Keyed on the value's shape, not on whether the type resolves: every type
- // shares the URL shape, and the type may simply not be visible to this user.
- const isUrlsValue = Array.isArray(value.urls);
+ // Keyed on the stored value's shape, not on whether the type resolves: every
+ // type shares the URL shape, and the type may simply not be visible to this
+ // user. Reading the stored bag rather than the edit state keeps the choice of
+ // editor fixed for the lifetime of an edit.
+ const isUrlsValue = Array.isArray(ref_.value.urls);
return (
<Stack spacing={2}>