Surfaces_team/surfaces
4
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

feat(deploy): platform handoff — agent routing, persistence, docs cleanup

Browse source 
Agent routing:
- Remove !agent command and manual agent selection flow
- Registry auto-assigns agent from user_agents mapping (fallback: agents[0])
- provision_workspace_chat and !new both write agent_id to room_meta
- Reconciliation backfills agent_id from registry on cold start
- Fix duplicate agent_id block in auth.py

Deployment stability:
- Add bot-state named volume to persist lambda_matrix.db and matrix_store
- Fix docker-compose.prod.yml duplicate environment: key (was silently losing all Matrix credentials)
- Fix MATRIX_AGENT_REGISTRY_PATH to use absolute container path /app/config/...
- Add bot-state volume declaration to docker-compose.fullstack.yml

Docs and config:
- Rewrite README.md for platform handoff (deploy table, working commands only)
- Rewrite docs/matrix-prototype.md (remove stale commands and mock descriptions)
- Remove !save/!load/!context/!agent from help text and welcome message
- Add !clear, !list, !remove, !yes/!no to help text
- Clean up .env.example (remove Telegram token, internal vars, real URLs)
- Update config/matrix-agents.example.yaml with user_agents section and comments
- Add explanatory comment to Dockerfile for --ignore-requires-python
- Remove silent uv sync fallbacks in Dockerfile
This commit is contained in:
Mikhail Putilovskij 2026-04-28 03:05:11 +03:00
parent 380961d6e9
commit b1aaa210a1
21 changed files with 311 additions and 937 deletions
Download patch file Download diff file Expand all files Collapse all files

19
adapter/matrix/agent_registry.py
View file

@ -18,9 +18,14 @@ class AgentDefinition:
class AgentRegistry:
def __init__(self, agents: list[AgentDefinition]) -> None:
def __init__(
self,
agents: list[AgentDefinition],
user_agents: Mapping[str, str] | None = None,
) -> None:
self.agents = tuple(agents)
self._by_id = {agent.agent_id: agent for agent in self.agents}
self._user_agents: dict[str, str] = dict(user_agents or {})
def get(self, agent_id: str) -> AgentDefinition:
try:
@ -28,6 +33,9 @@ class AgentRegistry:
except KeyError as exc:
raise AgentRegistryError(f"unknown agent id: {agent_id}") from exc
def get_agent_id_for_user(self, matrix_user_id: str) -> str | None:
return self._user_agents.get(matrix_user_id)
def _required_text(entry: Mapping[str, object], key: str) -> str:
value = entry.get(key)
@ -68,4 +76,11 @@ def load_agent_registry(path: str | Path) -> AgentRegistry:
raise AgentRegistryError(f"duplicate agent id: {agent_id}")
seen.add(agent_id)
agents.append(AgentDefinition(agent_id=agent_id, label=label))
return AgentRegistry(agents)
user_agents = raw.get("user_agents")
if user_agents is not None:
if not isinstance(user_agents, Mapping):
raise AgentRegistryError("user_agents must be a mapping of user_id to agent_id")
user_agents = {str(k): str(v) for k, v in user_agents.items()}
return AgentRegistry(agents, user_agents)

42
adapter/matrix/bot.py
View file

