feat: implement core/ and platform/ with full test coverage

- platform/interface.py: PlatformClient Protocol + Pydantic models (User,
  MessageResponse, UserSettings) — no explicit session management, Master
  handles container lifecycle
- platform/mock.py: MockPlatformClient with simulated latency, [MOCK]
  responses, is_new correctly True only on first creation
- core/protocol.py: unified dataclasses for all events and responses
  (IncomingMessage/Command/Callback, OutgoingMessage/UI/Notification,
  AuthFlow, ChatContext, SettingsAction, etc.)
- core/store.py: StateStore Protocol + InMemoryStore (tests) + SQLiteStore
  (prod) with JSON serialization
- core/chat.py: ChatManager — chat metadata (C1/C2/C3), not container
  lifecycle (that's the platform's job)
- core/auth.py: AuthManager — start_flow / confirm / is_authenticated
- core/settings.py: SettingsManager — get/apply with store cache
- core/handler.py: EventDispatcher — registry-based routing with keys
  (command name, action name, attachment type, "*" catch-all)
- core/handlers/: register_all() + start/new/message/callback/settings
  handlers; voice slot falls back to stub text until voice_handler added
- conftest.py: sys.path fix so local platform/ shadows stdlib platform
- docs/api-contract.md: rewritten for Lambda Lab 3.0 container model

46 tests passing, 0 warnings.

core/auth.py

@@ -0,0 +1,52 @@
+# core/auth.py
+from __future__ import annotations
+
+import structlog
+
+from core.protocol import AuthFlow
+from core.store import StateStore
+
+logger = structlog.get_logger(__name__)
+
+
+def _to_dict(flow: AuthFlow) -> dict:
+    return {
+        "user_id": flow.user_id,
+        "platform": flow.platform,
+        "state": flow.state,
+        "platform_user_id": flow.platform_user_id,
+    }
+
+
+def _from_dict(d: dict) -> AuthFlow:
+    return AuthFlow(
+        user_id=d["user_id"],
+        platform=d["platform"],
+        state=d["state"],
+        platform_user_id=d.get("platform_user_id"),
+    )
+
+
+class AuthManager:
+    def __init__(self, platform: object, store: StateStore) -> None:
+        self._store = store
+
+    async def start_flow(self, user_id: str, platform: str) -> AuthFlow:
+        flow = AuthFlow(user_id=user_id, platform=platform, state="pending")
+        await self._store.set(f"auth:{user_id}", _to_dict(flow))
+        return flow
+
+    async def confirm(self, user_id: str) -> AuthFlow:
+        """В моке — автоматическое подтверждение. В реальном SDK — валидация кода."""
+        stored = await self._store.get(f"auth:{user_id}")
+        if not stored:
+            stored = {"user_id": user_id, "platform": "unknown", "state": "pending", "platform_user_id": None}
+
+        stored["state"] = "confirmed"
+        stored["platform_user_id"] = f"plt_{user_id}"
+        await self._store.set(f"auth:{user_id}", stored)
+        return _from_dict(stored)
+
+    async def is_authenticated(self, user_id: str) -> bool:
+        stored = await self._store.get(f"auth:{user_id}")
+        return stored is not None and stored.get("state") == "confirmed"

core/chat.py

