Skip to content

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

Switch Trust: name the blocked agent, notify redacted senders, fix guardrails headers

Timo Bozsolik-Torrescddbfb5012a9
diff --git a/core/switch_core/bridges/agent/protocol/agent_core.py b/core/switch_core/bridges/agent/protocol/agent_core.py
index ee5823e39..c05876bcf 100644
--- a/core/switch_core/bridges/agent/protocol/agent_core.py
+++ b/core/switch_core/bridges/agent/protocol/agent_core.py
@@ -1227,7 +1227,11 @@ class AgentCore:
)
async def _enforce_trust(
- self, room: RoomDescriptor, content: str, thread_root_id: str | None
+ self,
+ room: RoomDescriptor,
+ content: str,
+ thread_root_id: str | None,
+ agent_name: str,
) -> str:
"""Check agent-authored content against Switch Trust before it is
sent. Returns the content to actually send — unchanged, redacted, or
@@ -1235,10 +1239,13 @@ class AgentCore:
`GuardrailBlockedError` on a BLOCKED verdict, having already posted a
notice in the room in place of the real content."""
check = await check_message(
- self.trust_client, role="assistant", content=content
+ self.trust_client,
+ role="assistant",
+ content=content,
+ room_id=room.id,
)
if check.blocked:
- await self._post_trust_blocked_notice(room, thread_root_id)
+ await self._post_trust_blocked_notice(room, thread_root_id, agent_name)
raise GuardrailBlockedError(check)
if check.redacted_content is not None:
content = check.redacted_content
@@ -1248,7 +1255,7 @@ class AgentCore:
return content
async def _post_trust_blocked_notice(
- self, room: RoomDescriptor, thread_root_id: str | None
+ self, room: RoomDescriptor, thread_root_id: str | None, agent_name: str
) -> None:
"""Tell the room a response was blocked, in place of sending it."""
admin = next(
@@ -1264,7 +1271,8 @@ class AgentCore:
try:
await admin.send_admin(
room.transport_room_id,
- "🚫 A response was blocked by Switch Trust and was not sent.",
+ f"🚫 A response from @{agent_name} was blocked by Switch Trust "
+ "and was not sent.",
message_type=AdminMessageType.TRUST_BLOCKED,
thread_root_id=thread_root_id,
)
@@ -1336,7 +1344,9 @@ class AgentCore:
thread_root_id = await self._resolve_thread_root(
client, room.transport_room_id, thread_id
)
- content = await self._enforce_trust(room, content, thread_root_id)
+ content = await self._enforce_trust(
+ room, content, thread_root_id, client.agent.name
+ )
event_id = await client.send_message(
room.transport_room_id,
content,
@@ -1805,7 +1815,7 @@ class AgentCore:
client = self.client_lifecycle.get_by_agent_id(agent_id)
if client is None:
raise ValueError("Agent client not running")
- detail = await self._enforce_trust(room, detail, None)
+ detail = await self._enforce_trust(room, detail, None, client.agent.name)
await client.send_message(
room.transport_room_id, f"*{detail}*", format="markdown", metered=True
)
@@ -2534,7 +2544,7 @@ class AgentCore:
client = self.client_lifecycle.get_by_agent_id(agent_id)
if client and client.transport:
- outcome = await self._enforce_trust(room, outcome, None)
+ outcome = await self._enforce_trust(room, outcome, None, client.agent.name)
await client.send_event(
room.transport_room_id,
"com.switch.task.finalise",
diff --git a/core/switch_core/bridges/collaboration/collaboration_core.py b/core/switch_core/bridges/collaboration/collaboration_core.py
index ed45e771e..bf7c68028 100644
--- a/core/switch_core/bridges/collaboration/collaboration_core.py
+++ b/core/switch_core/bridges/collaboration/collaboration_core.py
@@ -88,6 +88,7 @@ from switch_core.trust.client import (
TrustClient,
check_message,
trust_annotation,
+ trust_redaction_notice,
)
if TYPE_CHECKING:
@@ -954,7 +955,10 @@ class CollaborationCore:
if not msg.attachments:
check = await check_message(
- self._trust_client, role="user", content=content
+ self._trust_client,
+ role="user",
+ content=content,
+ room_id=room_id,
)
if check.blocked:
logger.warning(
@@ -974,6 +978,14 @@ class CollaborationCore:
return
if check.redacted_content is not None:
content = check.redacted_content
+ redaction_notice = trust_redaction_notice(check)
+ if redaction_notice is not None:
+ await self._adapter.admin_message(
+ msg.channel_id,
+ redaction_notice,
+ msg.root_id or msg.message_ref,
+ message_type=AdminMessageType.TRUST_REDACTED.value,
+ )
annotation = trust_annotation(check)
if annotation is not None:
content = f"{content}\n\n{annotation}"
diff --git a/core/switch_core/clients/admin_messages.py b/core/switch_core/clients/admin_messages.py
index 9bfe6c880..34ba85d61 100644
--- a/core/switch_core/clients/admin_messages.py
+++ b/core/switch_core/clients/admin_messages.py
@@ -107,6 +107,7 @@ class AdminMessageType(StrEnum):
NO_AGENTS = "no_agents"
RUN_NOTICE = "run_notice"
TRUST_BLOCKED = "trust_blocked"
+ TRUST_REDACTED = "trust_redacted"
def admin_extra_content(message_type: AdminMessageType | None) -> dict[str, object]:
diff --git a/core/switch_core/config.py b/core/switch_core/config.py
index c45238276..ed9b0e983 100644
--- a/core/switch_core/config.py
+++ b/core/switch_core/config.py
@@ -451,7 +451,7 @@ class SwitchConfig(BaseSettings):
# https://github.com/sandbox-quantum/hoot/pull/2397) is appended, the same
# convention `otlp_endpoint`/`telemetry_endpoint` follow. Defaults to the
# company API; override for a different deployment or a local stack.
- switch_trust_endpoint: str = "https://api.flintai.dev"
+ switch_trust_endpoint: str = "https://api.switchagents.ai"
# Authenticates with Switch Trust and names which policy to run. Both
# unset (the default) is what turns the whole feature off — see
diff --git a/core/switch_core/trust/client.py b/core/switch_core/trust/client.py
index a4f238ee9..43fdaefd8 100644
--- a/core/switch_core/trust/client.py
+++ b/core/switch_core/trust/client.py
@@ -12,6 +12,7 @@ ask whether the feature is on — the same shape as `telemetry/sink.py`'s
from __future__ import annotations
import logging
+import uuid
from dataclasses import dataclass
from typing import Any, Literal, Protocol
@@ -21,6 +22,14 @@ logger = logging.getLogger(__name__)
Role = Literal["user", "assistant"]
+# Every check is reported under one constant agent identity: Switch has no
+# single "agent" to attribute a check to (a room can hold several, and a
+# human-authored message has none at all), so this collapses all of Switch's
+# traffic onto one Switch Trust agent rather than inventing a per-sender
+# identity Switch Trust has no use for. `x-agent-session-id` (the room) and
+# `x-agent-turn-id` (one per check) carry the per-call distinction instead.
+_AGENT_NAME = "Switch Rooms"
+
# The outcome a check settles on. "errored" covers both what the wire protocol
# calls GUARDRAIL_RESULT_OUTCOME_ERRORED (a detector itself failed, but the
# engine still answered) and what `check_message` reports when the HTTP call
@@ -97,13 +106,17 @@ class TrustCheckResult:
class TrustClient(Protocol):
- async def check(self, *, role: Role, content: str) -> TrustCheckResult: ...
+ async def check(
+ self, *, role: Role, content: str, room_id: str
+ ) -> TrustCheckResult: ...
class NullTrustClient:
"""Off: every message is allowed, and no request is made."""
- async def check(self, *, role: Role, content: str) -> TrustCheckResult:
+ async def check(
+ self, *, role: Role, content: str, room_id: str
+ ) -> TrustCheckResult:
return TrustCheckResult(outcome="ok", policy_id=None, policy_name=None)
@@ -130,17 +143,29 @@ class HttpTrustClient:
"Content-Type": "application/json",
"x-guardrails-policy-id": policy_id,
"x-flintai-api-key": api_key,
+ "x-agent-name": _AGENT_NAME,
}
self._timeout_seconds = timeout_seconds
self._client = client
- async def check(self, *, role: Role, content: str) -> TrustCheckResult:
+ async def check(
+ self, *, role: Role, content: str, room_id: str
+ ) -> TrustCheckResult:
payload = {"messages": [{"role": role, "content": content}]}
+ headers = {
+ **self._headers,
+ "x-agent-session-id": room_id,
+ # One per check, not per logical "turn" a host might recognise —
+ # Switch has no such id to hand it (see `TrustClient.check`'s
+ # callers). Lets Switch Trust tell two checks apart; nothing here
+ # relies on it being stable across retries.
+ "x-agent-turn-id": str(uuid.uuid4()),
+ }
try:
response = await self._client.post(
self._url,
json=payload,
- headers=self._headers,
+ headers=headers,
timeout=self._timeout_seconds,
)
except httpx.HTTPError as error:
@@ -215,8 +240,22 @@ def trust_annotation(result: TrustCheckResult) -> str | None:
return None
+def trust_redaction_notice(result: TrustCheckResult) -> str | None:
+ """A notice for whoever sent a message Switch Trust redacted — without
+ it, they have no way to know their own words were altered before anyone
+ else saw them. `None` for every other outcome."""
+ if result.outcome != "redacted":
+ return None
+ categories = ", ".join(sorted({f.category for f in result.findings}))
+ detail = categories or "policy violation"
+ return (
+ f"⚠️ Part of your message ({detail}) was redacted by Switch Trust "
+ "before it was delivered."
+ )
+
+
async def check_message(
- client: TrustClient, *, role: Role, content: str
+ client: TrustClient, *, role: Role, content: str, room_id: str
) -> TrustCheckResult:
"""`client.check`, failing open: a Switch Trust outage degrades to
unchecked messages rather than to no messaging at all. Logged loudly
@@ -224,7 +263,7 @@ async def check_message(
`outcome="errored"` rather than `"ok"`, so callers give it the same
quiet in-chat annotation as an engine-side error."""
try:
- return await client.check(role=role, content=content)
+ return await client.check(role=role, content=content, room_id=room_id)
except GuardrailsCheckError:
logger.warning(
"Switch Trust check failed; message allowed through unchecked",
diff --git a/core/tests/integration/conftest.py b/core/tests/integration/conftest.py
index e0572de00..3b32da77a 100644
--- a/core/tests/integration/conftest.py
+++ b/core/tests/integration/conftest.py
@@ -255,6 +255,7 @@ class Harness:
protocol: AgentCore,
room_service: RoomService,
client_lifecycle: ClientLifecycleService,
+ client_factory: ClientFactory,
room_store: RoomStore,
event_buffer: EventBuffer,
owner_id: str,
@@ -263,6 +264,12 @@ class Harness:
self.protocol = protocol
self.room_service = room_service
self.client_lifecycle = client_lifecycle
+ # Not registered by default — most tests never need a running admin
+ # client, and one running in every test room changes what every
+ # room_join-watching test sees (admin is itself a room member once its
+ # client runs). A test that needs the SystemActor (e.g. to read back an
+ # admin notice) registers it itself, through this, before start_clients().
+ self.client_factory = client_factory
self.room_store = room_store
self.event_buffer = event_buffer
self.owner_id = owner_id
@@ -651,6 +658,7 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:
protocol=protocol,
room_service=room_service,
client_lifecycle=client_lifecycle,
+ client_factory=client_factory,
room_store=session_env.room_store,
event_buffer=event_buffer,
owner_id=owner_id,
diff --git a/core/tests/integration/test_switch_trust_agent_e2e.py b/core/tests/integration/test_switch_trust_agent_e2e.py
new file mode 100644
index 000000000..0a2ba72e1
--- /dev/null
+++ b/core/tests/integration/test_switch_trust_agent_e2e.py
@@ -0,0 +1,214 @@
+"""End-to-end tests for Switch Trust enforcement on agent-authored messages,
+over the real transport (docs/design/switch-trust-guardrails-v1.md).
+
+Drives the genuine path: `AgentCore.send_message` → `_enforce_trust` →
+(blocked: `SystemActor.send_admin` / allowed-or-degraded: the real send) — and
+reads the outcome back out of the `messages` table, so nothing is inferred
+from in-process state.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from switch_core.bridges.agent.protocol.agent_connections import AgentConnectionRegistry
+from switch_core.clients.actor import SystemActor
+from switch_core.clients.command_consumer import CommandConsumer
+from switch_core.db.models import Message
+from switch_core.room_service import RoomCreateConfig
+from switch_core.trust.client import (
+ GuardrailBlockedError,
+ GuardrailsCheckError,
+ TrustCheckResult,
+ TrustFinding,
+)
+from tests.integration.conftest import Harness, SessionEnv
+
+pytestmark = [pytest.mark.integration, pytest.mark.asyncio(loop_scope="session")]
+
+
+class _FixedTrustClient:
+ def __init__(self, result: TrustCheckResult) -> None:
+ self._result = result
+ self.room_ids: list[str] = []
+
+ async def check(self, *, role: str, content: str, room_id: str) -> TrustCheckResult:
+ self.room_ids.append(room_id)
+ return self._result
+
+
+class _FailingTrustClient:
+ """A Switch Trust outage: every check raises, never answers an outcome."""
+
+ async def check(self, *, role: str, content: str, room_id: str) -> TrustCheckResult:
+ raise GuardrailsCheckError("boom")
+
+
+async def _wait_joined(
+ client: object, transport_room_id: str, timeout: float = 30
+) -> None:
+ deadline = asyncio.get_event_loop().time() + timeout
+ while asyncio.get_event_loop().time() < deadline:
+ if transport_room_id in client.room_join_times: # type: ignore[attr-defined]
+ return
+ await asyncio.sleep(0.25)
+ raise AssertionError(f"client never joined {transport_room_id} within {timeout}s")
+
+
+async def _timeline_messages(
+ harness: Harness, session_env: SessionEnv, room_id: str
+) -> list[Message]:
+ async with harness.session_factory() as session: # type: ignore[operator]
+ rows = await session_env.message_store.list_for_room(
+ session, room_id, after_seq=0, limit=100
+ )
+ return [row for row in rows if row.event_type == "m.room.message"]
+
+
+async def _wire_admin_client(harness: Harness, session_env: SessionEnv) -> None:
+ """Registers and starts Switch's own SystemActor, the way `main.py` does.
+
+ Not part of the shared `harness` fixture: most integration tests don't
+ want a running admin client, since one silently joins every room they
+ create (`Harness.client_factory`'s docstring) which changes what
+ room_join-watching tests see. Only the Switch Trust blocked-notice case
+ here needs it, to read the `TRUST_BLOCKED` admin row back.
+ """
+ harness.client_factory.register(
+ "admin",
+ SystemActor,
+ CommandConsumer,
+ agent_store=session_env.agent_store,
+ room_store=session_env.room_store,
+ room_role_store=session_env.room_role_store,
+ document_store=session_env.document_store,
+ reference_store=session_env.reference_store,
+ agent_session_store=session_env.agent_session_store,
+ room_service=harness.room_service,
+ connections=AgentConnectionRegistry(),
+ frontend_base_url=session_env.config.frontend_base_url,
+ )
+ await harness.client_lifecycle.ensure_system_client("admin")
+
+
+async def _setup_room(
+ harness: Harness, session_env: SessionEnv, agent_name: str, *, with_admin: bool
+) -> tuple[str, str]:
+ """Registers an agent, starts it, and returns (agent_id, room_id) for a
+ room it has already joined."""
+ if with_admin:
+ await _wire_admin_client(harness, session_env)
+ agent = await harness.register_agent(agent_name)
+ await harness.start_clients()
+ client = harness.client_for(agent.agent_id)
+ result = await harness.room_service.create_room(
+ RoomCreateConfig(
+ name=f"{agent_name}-room",
+ description="integration switch trust test",
+ agent_ids=[agent.agent_id],
+ )
+ )
+ await _wait_joined(client, result.room.transport_room_id)
+ return agent.agent_id, result.room.id
+
+
+async def test_blocked_agent_message_is_not_sent_and_names_the_agent(
+ harness: Harness, session_env: SessionEnv
+) -> None:
+ agent_id, room_id = await _setup_room(
+ harness, session_env, "e2e-trust-blocked", with_admin=True
+ )
+ trust_client = _FixedTrustClient(
+ TrustCheckResult(
+ outcome="blocked",
+ policy_id="policy-1",
+ policy_name="default",
+ findings=(
+ TrustFinding(
+ category="pii/email", detector_name="email", severity="high"
+ ),
+ ),
+ )
+ )
+ harness.protocol.trust_client = trust_client
+
+ with pytest.raises(GuardrailBlockedError):
+ await harness.protocol.send_message(
+ agent_id, room_id, "my email is [email protected]"
+ )
+
+ rows = await _timeline_messages(harness, session_env, room_id)
+ assert not any(
+ "my email is [email protected]" in row.content.get("body", "") for row in rows
+ )
+ admin_rows = [row for row in rows if "com.switch.admin" in row.content]
+ assert len(admin_rows) == 1
+ assert admin_rows[0].content["com.switch.admin"]["type"] == "trust_blocked"
+ assert "e2e-trust-blocked" in admin_rows[0].content["body"]
+ assert "blocked by Switch Trust" in admin_rows[0].content["body"]
+ assert trust_client.room_ids == [room_id]
+
+
+async def test_allowed_agent_message_is_sent_unaffected(
+ harness: Harness, session_env: SessionEnv
+) -> None:
+ agent_id, room_id = await _setup_room(
+ harness, session_env, "e2e-trust-allowed", with_admin=False
+ )
+ harness.protocol.trust_client = _FixedTrustClient(
+ TrustCheckResult(outcome="ok", policy_id="policy-1", policy_name="default")
+ )
+
+ await harness.protocol.send_message(agent_id, room_id, "hello there")
+
+ rows = await _timeline_messages(harness, session_env, room_id)
+ assert any(row.content.get("body") == "hello there" for row in rows)
+ assert not any("com.switch.admin" in row.content for row in rows)
+
+
+async def test_redacted_agent_message_is_sent_with_content_swapped(
+ harness: Harness, session_env: SessionEnv
+) -> None:
+ agent_id, room_id = await _setup_room(
+ harness, session_env, "e2e-trust-redacted", with_admin=False
+ )
+ harness.protocol.trust_client = _FixedTrustClient(
+ TrustCheckResult(
+ outcome="redacted",
+ policy_id="policy-1",
+ policy_name="default",
+ findings=(
+ TrustFinding(
+ category="pii/email", detector_name="email", severity="high"
+ ),
+ ),
+ redacted_content="my email is [redacted]",
+ )
+ )
+
+ await harness.protocol.send_message(
+ agent_id, room_id, "my email is [email protected]"
+ )
+
+ rows = await _timeline_messages(harness, session_env, room_id)
+ assert any(row.content.get("body") == "my email is [redacted]" for row in rows)
+ assert not any("[email protected]" in row.content.get("body", "") for row in rows)
+
+
+async def test_trust_check_failure_fails_open_and_annotates_instead_of_blocking(
+ harness: Harness, session_env: SessionEnv
+) -> None:
+ agent_id, room_id = await _setup_room(
+ harness, session_env, "e2e-trust-failopen", with_admin=False
+ )
+ harness.protocol.trust_client = _FailingTrustClient()
+
+ await harness.protocol.send_message(agent_id, room_id, "hello there")
+
+ rows = await _timeline_messages(harness, session_env, room_id)
+ sent = [row for row in rows if "hello there" in row.content.get("body", "")]
+ assert len(sent) == 1
+ assert "Switch Trust could not fully check" in sent[0].content["body"]
+ assert not any("com.switch.admin" in row.content for row in rows)
diff --git a/core/tests/switch_core/bridges/agent/protocol/test_pool_checkouts.py b/core/tests/switch_core/bridges/agent/protocol/test_pool_checkouts.py
index 5194ef749..2e2468a29 100644
--- a/core/tests/switch_core/bridges/agent/protocol/test_pool_checkouts.py
+++ b/core/tests/switch_core/bridges/agent/protocol/test_pool_checkouts.py
@@ -315,6 +315,8 @@ class TestSendMessage:
sent: list[tuple[str, str]] = []
class _Client:
+ agent = SimpleNamespace(name="member")
+
async def send_message(
self, transport_room_id: str, content: str, **_kwargs: Any
) -> str:
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_trust.py b/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_trust.py
new file mode 100644
index 000000000..4c0a07309
--- /dev/null
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_trust.py
@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from switch_core.bridges.collaboration.collaboration_core import CollaborationCore
+from switch_core.bridges.collaboration.models import InboundMessage
+from switch_core.clients.admin_messages import AdminMessageType
+from switch_core.trust.client import (
+ GuardrailsCheckError,
+ TrustCheckResult,
+ TrustFinding,
+)
+
+# Switch Trust guardrails, enforced in CollaborationCore._handle_inbound_message
+# before a human-authored message becomes a room row (docs/design/switch-trust-guardrails-v1.md).
+
+TRANSPORT_ROOM_ID = "!matrix:switch.local"
+
+
+async def _noop_repair(*_args: object, **_kwargs: object) -> None:
+ return None
+
+
+async def _no_text_answer(_msg: object) -> None:
+ return None
+
+
+async def _is_registered_agent(_name: str) -> bool:
+ return False
+
+
+class _FakeHumanActor:
+ """Already-joined human actor — these tests exercise the trust gate, not
+ the join race `test_bridge_unknown_member_first_message.py` covers."""
+
+ def __init__(self) -> None:
+ self.transport_user_id = "@ext_alice:switch.local"
+ self.sent: list[tuple[str, str]] = []
+
+ async def send_message(self, room_id: str, content: str, **_kw: object) -> str:
+ self.sent.append((room_id, content))
+ return "$event-1"
+
+
+class _FakeAdapter:
+ def __init__(self) -> None:
+ self.admin_messages: list[tuple[str, str, str | None, str]] = []
+
+ def translate_inbound(self, content: str) -> str:
+ return content
+
+ async def admin_message(
+ self,
+ channel_id: str,
+ body: str,
+ root_or_ref: str | None,
+ *,
+ message_type: str,
+ ) -> None:
+ self.admin_messages.append((channel_id, body, root_or_ref, message_type))
+
+
+class _FixedTrustClient:
+ def __init__(self, result: TrustCheckResult) -> None:
+ self._result = result
+ self.room_ids: list[str] = []
+
+ async def check(self, *, role: str, content: str, room_id: str) -> TrustCheckResult:
+ self.room_ids.append(room_id)
+ return self._result
+
+
+class _FailingTrustClient:
+ """A Switch Trust outage: every check raises, never answers an outcome."""
+
+ async def check(self, *, role: str, content: str, room_id: str) -> TrustCheckResult:
+ raise GuardrailsCheckError("boom")
+
+
+def _bridge(
+ human_actor: _FakeHumanActor, adapter: _FakeAdapter, trust_client: object
+) -> SimpleNamespace:
+ relayed: list[tuple[str, str]] = []
+
+ async def _ensure_human_in_room(**_kw: object) -> _FakeHumanActor:
+ return human_actor
+
+ async def _record_message_map(**kwargs: str) -> None:
+ relayed.append((kwargs["transport_event_id"], kwargs["external_post_id"]))
+
+ bridge = SimpleNamespace(
+ _repair_placeholder_username=_noop_repair,
+ _is_registered_agent=_is_registered_agent,
+ _ensure_human_in_room=_ensure_human_in_room,
+ _record_message_map=_record_message_map,
+ _adapter=adapter,
+ _handle_text_answer=_no_text_answer,
+ _channel_to_room={"chan-1": ("room-uuid", TRANSPORT_ROOM_ID)},
+ _channel_locks={},
+ _trust_client=trust_client,
+ )
+ bridge.relayed = relayed
+ return bridge
+
+
+def _message(content: str) -> InboundMessage:
+ return InboundMessage(
+ channel_id="chan-1",
+ channel_type="channel_public",
+ sender_id="ext-alice",
+ sender_name="alice",
+ content=content,
+ message_ref="mm-post-1",
+ )
+
+
+async def test_blocked_message_never_reaches_the_room_and_sender_is_notified() -> None:
+ human_actor = _FakeHumanActor()
+ adapter = _FakeAdapter()
+ result = TrustCheckResult(
+ outcome="blocked",
+ policy_id="policy-1",
+ policy_name="default",
+ findings=(
+ TrustFinding(category="pii/email", detector_name="email", severity="high"),
+ ),
+ )
+ bridge = _bridge(human_actor, adapter, _FixedTrustClient(result))
+
+ await CollaborationCore._handle_inbound_message(
+ bridge, _message("my email is [email protected]")
+ )
+
+ assert human_actor.sent == []
+ assert bridge.relayed == []
+ assert len(adapter.admin_messages) == 1
+ channel_id, body, root_or_ref, message_type = adapter.admin_messages[0]
+ assert channel_id == "chan-1"
+ assert "blocked by Switch Trust" in body
+ assert root_or_ref == "mm-post-1"
+ assert message_type == AdminMessageType.TRUST_BLOCKED.value
+
+
+async def test_redacted_message_reaches_the_room_redacted_and_sender_is_notified() -> (
+ None
+):
+ human_actor = _FakeHumanActor()
+ adapter = _FakeAdapter()
+ result = TrustCheckResult(
+ outcome="redacted",
+ policy_id="policy-1",
+ policy_name="default",
+ findings=(
+ TrustFinding(category="pii/email", detector_name="email", severity="high"),
+ ),
+ redacted_content="my email is [redacted]",
+ )
+ bridge = _bridge(human_actor, adapter, _FixedTrustClient(result))
+
+ await CollaborationCore._handle_inbound_message(
+ bridge, _message("my email is [email protected]")
+ )
+
+ assert human_actor.sent == [(TRANSPORT_ROOM_ID, "my email is [redacted]")]
+ assert len(adapter.admin_messages) == 1
+ channel_id, body, root_or_ref, message_type = adapter.admin_messages[0]
+ assert channel_id == "chan-1"
+ assert "redacted" in body
+ assert "pii/email" in body
+ assert root_or_ref == "mm-post-1"
+ assert message_type == AdminMessageType.TRUST_REDACTED.value
+
+
+async def test_allowed_message_is_relayed_unaffected() -> None:
+ human_actor = _FakeHumanActor()
+ adapter = _FakeAdapter()
+ result = TrustCheckResult(outcome="ok", policy_id="policy-1", policy_name="default")
+ trust_client = _FixedTrustClient(result)
+ bridge = _bridge(human_actor, adapter, trust_client)
+
+ await CollaborationCore._handle_inbound_message(bridge, _message("hello there"))
+
+ assert human_actor.sent == [(TRANSPORT_ROOM_ID, "hello there")]
+ assert adapter.admin_messages == []
+ # The check is scoped to the room it happened in.
+ assert trust_client.room_ids == ["room-uuid"]
+
+
+async def test_trust_check_failure_fails_open_and_annotates_instead_of_blocking() -> (
+ None
+):
+ human_actor = _FakeHumanActor()
+ adapter = _FakeAdapter()
+ bridge = _bridge(human_actor, adapter, _FailingTrustClient())
+
+ await CollaborationCore._handle_inbound_message(bridge, _message("hello there"))
+
+ assert len(human_actor.sent) == 1
+ _, content = human_actor.sent[0]
+ assert content.startswith("hello there")
+ assert "Switch Trust could not fully check" in content
+ # A degraded check is disclosed inline, not via a separate notice.
+ assert adapter.admin_messages == []
diff --git a/core/tests/switch_core/test_config_switch_trust.py b/core/tests/switch_core/test_config_switch_trust.py
index 2480d0e67..c27fd5db4 100644
--- a/core/tests/switch_core/test_config_switch_trust.py
+++ b/core/tests/switch_core/test_config_switch_trust.py
@@ -33,7 +33,7 @@ def _config(**overrides: object) -> SwitchConfig:
def test_off_by_default() -> None:
config = _config()
assert config.trust_enabled is False
- assert config.switch_trust_endpoint == "https://api.flintai.dev"
+ assert config.switch_trust_endpoint == "https://api.switchagents.ai"
def test_setting_both_enables_it() -> None:
diff --git a/core/tests/switch_core/trust/test_client.py b/core/tests/switch_core/trust/test_client.py
index fb66b16ab..c9527838e 100644
--- a/core/tests/switch_core/trust/test_client.py
+++ b/core/tests/switch_core/trust/test_client.py
@@ -4,6 +4,7 @@ sites that use them.
"""
import json
+import uuid
import httpx
import pytest
@@ -38,19 +39,44 @@ async def test_posts_the_one_message_with_the_expected_headers():
seen["url"] = str(request.url)
seen["policy"] = request.headers.get("x-guardrails-policy-id")
seen["key"] = request.headers.get("x-flintai-api-key")
+ seen["agent_name"] = request.headers.get("x-agent-name")
+ seen["session_id"] = request.headers.get("x-agent-session-id")
+ seen["turn_id"] = request.headers.get("x-agent-turn-id")
seen["body"] = json.loads(request.content)
return httpx.Response(200, json={"outcome": "GUARDRAIL_RESULT_OUTCOME_OK"})
client = _client(handler)
- result = await client.check(role="user", content="hi")
+ result = await client.check(role="user", content="hi", room_id="room-1")
assert seen["url"] == "https://trust.example/guardrails/check"
assert seen["policy"] == "pol_123"
assert seen["key"] == "k"
+ # Always the same constant agent identity (Switch has no single "agent" to
+ # attribute a check to); the room and a fresh per-check id carry the
+ # per-call distinction instead.
+ assert seen["agent_name"] == "Switch Rooms"
+ assert seen["session_id"] == "room-1"
+ assert uuid.UUID(str(seen["turn_id"])) # a fresh, well-formed UUID
assert seen["body"] == {"messages": [{"role": "user", "content": "hi"}]}
assert result.blocked is False
+async def test_each_check_gets_its_own_turn_id():
+ seen: list[str | None] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ seen.append(request.headers.get("x-agent-turn-id"))
+ return httpx.Response(200, json={"outcome": "GUARDRAIL_RESULT_OUTCOME_OK"})
+
+ client = _client(handler)
+ await client.check(role="user", content="hi", room_id="room-1")
+ await client.check(role="user", content="hi", room_id="room-1")
+
+ assert len(seen) == 2
+ assert seen[0] != seen[1]
+
+
@pytest.mark.asyncio
async def test_a_trailing_slash_on_the_base_url_does_not_double_up():
seen: dict[str, object] = {}
@@ -66,7 +92,7 @@ async def test_a_trailing_slash_on_the_base_url_does_not_double_up():
timeout_seconds=1.0,
client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
)
- await client.check(role="user", content="hi")
+ await client.check(role="user", content="hi", room_id="room-1")
assert seen["url"] == "https://trust.example/guardrails/check"
@@ -91,7 +117,9 @@ async def test_a_blocked_outcome_carries_its_findings():
)
client = _client(handler)
- result = await client.check(role="user", content="my email is [email protected]")
+ result = await client.check(
+ role="user", content="my email is [email protected]", room_id="room-1"
+ )
assert result.blocked is True
assert result.policy_name == "Default Policy"
@@ -106,7 +134,7 @@ async def test_a_blocked_outcome_carries_its_findings():
async def test_an_error_response_raises_rather_than_allowing_silently():
client = _client(lambda request: httpx.Response(503, text="unavailable"))
with pytest.raises(GuardrailsCheckError, match="503"):
- await client.check(role="user", content="hi")
+ await client.check(role="user", content="hi", room_id="room-1")
@pytest.mark.asyncio
@@ -116,19 +144,21 @@ async def test_a_network_failure_raises():
client = _client(handler)
with pytest.raises(GuardrailsCheckError, match="failed"):
- await client.check(role="user", content="hi")
+ await client.check(role="user", content="hi", room_id="room-1")
@pytest.mark.asyncio
async def test_null_client_always_allows():
- result = await NullTrustClient().check(role="user", content="anything")
+ result = await NullTrustClient().check(
+ role="user", content="anything", room_id="room-1"
+ )
assert result.blocked is False
@pytest.mark.asyncio
async def test_check_message_fails_open_on_error():
client = _client(lambda request: httpx.Response(500, text="boom"))
- result = await check_message(client, role="user", content="hi")
+ result = await check_message(client, role="user", content="hi", room_id="room-1")
assert result == TrustCheckResult(
outcome="errored", policy_id=None, policy_name=None
)
@@ -141,7 +171,9 @@ async def test_check_message_passes_through_a_block():
200, json={"outcome": "GUARDRAIL_RESULT_OUTCOME_BLOCKED"}
)
)
- result = await check_message(client, role="assistant", content="hi")
+ result = await check_message(
+ client, role="assistant", content="hi", room_id="room-1"
+ )
assert result.blocked is True
@@ -179,7 +211,9 @@ async def test_a_redacted_outcome_swaps_the_detected_text():
client = _client(handler)
result = await client.check(
- role="user", content="email me at [email protected] please"
+ role="user",
+ content="email me at [email protected] please",
+ room_id="room-1",
)
assert result.outcome == "redacted"
@@ -195,7 +229,7 @@ async def test_a_redacted_outcome_with_no_detected_text_redacts_nothing():
200, json={"outcome": "GUARDRAIL_RESULT_OUTCOME_REDACTED", "findings": []}
)
)
- result = await client.check(role="user", content="hello")
+ result = await client.check(role="user", content="hello", room_id="room-1")
assert result.outcome == "redacted"
assert result.redacted_content == "hello"
@@ -211,7 +245,7 @@ async def test_an_alerted_outcome_is_not_blocked():
},
)
)
- result = await client.check(role="user", content="hi")
+ result = await client.check(role="user", content="hi", room_id="room-1")
assert result.outcome == "alerted"
assert result.blocked is False
assert result.redacted_content is None
@@ -222,7 +256,7 @@ async def test_an_unrecognised_outcome_is_treated_as_errored_not_allowed_silentl
client = _client(
lambda request: httpx.Response(200, json={"outcome": "SOMETHING_NEW"})
)
- result = await client.check(role="user", content="hi")
+ result = await client.check(role="user", content="hi", room_id="room-1")
assert result.outcome == "errored"
diff --git a/docs/design/switch-trust-guardrails-v1.md b/docs/design/switch-trust-guardrails-v1.md
index 4fbb45ca7..6daeb2852 100644
--- a/docs/design/switch-trust-guardrails-v1.md
+++ b/docs/design/switch-trust-guardrails-v1.md
@@ -58,8 +58,22 @@ interception point further down the stack.
Role mapping: `agent` → `assistant`, `human`/`bridge` → `user`.
2. `POST {switch_trust_endpoint}/guardrails/check` — the check-only endpoint
added in [hoot#2397](https://github.com/sandbox-quantum/hoot/pull/2397) —
- with headers `x-guardrails-policy-id` and `x-flintai-api-key`, short
- timeout (2s default).
+ with headers `x-guardrails-policy-id`, `x-flintai-api-key`, and three
+ always-set identity headers Switch Trust uses to group checks:
+ - `x-agent-name`: a constant, `Switch Rooms` — Switch has no single agent
+ to attribute a check to (a room can hold several, and a human-authored
+ message has none at all), so every check is reported under one identity
+ rather than inventing a per-sender one Switch Trust has no use for.
+ - `x-agent-session-id`: the Switch room id — a room is the closest thing
+ Switch has to an agentic session.
+ - `x-agent-turn-id`: a fresh UUID per check. Switch has no stable
+ "invocation" or "turn" id to hand it at either call site (the closest
+ existing concept, session-activity's host-supplied `turn_id`, belongs to
+ a different subsystem, is opaque to Switch, and doesn't exist for
+ human-authored messages at all), so this is generated per call instead
+ of reused.
+
+ Short timeout (2s default).
3. The outcome (mapped from the wire's `GUARDRAIL_RESULT_OUTCOME_*` values —
`ok` / `blocked` / `redacted` / `alerted` / `errored`) decides what happens
next — see §Outcome handling.
@@ -84,9 +98,11 @@ on `TrustCheckResult.outcome`:
(`core/switch_core/clients/admin_messages.py`). Every collaboration adapter
(Slack, Mattermost, Discord, Teams, Telegram) already renders
`admin_message()` as a platform-native system notice, distinct from an
- ordinary chat bubble — this is "visually stands out" for free. The
- agent's tool/API call gets back an error (HTTP 422 / an MCP tool error) so
- it knows its response was blocked.
+ ordinary chat bubble — this is "visually stands out" for free. The notice
+ names the agent (`@<agent-name> was blocked...`) so a room with several
+ agents can tell whose response was withheld. The agent's tool/API call
+ gets back an error (HTTP 422 / an MCP tool error) so it knows its response
+ was blocked.
- **Human-authored**: catch it in `CollaborationCore._handle_inbound_message`
and call the adapter's `admin_message(...)` back to the **originating
platform channel** directly (`msg.channel_id`, `msg.root_id or
@@ -103,7 +119,11 @@ on `TrustCheckResult.outcome`:
it's set. (The endpoint's own response doesn't carry a pre-sanitized
message — hoot's "SanitizedMessages" is dashboard-ingestion-only state, not
part of the `/guardrails/check` JSON body — so this redaction is Switch's
- own, built from the findings' detected text.)
+ own, built from the findings' detected text.) **Human-authored**: the
+ redacted content is what reaches the room, but the sender would otherwise
+ never know their own words were altered — `CollaborationCore` also calls
+ the adapter's `admin_message(...)` back to the originating channel (a new
+ `AdminMessageType.TRUST_REDACTED`) naming the finding categories redacted.
- **`alerted`** / **`errored`** (including a failed check, per above) — not
blocking. The caller appends a short line to the message body itself via
`trust_annotation()`, e.g. `⚠️ _Switch Trust: pii/email (not blocked)_` for
@@ -136,7 +156,7 @@ existing all-or-nothing settings groups (`_validate_slack_app`,
`core/switch_core/config.py:986`):
```python
-switch_trust_endpoint: str = "https://api.flintai.dev"
+switch_trust_endpoint: str = "https://api.switchagents.ai"
switch_trust_api_key: str = ""
switch_trust_policy_id: str = ""
switch_trust_timeout_seconds: float = 2.0
@@ -145,8 +165,7 @@ switch_trust_timeout_seconds: float = 2.0
`switch_trust_endpoint` is a base URL; the client appends
`/guardrails/check` — the check-only route added in
[hoot#2397](https://github.com/sandbox-quantum/hoot/pull/2397) — rather than
-treating the configured value as the full check URL. This default will change
-once Switch Trust has its own deployment — see Follow-ups.
+treating the configured value as the full check URL.
A `trust_enabled` property returns `bool(switch_trust_api_key and
switch_trust_policy_id)`. A `_validate_switch_trust` model validator checks
@@ -190,18 +209,20 @@ call site has to branch on whether the feature is on.
results in a `TRUST_BLOCKED` admin row instead of the real content; an
allowed message is unaffected; a Switch Trust timeout/error still delivers
the message (fail-open, annotated).
-8. **`docs/old/`**: note the new config block in whichever doc lists
- deployment env vars (none currently fully enumerates `SwitchConfig`, so
- likely just a short mention near the other optional-integration blocks, if
- one exists).
## Resolved decisions
-- Prod default for `switch_trust_endpoint`: `https://api.flintai.dev` (base
- URL; the client appends `/guardrails/check`). Expected to change once Switch
- Trust has its own deployment — tracked in Follow-ups.
+- Prod default for `switch_trust_endpoint`: `https://api.switchagents.ai`
+ (base URL; the client appends `/guardrails/check`).
- 2s timeout default, and `x-guardrails-policy-id` / `x-flintai-api-key`
headers, confirmed as-is.
+- `x-agent-name` / `x-agent-session-id` / `x-agent-turn-id` are always set,
+ never omitted: a deployment-side bug report showed a check going out with no
+ agent attribution at all. `x-agent-name` is a fixed constant rather than
+ per-caller, since nothing in Switch maps cleanly to the "one agent" these
+ headers assume — see the header list above. `TrustClient.check` takes
+ `room_id` as a required parameter (no default) precisely so a call site
+ cannot forget it; the other two headers need no caller input at all.
- The hook point moved from the originally-sketched `Actor.send_message` to
three `AgentCore` methods plus `CollaborationCore`'s inbound handler, to
avoid checking Switch's own canned/system text — see §Where it hooks in.
@@ -213,9 +234,6 @@ call site has to branch on whether the feature is on.
## Follow-ups (explicitly out of v1 scope)
-- **`switch_trust_endpoint` default will change**: `https://api.flintai.dev`
- is a placeholder base URL for now; Switch Trust is expected to get its own
- dedicated endpoint later, at which point the default should move.
- **Conversation history**: send the last N room messages as context so the
policy can catch things that only make sense across turns (e.g. a PII leak
split across messages). Needs a role-mapping strategy for Switch's
@@ -224,11 +242,6 @@ call site has to branch on whether the feature is on.
- **Tool calls / tool results**: the hoot endpoint supports `tool_calls` and
`tool_result` message fields; Switch doesn't yet have an obvious mapping
from its agent-protocol tool use onto that shape.
-- **A real cross-platform status indicator**: the inline-annotation approach
- for `ALERTED`/`ERRORED` (§Outcome handling) is a pragmatic v1 choice. A
- dedicated, Switch-level (not per-agent) reaction or status primitive across
- adapters would be a nicer fast-follow, if the inline text proves too noisy
- in practice.
- **Per-tenant / per-workspace policy**: today it's one global policy for the
whole deployment. Multiple tenants wanting different policies needs a DB
table, migration, and an admin API — a materially bigger lift than the env