@ -45,7 +45,6 @@ from adapter.matrix.store import (
clear_staged_attachments,
get_load_pending,
get_room_meta,
get_selected_agent_id,
get_staged_attachments,
next_platform_chat_id,
remove_staged_attachment_at,
@ -89,6 +88,7 @@ class MatrixRuntime:
settings_mgr: SettingsManager
dispatcher: EventDispatcher
agent_routing_enabled: bool = False
registry: AgentRegistry | None = None
def build_event_dispatcher(platform: PlatformClient, store: StateStore) -> EventDispatcher:
@ -197,6 +197,7 @@ def build_runtime(
settings_mgr=settings_mgr,
dispatcher=dispatcher,
agent_routing_enabled=isinstance(platform, RoutedPlatformClient),
registry=registry,
)
@ -261,10 +262,7 @@ class MatrixBot:
)
return
if not body.startswith("!") and self.runtime.agent_routing_enabled:
block = await self._check_agent_routing(room.room_id, sender, room_meta)
if block is not None:
await self._send_all(room.room_id, block)
return
pass
local_chat_id = await resolve_chat_id(self.runtime.store, room.room_id, sender)
incoming = from_room_event(event, room_id=room.room_id, chat_id=local_chat_id)
@ -485,6 +483,7 @@ class MatrixBot:
self.runtime.store,
self.runtime.auth_mgr,
self.runtime.chat_mgr,
registry=self.runtime.registry,
)
except Exception as exc:
logger.warning(
@ -594,40 +593,9 @@ class MatrixBot:
self.runtime.store,
self.runtime.auth_mgr,
self.runtime.chat_mgr,
self.runtime.registry,
)
async def _check_agent_routing(
self,
room_id: str,
sender: str,
room_meta: dict,
) -> list[OutgoingEvent] | None:
selected_agent_id = await get_selected_agent_id(self.runtime.store, sender)
if not selected_agent_id:
return [
OutgoingMessage(
chat_id=room_id,
text="Выбери агент через !agent прежде чем отправлять сообщения.",
)
]
room_agent_id = room_meta.get("agent_id")
if room_agent_id and room_agent_id != selected_agent_id:
return [
OutgoingMessage(
chat_id=room_id,
text=(
f"Этот чат привязан к агенту «{room_agent_id}». "
"Создай новый чат командой !new."
),
)
]
if not room_agent_id:
await set_room_agent_id(self.runtime.store, room_id, selected_agent_id)
await self._ensure_platform_chat_id(
room_id, await get_room_meta(self.runtime.store, room_id)
)
return None
async def _send_all(self, room_id: str, outgoing: list[OutgoingEvent]) -> None:
for event in outgoing:
await send_outgoing(self.client, room_id, event, store=self.runtime.store)

5
adapter/matrix/handlers/__init__.py
View file