@@ -0,0 +1,111 @@
+# core/chat.py
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import structlog
+
+from core.protocol import ChatContext
+from core.store import StateStore
+
+logger = structlog.get_logger(__name__)
+
+
+def _to_dict(ctx: ChatContext) -> dict:
+    return {
+        "chat_id": ctx.chat_id,
+        "display_name": ctx.display_name,
+        "platform": ctx.platform,
+        "surface_ref": ctx.surface_ref,
+        "created_at": ctx.created_at.isoformat(),
+        "is_archived": ctx.is_archived,
+    }
+
+
+def _from_dict(d: dict) -> ChatContext:
+    return ChatContext(
+        chat_id=d["chat_id"],
+        display_name=d["display_name"],
+        platform=d["platform"],
+        surface_ref=d["surface_ref"],
+        created_at=datetime.fromisoformat(d["created_at"]),
+        is_archived=d.get("is_archived", False),
+    )
+
+
+class ChatManager:
+    """
+    Управляет метаданными чатов (C1/C2/C3 в workspace пользователя).
+    НЕ управляет lifecycle контейнера — это дело Master'а на стороне платформы.
+    """
+
+    def __init__(self, platform: object, store: StateStore) -> None:
+        self._store = store
+
+    def _key(self, user_id: str, chat_id: str) -> str:
+        return f"chat:{user_id}:{chat_id}"
+
+    async def get_or_create(
+        self,
+        user_id: str,
+        chat_id: str,
+        platform: str,
+        surface_ref: str,
+        name: str | None = None,
+    ) -> ChatContext:
+        key = self._key(user_id, chat_id)
+        stored = await self._store.get(key)
+        if stored:
+            return _from_dict(stored)
+
+        ctx = ChatContext(
+            chat_id=chat_id,
+            display_name=name or f"Чат {chat_id}",
+            platform=platform,
+            surface_ref=surface_ref,
+            created_at=datetime.now(UTC),
+        )
+        await self._store.set(key, _to_dict(ctx))
+        logger.info("Chat created", chat_id=chat_id, user_id=user_id)
+        return ctx
+
+    async def get(self, chat_id: str, user_id: str | None = None) -> ChatContext | None:
+        if user_id:
+            stored = await self._store.get(self._key(user_id, chat_id))
+            return _from_dict(stored) if stored else None
+        # Scan by chat_id suffix when user_id unknown (slower)
+        for key in await self._store.keys("chat:"):
+            if key.endswith(f":{chat_id}"):
+                stored = await self._store.get(key)
+                if stored:
+                    return _from_dict(stored)
+        return None
+
+    async def rename(self, chat_id: str, name: str, user_id: str | None = None) -> ChatContext:
+        ctx = await self.get(chat_id, user_id)
+        if not ctx:
+            raise ValueError(f"Chat {chat_id} not found")
+        ctx.display_name = name
+        for key in await self._store.keys("chat:"):
+            if key.endswith(f":{chat_id}"):
+                await self._store.set(key, _to_dict(ctx))
+                break
+        return ctx
+
+    async def archive(self, chat_id: str, user_id: str | None = None) -> None:
+        ctx = await self.get(chat_id, user_id)
+        if not ctx:
+            raise ValueError(f"Chat {chat_id} not found")
+        ctx.is_archived = True
+        for key in await self._store.keys("chat:"):
+            if key.endswith(f":{chat_id}"):
+                await self._store.set(key, _to_dict(ctx))
+                break
+
+    async def list_active(self, user_id: str) -> list[ChatContext]:
+        chats = []
+        for key in await self._store.keys(f"chat:{user_id}:"):
+            stored = await self._store.get(key)
+            if stored and not stored.get("is_archived"):
+                chats.append(_from_dict(stored))
+        return chats

core/handler.py

@@ -0,0 +1,71 @@
+# core/handler.py
+from __future__ import annotations
+
+from typing import Awaitable, Callable
+
+import structlog
+
+from core.auth import AuthManager
+from core.chat import ChatManager
+from core.protocol import (
+    IncomingCallback,
+    IncomingCommand,
+    IncomingEvent,
+    IncomingMessage,
+    OutgoingEvent,
+)
+from core.settings import SettingsManager
+from platform.interface import PlatformClient
+
+logger = structlog.get_logger(__name__)
+
+HandlerFn = Callable[..., Awaitable[list[OutgoingEvent]]]
+
+
+class EventDispatcher:
+    def __init__(
+        self,
+        platform: PlatformClient,
+        chat_mgr: ChatManager,
+        auth_mgr: AuthManager,
+        settings_mgr: SettingsManager,
+    ) -> None:
+        self._platform = platform
+        self._chat_mgr = chat_mgr
+        self._auth_mgr = auth_mgr
+        self._settings_mgr = settings_mgr
+        self._handlers: dict[type, dict[str, HandlerFn]] = {
+            IncomingCommand: {},
+            IncomingMessage: {},
+            IncomingCallback: {},
+        }
+
+    def register(self, event_type: type, key: str, handler: HandlerFn) -> None:
+        self._handlers[event_type][key] = handler
+
+    async def dispatch(self, event: IncomingEvent) -> list[OutgoingEvent]:
+        event_type = type(event)
+        handlers = self._handlers.get(event_type, {})
+        key = self._routing_key(event)
+        handler = handlers.get(key) or handlers.get("*")
+
+        if handler is None:
+            logger.warning("No handler registered", event_type=event_type.__name__, key=key)
+            return []
+
+        return await handler(
+            event=event,
+            chat_mgr=self._chat_mgr,
+            auth_mgr=self._auth_mgr,
+            settings_mgr=self._settings_mgr,
+            platform=self._platform,
+        )
+
+    def _routing_key(self, event: IncomingEvent) -> str:
+        if isinstance(event, IncomingCommand):
+            return event.command
+        if isinstance(event, IncomingCallback):
+            return event.action
+        if isinstance(event, IncomingMessage) and event.attachments:
+            return event.attachments[0].type
+        return "*"

