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(chats): mention spans

raullopez-sandbox1e4e38907d78
diff --git a/core/switch_core/chats/service.py b/core/switch_core/chats/service.py
index 0f399a294..7dd3c6b49 100644
--- a/core/switch_core/chats/service.py
+++ b/core/switch_core/chats/service.py
@@ -54,6 +54,7 @@ from switch_core.chats.views import (
COMMAND_EVENT_TYPE,
MESSAGE_EVENT_TYPE,
SHOWN_EVENT_TYPES,
+ ChatMention,
)
from switch_core.clients.mentions import mention_regex, strip_emphasis
from switch_core.db.models import (
@@ -1453,6 +1454,7 @@ class ChatService:
mention_agent_id: str | None,
mention_agent_ids: list[str],
mention_user_ids: list[str],
+ mention_spans: list[ChatMention],
) -> tuple[Room, list[Message]]:
"""Post the user's message, every part of it in one transaction.
@@ -1464,11 +1466,15 @@ class ChatService:
The agents the message is for are `mention_agent_ids` together with
`mention_agent_id`, the one earlier clients send, as a set. The people
it names, `mention_user_ids`, address no agent (`MENTIONS_KEY`).
+ `mention_spans` say where in `body` each mention is written (UTF-16
+ offsets, as the Console's strings count); an agent's span is for it as
+ `mention_agent_ids` is, a person's addresses no agent.
"""
mentions = sorted(set(mention_agent_ids))
people = sorted(set(mention_user_ids))
- if people:
+ if people or mention_spans:
self._require_group_chats()
+ typed = _span_texts(body, mention_spans)
request: dict[str, object] = {
"roomId": room_id,
"body": body,
@@ -1480,9 +1486,17 @@ class ChatService:
request["mentionAgentIds"] = mentions
if people:
request["mentionUserIds"] = people
+ if mention_spans:
+ request["mentionSpans"] = [span.model_dump() for span in mention_spans]
payload_hash = _hash(request)
if mention_agent_id is not None:
mentions = sorted({*mentions, mention_agent_id})
+ mentions = sorted(
+ {*mentions, *(span.id for span in mention_spans if span.kind == "agent")}
+ )
+ people = sorted(
+ {*people, *(span.id for span in mention_spans if span.kind == "user")}
+ )
async with tenant_session(self.session_factory, tenant_id) as session:
room, client = await self.require_member(session, tenant_id, user, room_id)
operation = await self._operation(session, user.id, request_id)
@@ -1497,9 +1511,27 @@ class ChatService:
for upload_id in upload_ids
]
root = await self._thread_root(session, room, thread_root_id)
+ shift = 0
if mentions:
+ written = body
body = await self._with_mentions(session, room, mentions, body)
- named_people = await self._named_people(session, room, people, mentions)
+ if body != written:
+ shift = _utf16_len(body) - _utf16_len(written)
+ named_people = await self._named_people(
+ session,
+ room,
+ people,
+ mentions,
+ [
+ text[1:]
+ for text, span in zip(typed, mention_spans, strict=True)
+ if span.kind == "user"
+ ],
+ [
+ {**span.model_dump(), "offset": span.offset + shift}
+ for span in mention_spans
+ ],
+ )
if not await self._claim(
session,
@@ -1761,11 +1793,15 @@ class ChatService:
room: Room,
user_ids: list[str],
agent_ids: list[str],
- ) -> dict[str, list[str]] | None:
- """What a send records of the people it names (`MENTIONS_KEY`): their
- ids, and the names whose `@` spans address no agent. A name an agent
- named in the same send also answers to stays the agent's."""
- if not user_ids:
+ typed_names: list[str],
+ spans: list[dict[str, object]],
+ ) -> dict[str, object] | None:
+ """What a send records of the mentions it makes (`MENTIONS_KEY`): the
+ people's ids, the names whose `@` spans address no agent (the people's
+ names and what their spans say), and where each mention is written.
+ A name an agent named in the same send also answers to stays the
+ agent's."""
+ if not user_ids and not spans:
return None
names: dict[str, str] = {
user_id: name
@@ -1795,8 +1831,13 @@ class ChatService:
return {
"user_ids": user_ids,
"person_names": sorted(
- {name for name in names.values() if name.lower() not in spoken}
+ {
+ name
+ for name in [*names.values(), *typed_names]
+ if name and name.lower() not in spoken
+ }
),
+ "spans": spans,
}
async def _with_mentions(
@@ -1836,6 +1877,39 @@ def _may_use(agent: Agent, user: User, *, room_id: str, group_id: str | None) ->
)
+def _utf16_len(text: str) -> int:
+ return len(text.encode("utf-16-le")) // 2
+
+
+def _span_texts(body: str, spans: list[ChatMention]) -> list[str]:
+ """What each span covers in `body`, in the spans' order, or a refusal for
+ a span out of bounds, splitting a character, overlapping another, or not
+ starting with `@`. Offsets and lengths count UTF-16 code units."""
+ units = body.encode("utf-16-le")
+ refusal = ChatError(422, "INVALID_MENTION", "A mention does not match the message.")
+ end = 0
+ for span in sorted(spans, key=lambda each: each.offset):
+ if (
+ span.offset < end
+ or span.length < 1
+ or span.offset + span.length > len(units) // 2
+ ):
+ raise refusal
+ end = span.offset + span.length
+ texts = []
+ for span in spans:
+ try:
+ text = units[span.offset * 2 : (span.offset + span.length) * 2].decode(
+ "utf-16-le"
+ )
+ except UnicodeDecodeError as exc:
+ raise refusal from exc
+ if not text.startswith("@"):
+ raise refusal
+ texts.append(text)
+ return texts
+
+
def _owns_agent_in_room(user_id: str) -> ColumnElement[bool]:
"""True for a `Room` row holding an agent `user_id` owns."""
return exists().where(
diff --git a/core/switch_core/chats/views.py b/core/switch_core/chats/views.py
index d00a0dbe4..3b5b0d361 100644
--- a/core/switch_core/chats/views.py
+++ b/core/switch_core/chats/views.py
@@ -8,6 +8,7 @@ from __future__ import annotations
from collections.abc import Sequence
from datetime import datetime
+from typing import Literal
from pydantic import BaseModel, ConfigDict
from pydantic.alias_generators import to_camel
@@ -134,11 +135,22 @@ class ChatMessage(CamelModel):
named_agent_ids: list[str]
# The people the sender named (`mentionUserIds`); they address no agent.
named_user_ids: list[str]
+ mentions: list[ChatMention]
# Of a thread's root; 0 and None on a reply and on a message with none.
thread_reply_count: int
thread_last_reply_seq: int | None
+class ChatMention(CamelModel):
+ """Where a message names an agent or a person: `offset` and `length` in
+ UTF-16 code units of its body, as JavaScript strings count."""
+
+ kind: Literal["agent", "user"]
+ id: str
+ offset: int
+ length: int
+
+
class ChatMember(CamelModel):
user_id: str
name: str
@@ -366,6 +378,7 @@ async def chat_messages(
addressable_text(message.body or "", message.content),
),
named_user_ids=_named_user_ids(message),
+ mentions=_mentions(message),
thread_reply_count=thread[0] if thread is not None else 0,
thread_last_reply_seq=thread[1] if thread is not None else None,
)
@@ -378,3 +391,10 @@ def _named_user_ids(message: Message) -> list[str]:
if not isinstance(mentions, dict):
return []
return [each for each in mentions.get("user_ids") or [] if isinstance(each, str)]
+
+
+def _mentions(message: Message) -> list[ChatMention]:
+ mentions = message.content.get(MENTIONS_KEY)
+ if not isinstance(mentions, dict):
+ return []
+ return [ChatMention.model_validate(span) for span in mentions.get("spans") or []]
diff --git a/core/switch_core/gateway/chats.py b/core/switch_core/gateway/chats.py
index 57142da6f..9877a226a 100644
--- a/core/switch_core/gateway/chats.py
+++ b/core/switch_core/gateway/chats.py
@@ -42,6 +42,7 @@ from switch_core.chats.service import (
from switch_core.chats.views import (
CamelModel,
ChatMember,
+ ChatMention,
ChatMessage,
ChatSummary,
chat_messages,
@@ -133,6 +134,7 @@ class SendRequest(CamelModel):
mention_agent_id: str | None = None
mention_agent_ids: list[str] = []
mention_user_ids: list[str] = []
+ mention_spans: list[ChatMention] = []
class ControlRequest(CamelModel):
@@ -441,6 +443,7 @@ async def send_message(
mention_agent_id=req.mention_agent_id,
mention_agent_ids=req.mention_agent_ids,
mention_user_ids=req.mention_user_ids,
+ mention_spans=req.mention_spans,
)
async with tenant_session(service.session_factory, tenant_id) as session:
return SentMessages(messages=await chat_messages(session, room, posted))
diff --git a/core/tests/switch_core/gateway/test_chats_groups.py b/core/tests/switch_core/gateway/test_chats_groups.py
index ffccc9894..92be67912 100644
--- a/core/tests/switch_core/gateway/test_chats_groups.py
+++ b/core/tests/switch_core/gateway/test_chats_groups.py
@@ -1097,3 +1097,87 @@ async def test_group_only_requests_are_refused_while_group_chats_is_off(
chats.service.group_chats_enabled = True
assert (await _add_agent(chats, chats.alice.id, room_id, other)).status_code == 200
+
+
+def _utf16(text: str) -> bytes:
+ return text.encode("utf-16-le")
+
+
+def _at(body: str, span: dict[str, Any]) -> str:
+ units = _utf16(body)
+ return units[span["offset"] * 2 : (span["offset"] + span["length"]) * 2].decode(
+ "utf-16-le"
+ )
+
+
+async def test_mention_spans_place_people_and_agents_in_the_body(
+ chats: _Harness,
+) -> None:
+ namesake = await chats.agent("bob", owner=chats.alice)
+ helper = await chats.agent("helper", owner=chats.alice)
+ created = await chats.client.post(
+ "/chats",
+ json={
+ "agentIds": [namesake.id, helper.id],
+ "memberUserIds": [chats.bob.id],
+ "requestId": "c1",
+ },
+ headers=chats.as_user(chats.alice),
+ )
+ room_id = created.json()["chat"]["roomId"]
+
+ # An emoji (two UTF-16 units) before a person's mention of the agent's name.
+ person = {"kind": "user", "id": chats.bob.id, "offset": 3, "length": 4}
+ sent = await chats.send(
+ chats.alice, room_id, "s1", "πŸ˜€ @bob look", mentionSpans=[person]
+ )
+ assert sent.status_code == 200, sent.text
+ [message] = sent.json()["messages"]
+ assert message["mentions"] == [person]
+ assert message["namedUserIds"] == [chats.bob.id]
+ assert _at(message["body"], message["mentions"][0]) == "@bob"
+ assert (room_id, message["seq"]) not in await _events_of(chats, namesake)
+
+ # An agent the body does not name is put first; the spans move with it.
+ prefixed = await chats.send(
+ chats.alice,
+ room_id,
+ "s2",
+ "@bob see",
+ mentionAgentIds=[helper.id],
+ mentionSpans=[{"kind": "user", "id": chats.bob.id, "offset": 0, "length": 4}],
+ )
+ [message] = prefixed.json()["messages"]
+ assert message["body"] == "@helper @bob see"
+ assert [_at(message["body"], span) for span in message["mentions"]] == ["@bob"]
+ assert (room_id, message["seq"]) in await _events_of(chats, helper)
+ assert (room_id, message["seq"]) not in await _events_of(chats, namesake)
+
+ agent_span = {"kind": "agent", "id": namesake.id, "offset": 0, "length": 4}
+ for_agent = await chats.send(
+ chats.alice, room_id, "s3", "@bob go", mentionSpans=[agent_span]
+ )
+ [message] = for_agent.json()["messages"]
+ assert (room_id, message["seq"]) in await _events_of(chats, namesake)
+
+ for index, (body, spans) in enumerate(
+ [
+ ("πŸ˜€ @bob", [{**person, "offset": 1, "length": 3}]),
+ ("@bob", [{**person, "offset": 0, "length": 9}]),
+ ("hey bob", [{**person, "offset": 4, "length": 3}]),
+ ("@bob", [person | {"offset": 0}, agent_span]),
+ ]
+ ):
+ refused = await chats.send(
+ chats.alice, room_id, f"bad{index}", body, mentionSpans=spans
+ )
+ assert refused.status_code == 422, body
+ assert _code(refused) == "INVALID_MENTION"
+ stranger = await chats.send(
+ chats.alice,
+ room_id,
+ "bad-member",
+ "@admin",
+ mentionSpans=[{"kind": "user", "id": chats.admin.id, "offset": 0, "length": 6}],
+ )
+ assert _code(stranger) == "USER_NOT_IN_CHAT"