@ -1,6 +1,5 @@
from __future__ import annotations
from adapter.matrix.handlers.agent import make_handle_agent
from adapter.matrix.handlers.chat import (
handle_list_chats,
make_handle_archive,
@ -39,9 +38,7 @@ def register_matrix_handlers(
prototype_state=None,
agent_base_url: str = "http://127.0.0.1:8000",
) -> None:
if store is not None and registry is not None:
dispatcher.register(IncomingCommand, "agent", make_handle_agent(store, registry))
dispatcher.register(IncomingCommand, "new", make_handle_new_chat(client, store))
dispatcher.register(IncomingCommand, "new", make_handle_new_chat(client, store, registry))
dispatcher.register(IncomingCommand, "chats", handle_list_chats)
dispatcher.register(IncomingCommand, "rename", make_handle_rename(client, store))
dispatcher.register(IncomingCommand, "archive", make_handle_archive(client, store))

78
adapter/matrix/handlers/agent.py
View file

@ -1,78 +0,0 @@
from __future__ import annotations
from collections.abc import Awaitable, Callable
from adapter.matrix.agent_registry import AgentRegistry
from adapter.matrix.store import (
get_platform_chat_id,
get_selected_agent_id,
get_room_meta,
next_platform_chat_id,
set_platform_chat_id,
set_room_agent_id,
set_selected_agent_id,
)
from core.protocol import IncomingCommand, OutgoingMessage
def make_handle_agent(store, registry: AgentRegistry) -> Callable[..., Awaitable[list]]:
async def handle_agent(
event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
) -> list:
if not event.args:
selected_agent_id = await get_selected_agent_id(store, event.user_id)
lines = ["Доступные агенты:"]
for index, agent in enumerate(registry.agents, start=1):
suffix = " [текущий]" if agent.agent_id == selected_agent_id else ""
lines.append(f"{index}. {agent.label}{suffix}")
lines.extend(["", "Выбери агент: !agent <номер>"])
return [OutgoingMessage(chat_id=event.chat_id, text="\n".join(lines))]
try:
selected_index = int(event.args[0])
except ValueError:
return [
OutgoingMessage(
chat_id=event.chat_id,
text="Укажи номер агента из списка: !agent <номер>.",
)
]
if selected_index < 1 or selected_index > len(registry.agents):
return [
OutgoingMessage(
chat_id=event.chat_id,
text="Такого агента нет. Открой список через !agent.",
)
]
agent = registry.agents[selected_index - 1]
await set_selected_agent_id(store, event.user_id, agent.agent_id)
current_chat = await chat_mgr.get(event.chat_id, user_id=event.user_id)
if current_chat is not None and current_chat.surface_ref:
room_id = current_chat.surface_ref
room_meta = await get_room_meta(store, room_id)
if room_meta is not None and not room_meta.get("agent_id"):
await set_room_agent_id(store, room_id, agent.agent_id)
if await get_platform_chat_id(store, room_id) is None:
await set_platform_chat_id(
store,
room_id,
await next_platform_chat_id(store),
)
return [
OutgoingMessage(
chat_id=event.chat_id,
text=f"Агент {agent.label} выбран. Текущий чат готов к работе.",
)
]
return [
OutgoingMessage(
chat_id=event.chat_id,
text=f"Агент переключен на {agent.label}. Продолжай через !new.",
)
]
return handle_agent

14
adapter/matrix/handlers/auth.py
View file

@ -6,6 +6,7 @@ import structlog
from nio.api import RoomVisibility
from nio.responses import RoomCreateError
from adapter.matrix.agent_registry import AgentRegistry
from adapter.matrix.store import (
get_user_meta,
next_platform_chat_id,
@ -30,6 +31,7 @@ async def provision_workspace_chat(
auth_mgr,
chat_mgr,
room_name_override: str | None = None,
registry: AgentRegistry | None = None,
) -> dict:
user = await platform.get_or_create_user(
external_id=matrix_user_id,
@ -64,6 +66,13 @@ async def provision_workspace_chat(
chat_id = f"C{next_chat_index}"
platform_chat_id = await next_platform_chat_id(store)
room_name = room_name_override or _default_room_name(chat_id)
agent_id = None
if registry is not None:
agent_id = registry.get_agent_id_for_user(matrix_user_id)
if agent_id is None and registry.agents:
agent_id = registry.agents[0].agent_id
chat_resp = await client.room_create(
name=room_name,
visibility=RoomVisibility.private,
@ -100,6 +109,7 @@ async def provision_workspace_chat(
"matrix_user_id": matrix_user_id,
"space_id": space_id,
"platform_chat_id": platform_chat_id,
"agent_id": agent_id,
},
)
await chat_mgr.get_or_create(
@ -127,6 +137,7 @@ async def handle_invite(
store,
auth_mgr,
chat_mgr,
registry: AgentRegistry | None = None,
) -> None:
matrix_user_id = getattr(event, "sender", "")
display_name = getattr(room, "display_name", None) or matrix_user_id
@ -147,6 +158,7 @@ async def handle_invite(
auth_mgr,
chat_mgr,
room_name_override="Чат 1",
registry=registry,
)
except RuntimeError as exc:
logger.error("invite_workspace_provision_failed", user=matrix_user_id, error=str(exc))
@ -154,7 +166,7 @@ async def handle_invite(
welcome = (
f"Привет, {created['user'].display_name or matrix_user_id}! Пиши — я здесь.\n\n"
"Команды: !new · !chats · !rename · !archive · !context · !save · !load · !help"
"Команды: !new · !chats · !rename · !archive · !clear · !help"
)
await client.room_send(
created["chat_room_id"],

13
adapter/matrix/handlers/chat.py
View file

@ -7,8 +7,8 @@ import structlog
from nio.api import RoomVisibility
from nio.responses import RoomCreateError
from adapter.matrix.agent_registry import AgentRegistry
from adapter.matrix.store import (
get_selected_agent_id,
get_user_meta,
next_chat_id,
next_platform_chat_id,
@ -49,6 +49,7 @@ async def _fallback_new_chat(
def make_handle_new_chat(
client: Any | None,
store: Any | None,
registry: AgentRegistry | None = None,
) -> Callable[..., Awaitable[list]]:
async def handle_new_chat(
event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
@ -105,7 +106,12 @@ def make_handle_new_chat(
state_key=room_id,
)
selected_agent_id = await get_selected_agent_id(store, event.user_id)
agent_id = None
if registry is not None:
agent_id = registry.get_agent_id_for_user(event.user_id)
if agent_id is None and registry.agents:
agent_id = registry.agents[0].agent_id
room_meta: dict = {
"room_type": "chat",
"chat_id": chat_id,
@ -113,9 +119,8 @@ def make_handle_new_chat(
"matrix_user_id": event.user_id,
"space_id": space_id,
"platform_chat_id": platform_chat_id,
"agent_id": agent_id,
}
if selected_agent_id:
room_meta["agent_id"] = selected_agent_id
await set_room_meta(store, room_id, room_meta)
ctx = await chat_mgr.get_or_create(
user_id=event.user_id,

13
adapter/matrix/handlers/settings.py
View file

@ -10,14 +10,15 @@ HELP_TEXT = "\n".join(
"!chats список активных чатов",
"!rename <название> переименовать текущий чат",
"!archive архивировать текущий чат",
"!context показать текущее состояние контекста",
"!save [имя] сохранить текущий контекст",
"!load показать сохранённые контексты",
"",
"!agent показать доступных агентов",
"!agent <номер> выбрать агента для следующих чатов",
"!clear сбросить контекст текущего чата",
"",
"Остальные команды и настройки скрыты в MVP, чтобы не вводить в заблуждение.",
"!list показать файлы в очереди",
"!remove <n> удалить файл из очереди",
"!remove all очистить очередь файлов",
"",
"!yes / !no подтвердить или отменить действие",
"!help эта справка",
]
)

9
adapter/matrix/reconciliation.py
View file

@ -125,6 +125,15 @@ async def reconcile_startup_state(client: object, runtime: object) -> Reconcilia
room_meta["platform_chat_id"] = await next_platform_chat_id(runtime.store)
result.backfilled_platform_chat_ids += 1
if not room_meta.get("agent_id"):
registry = getattr(runtime, "registry", None)
if registry is not None:
agent_id = registry.get_agent_id_for_user(matrix_user_id)
if agent_id is None and registry.agents:
agent_id = registry.agents[0].agent_id
if agent_id:
room_meta["agent_id"] = agent_id
if existing_meta is None:
result.recovered_rooms += 1
elif room_meta != existing_meta:

15
adapter/matrix/store.py
View file

@ -45,21 +45,6 @@ async def set_user_meta(store: StateStore, matrix_user_id: str, meta: dict) -> N
await store.set(f"{USER_META_PREFIX}{matrix_user_id}", meta)
async def get_selected_agent_id(store: StateStore, matrix_user_id: str) -> str | None:
meta = await get_user_meta(store, matrix_user_id)
return meta.get("selected_agent_id") if meta else None
async def set_selected_agent_id(
store: StateStore,
matrix_user_id: str,
agent_id: str,
) -> None:
meta = dict(await get_user_meta(store, matrix_user_id) or {})
meta["selected_agent_id"] = agent_id
await set_user_meta(store, matrix_user_id, meta)
async def set_room_agent_id(store: StateStore, room_id: str, agent_id: str) -> None:
meta = dict(await get_room_meta(store, room_id) or {})
meta["agent_id"] = agent_id