core/handlers/__init__.py

@@ -0,0 +1,24 @@
+# core/handlers/__init__.py
+from __future__ import annotations
+
+from core.handler import EventDispatcher
+from core.protocol import IncomingCallback, IncomingCommand, IncomingMessage
+from core.handlers import callback, chat, message, settings, start
+
+
+def register_all(dispatcher: EventDispatcher) -> None:
+    # Commands
+    dispatcher.register(IncomingCommand, "start",    start.handle_start)
+    dispatcher.register(IncomingCommand, "new",      chat.handle_new_chat)
+    dispatcher.register(IncomingCommand, "rename",   chat.handle_rename)
+    dispatcher.register(IncomingCommand, "archive",  chat.handle_archive)
+    dispatcher.register(IncomingCommand, "chats",    chat.handle_list_chats)
+    dispatcher.register(IncomingCommand, "settings", settings.handle_settings)
+
+    # Messages — catch-all (audio falls back here until voice_handler registered)
+    dispatcher.register(IncomingMessage, "*", message.handle_message)
+
+    # Callbacks
+    dispatcher.register(IncomingCallback, "confirm",      callback.handle_confirm)
+    dispatcher.register(IncomingCallback, "cancel",       callback.handle_cancel)
+    dispatcher.register(IncomingCallback, "toggle_skill", callback.handle_toggle_skill)

core/handlers/callback.py

@@ -0,0 +1,25 @@
+# core/handlers/callback.py
+from __future__ import annotations
+
+from core.protocol import IncomingCallback, OutgoingMessage, SettingsAction
+
+
+async def handle_confirm(event: IncomingCallback, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    action_id = event.payload.get("action_id", "unknown")
+    return [OutgoingMessage(chat_id=event.chat_id, text=f"Действие подтверждено (id: {action_id}).")]
+
+
+async def handle_cancel(event: IncomingCallback, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    action_id = event.payload.get("action_id", "unknown")
+    return [OutgoingMessage(chat_id=event.chat_id, text=f"Действие отменено (id: {action_id}).")]
+
+
+async def handle_toggle_skill(event: IncomingCallback, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    skill = event.payload.get("skill")
+    enabled = event.payload.get("enabled", True)
+    if not skill:
+        return [OutgoingMessage(chat_id=event.chat_id, text="Ошибка: не указан навык.")]
+    action = SettingsAction(action="toggle_skill", payload={"skill": skill, "enabled": enabled})
+    await settings_mgr.apply(event.user_id, action)
+    state = "включён" if enabled else "выключен"
+    return [OutgoingMessage(chat_id=event.chat_id, text=f"Навык {skill} {state}.")]

core/handlers/chat.py

@@ -0,0 +1,38 @@
+# core/handlers/chat.py
+from __future__ import annotations
+
+from core.protocol import IncomingCommand, OutgoingMessage
+
+
+async def handle_new_chat(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    if not await auth_mgr.is_authenticated(event.user_id):
+        return [OutgoingMessage(chat_id=event.chat_id, text="Введите /start чтобы начать.")]
+    name = " ".join(event.args) if event.args else None
+    ctx = await chat_mgr.get_or_create(
+        user_id=event.user_id,
+        chat_id=event.chat_id,
+        platform=event.platform,
+        surface_ref=event.chat_id,
+        name=name,
+    )
+    return [OutgoingMessage(chat_id=event.chat_id, text=f"Создан чат: {ctx.display_name}")]
+
+
+async def handle_rename(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    if not event.args:
+        return [OutgoingMessage(chat_id=event.chat_id, text="Укажите название: /rename Название")]
+    ctx = await chat_mgr.rename(event.chat_id, " ".join(event.args))
+    return [OutgoingMessage(chat_id=event.chat_id, text=f"Переименован в: {ctx.display_name}")]
+
+
+async def handle_archive(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    await chat_mgr.archive(event.chat_id)
+    return [OutgoingMessage(chat_id=event.chat_id, text="Чат архивирован.")]
+
+
+async def handle_list_chats(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    chats = await chat_mgr.list_active(event.user_id)
+    if not chats:
+        return [OutgoingMessage(chat_id=event.chat_id, text="Нет активных чатов.")]
+    lines = [f"• {c.display_name} ({c.chat_id})" for c in chats]
+    return [OutgoingMessage(chat_id=event.chat_id, text="\n".join(lines))]

core/handlers/message.py

@@ -0,0 +1,29 @@
+# core/handlers/message.py
+from __future__ import annotations
+
+from core.protocol import IncomingMessage, OutgoingMessage, OutgoingTyping
+
+
+async def handle_message(event: IncomingMessage, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    if not await auth_mgr.is_authenticated(event.user_id):
+        return [OutgoingMessage(chat_id=event.chat_id, text="Введите /start чтобы начать.")]
+
+    # Voice slot fallback: audio attachment without registered voice_handler
+    if event.attachments and event.attachments[0].type == "audio":
+        return [OutgoingMessage(
+            chat_id=event.chat_id,
+            text="Голосовые сообщения скоро поддержим.",
+            parse_mode="plain",
+        )]
+
+    response = await platform.send_message(
+        user_id=event.user_id,
+        chat_id=event.chat_id,
+        text=event.text,
+        attachments=[],
+    )
+
+    return [
+        OutgoingTyping(chat_id=event.chat_id, is_typing=False),
+        OutgoingMessage(chat_id=event.chat_id, text=response.response, parse_mode="markdown"),
+    ]

core/handlers/settings.py

@@ -0,0 +1,25 @@
+# core/handlers/settings.py
+from __future__ import annotations
+
+from core.protocol import IncomingCommand, OutgoingMessage, OutgoingUI, UIButton
+
+
+async def handle_settings(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    return [OutgoingUI(
+        chat_id=event.chat_id,
+        text="⚙️ Настройки",
+        buttons=[
+            UIButton(label="🔗 Коннекторы",    action="settings_connectors", style="secondary"),
+            UIButton(label="🧩 Скиллы",        action="settings_skills",     style="secondary"),
+            UIButton(label="🧠 Личность",      action="settings_soul",       style="secondary"),
+            UIButton(label="🔒 Безопасность",  action="settings_safety",     style="secondary"),
+            UIButton(label="💳 Подписка",      action="settings_plan",       style="secondary"),
+        ],
+    )]
+
+
+async def handle_settings_skills(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    s = await settings_mgr.get(event.user_id)
+    lines = [("✅" if on else "❌") + f" {name}" for name, on in s.skills.items()]
+    text = "🧩 Скиллы\n\n" + ("\n".join(lines) or "Нет доступных скиллов")
+    return [OutgoingMessage(chat_id=event.chat_id, text=text)]

core/handlers/start.py

@@ -0,0 +1,16 @@
+# core/handlers/start.py
+from __future__ import annotations
+
+from core.protocol import IncomingCommand, OutgoingMessage
+
+
+async def handle_start(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
+    user = await platform.get_or_create_user(event.user_id, event.platform)
+    await auth_mgr.confirm(event.user_id)
+    name = user.display_name or event.user_id
+    text = (
+        f"Добро пожаловать, {name}! Я агент Lambda. Напишите что-нибудь чтобы начать."
+        if user.is_new
+        else f"С возвращением, {name}!"
+    )
+    return [OutgoingMessage(chat_id=event.chat_id, text=text)]

core/protocol.py

@@ -0,0 +1,124 @@
+# core/protocol.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class Attachment:
+    type: str  # "image" | "document" | "audio" | "video"
+    url: str | None = None
+    content: bytes | None = None
+    filename: str | None = None
+    mime_type: str | None = None
+
+
+@dataclass
+class IncomingMessage:
+    user_id: str
+    platform: str
+    chat_id: str
+    text: str
+    attachments: list[Attachment] = field(default_factory=list)
+    reply_to: str | None = None
+
+
+@dataclass
+class IncomingCommand:
+    user_id: str
+    platform: str
+    chat_id: str
+    command: str
+    args: list[str] = field(default_factory=list)
+
+
+@dataclass
+class IncomingCallback:
+    user_id: str
+    platform: str
+    chat_id: str
+    action: str
+    payload: dict = field(default_factory=dict)
+
+
+@dataclass
+class OutgoingMessage:
+    chat_id: str
+    text: str
+    parse_mode: str = "plain"
+    attachments: list[Attachment] = field(default_factory=list)
+    reply_to: str | None = None
+
+
+@dataclass
+class UIButton:
+    label: str
+    action: str
+    payload: dict = field(default_factory=dict)
+    style: str = "secondary"  # "primary" | "danger" | "secondary"
+
+
+@dataclass
+class OutgoingUI:
+    chat_id: str
+    text: str
+    buttons: list[UIButton] = field(default_factory=list)
+
+
+@dataclass
+class OutgoingNotification:
+    chat_id: str
+    text: str
+    level: str = "info"  # "info" | "warning" | "success" | "error"
+
+
+@dataclass
+class OutgoingTyping:
+    chat_id: str
+    is_typing: bool
+
+
+@dataclass
+class ChatContext:
+    chat_id: str
+    display_name: str
+    platform: str
+    surface_ref: str
+    created_at: datetime
+    is_archived: bool = False
+
+
+@dataclass
+class AuthFlow:
+    user_id: str
+    platform: str
+    state: str  # "pending" | "code_sent" | "confirmed" | "failed"
+    platform_user_id: str | None = None
+
+
+@dataclass
+class ConfirmationRequest:
+    action_id: str
+    chat_id: str
+    description: str
+    risk_level: str  # "low" | "medium" | "high"
+    expires_at: datetime
+
+
+@dataclass
+class SettingsAction:
+    action: str
+    payload: dict = field(default_factory=dict)
+
+
+@dataclass
+class PaymentRequired:
+    user_id: str
+    reason: str
+    current_plan: str
+
+
+# Type aliases
+IncomingEvent = IncomingMessage | IncomingCommand | IncomingCallback
+OutgoingEvent = OutgoingMessage | OutgoingUI | OutgoingNotification | OutgoingTyping

core/settings.py

@@ -0,0 +1,29 @@
+# core/settings.py
+from __future__ import annotations
+
+import structlog
+
+from core.protocol import SettingsAction
+from core.store import StateStore
+from platform.interface import PlatformClient, UserSettings
+
+logger = structlog.get_logger(__name__)
+
+
+class SettingsManager:
+    def __init__(self, platform: PlatformClient, store: StateStore) -> None:
+        self._platform = platform
+        self._store = store
+
+    async def get(self, user_id: str) -> UserSettings:
+        cached = await self._store.get(f"settings:{user_id}")
+        if cached:
+            return UserSettings(**cached)
+        settings = await self._platform.get_settings(user_id)
+        await self._store.set(f"settings:{user_id}", settings.model_dump())
+        return settings
+
+    async def apply(self, user_id: str, action: SettingsAction) -> None:
+        await self._platform.update_settings(user_id, action)
+        await self._store.delete(f"settings:{user_id}")  # invalidate cache
+        logger.info("Settings applied", user_id=user_id, action=action.action)

core/store.py

@@ -0,0 +1,73 @@
+# core/store.py
+from __future__ import annotations
+
+import json
+import sqlite3
+from typing import Protocol
+
+
+class StateStore(Protocol):
+    async def get(self, key: str) -> dict | None: ...
+    async def set(self, key: str, value: dict) -> None: ...
+    async def delete(self, key: str) -> None: ...
+    async def keys(self, prefix: str) -> list[str]: ...
+
+
+class InMemoryStore:
+    def __init__(self) -> None:
+        self._data: dict[str, dict] = {}
+
+    async def get(self, key: str) -> dict | None:
+        return self._data.get(key)
+
+    async def set(self, key: str, value: dict) -> None:
+        self._data[key] = value
+
+    async def delete(self, key: str) -> None:
+        self._data.pop(key, None)
+
+    async def keys(self, prefix: str) -> list[str]:
+        return [k for k in self._data if k.startswith(prefix)]
+
+
+class SQLiteStore:
+    def __init__(self, db_path: str) -> None:
+        self._db_path = db_path
+        self._init_db()
+
+    def _init_db(self) -> None:
+        conn = sqlite3.connect(self._db_path)
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT NOT NULL)"
+        )
+        conn.commit()
+        conn.close()
+
+    async def get(self, key: str) -> dict | None:
+        conn = sqlite3.connect(self._db_path)
+        row = conn.execute("SELECT value FROM kv WHERE key = ?", (key,)).fetchone()
+        conn.close()
+        return json.loads(row[0]) if row else None
+
+    async def set(self, key: str, value: dict) -> None:
+        conn = sqlite3.connect(self._db_path)
+        conn.execute(
+            "INSERT OR REPLACE INTO kv (key, value) VALUES (?, ?)",
+            (key, json.dumps(value, default=str)),
+        )
+        conn.commit()
+        conn.close()
+
+    async def delete(self, key: str) -> None:
+        conn = sqlite3.connect(self._db_path)
+        conn.execute("DELETE FROM kv WHERE key = ?", (key,))
+        conn.commit()
+        conn.close()
+
+    async def keys(self, prefix: str) -> list[str]:
+        conn = sqlite3.connect(self._db_path)
+        rows = conn.execute(
+            "SELECT key FROM kv WHERE key LIKE ?", (prefix + "%",)
+        ).fetchall()
+        conn.close()
+        return [row[0] for row in rows]