Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

31.2 KB
Raw Blame
"""Bots: an enabled Vibey Agent plus one permanent Session and a working directory (``docs/plans/bots.md``).

A Bot is no new table. Its fields live in its Agent's metadata under ``bot`` (D1), a key ordinary Agent create and
update can neither set nor clear (``core.vibe_agents.STORE_OWNED_METADATA_KEYS``); this module is its one writer.

- **Handle** (D2): lowercase ASCII, frozen once the Bot exists. It names the Session (``ses_<handle>``), the working
  directory (``~/.avibe/bots/<handle>/``), and every ``@<bot:handle>`` marker and ``--bot`` invocation.
- **Removing** the Bot role keeps the Agent, the Session, and the directory, hidden; the record keeps its handle with
  ``removed_at``, so setting the Agent as a Bot again reconnects them.
- **The main Bot** (D9) is the store-made ``main`` Agent (``VibeAgentStore.ensure_main_bot_agent``); it is always a
  Bot, and its Session is the released ``ses_main``.
- Bots are the instance Owner's (D1): every operation here requires the Owner.
"""

from __future__ import annotations

import io
import json
import logging
import re
import subprocess
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Iterable, Mapping, Optional

from sqlalchemy import func, select, update
from sqlalchemy.engine import Connection

from config import paths
from core.vibe_agents import (
    BOT_METADATA_KEY,
    MAIN_BOT_HANDLE,
    VibeAgent,
    VibeAgentStore,
    agent_bot_record,
    is_builtin_default_agent,
    is_main_bot_agent,
    normalize_agent_name,
)
from core.inbox_events import publish_bots_changed
from storage.agent_session_rows import BOT_SESSION_ID_PREFIX, is_bot_session_id, reserve_write_lock
from storage.agent_session_rows import hidden_bot_session_ids as stored_hidden_bot_session_ids
from storage.models import agent_sessions, agents
from vibe.authorization import AuthorizationContext, require_instance_role

logger = logging.getLogger(__name__)

BOT_BACKEND = "vibey"
BOT_HANDLE_PATTERN = re.compile(r"^[a-z][a-z0-9-]{1,23}$")
BOT_HANDLE_MAX_LENGTH = 24
#: Handles kept for the built-in Bots: the main Bot, and later the memory and operations Bots (D2).
RESERVED_BOT_HANDLES = frozenset({MAIN_BOT_HANDLE, "memory", "ops"})
DISPLAY_NAME_MAX_LENGTH = 64
AVATAR_FILENAME = "avatar.png"
AVATAR_SIZE = 256
AVATAR_MAX_UPLOAD_BYTES = 10 * 1024 * 1024
EMOJI_MAX_LENGTH = 16
HANDLE_SOURCE_MODEL = "model"
HANDLE_SOURCE_TRANSLITERATION = "transliteration"
GIT_INIT_TIMEOUT_SECONDS = 30


class BotError(ValueError):
    """A refused Bot operation: a stable ``code`` for every surface, the HTTP status it maps to, and details."""

    def __init__(self, code: str, message: str, *, status: int = 400, **details: Any) -> None:
        super().__init__(message)
        self.code = code
        self.status = status
        self.details = details


def _not_found(handle: str) -> BotError:
    return BotError("bot_not_found", f"Bot '{handle}' not found", status=404, handle=handle)


def _now() -> str:
    return datetime.now(timezone.utc).isoformat()


# --- identity ---------------------------------------------------------------------------------------------------


def bot_session_id(handle: str) -> str:
    return f"{BOT_SESSION_ID_PREFIX}{handle}"


def bot_handle_for_session_id(session_id: Any) -> Optional[str]:
    """The handle a Bot-namespace Session id names, or None for any other Session."""
    text = str(session_id or "")
    if not is_bot_session_id(text):
        return None
    handle = text[len(BOT_SESSION_ID_PREFIX):]
    return handle if BOT_HANDLE_PATTERN.fullmatch(handle) else None


def bot_directory(handle: str) -> Path:
    return paths.get_bot_dir(handle)


def is_valid_handle(handle: Any) -> bool:
    """D2's pattern, and no trailing hyphen: a new Bot's Agent is named after its handle, and an Agent name never
    ends in one, so such a handle could never be created."""
    return isinstance(handle, str) and BOT_HANDLE_PATTERN.fullmatch(handle) is not None and not handle.endswith("-")


def normalize_handle(text: Any) -> Optional[str]:
    """``text`` as a handle: lowercase ASCII letters, digits, and single hyphens, starting with a letter."""
    lowered = str(text or "").lower()
    candidate = re.sub(r"[^a-z0-9]+", "-", lowered).strip("-")
    candidate = re.sub(r"^[^a-z]+", "", candidate)
    candidate = candidate[:BOT_HANDLE_MAX_LENGTH].rstrip("-")
    return candidate if is_valid_handle(candidate) else None


def ascii_name_handle(display_name: str) -> Optional[str]:
    """D2 step 1: an ASCII display name, normalized (``Researcher`` to ``researcher``)."""
    name = str(display_name or "").strip()
    return normalize_handle(name) if name.isascii() else None


def transliterated_handle(display_name: str) -> Optional[str]:
    """D2 step 3: the display name transliterated with ``anyascii`` (``小爱`` to ``xiaoai``)."""
    from anyascii import anyascii

    return normalize_handle(anyascii(str(display_name or "")))


def model_handle(text: Any) -> Optional[str]:
    """A model's proposal, accepted only if it is a handle once trimmed of quoting (``CSO`` reads as ``cso``)."""
    candidate = str(text or "").strip().strip("`'\"").strip().removeprefix("@").lower()
    return candidate if is_valid_handle(candidate) else None


def _with_suffix(base: str, number: int) -> str:
    suffix = f"-{number}"
    return base[: BOT_HANDLE_MAX_LENGTH - len(suffix)].rstrip("-") + suffix


def handle_taken(conn: Connection, handle: str, *, agent_id: Optional[str] = None) -> bool:
    """Whether ``handle`` already names something other than ``agent_id``'s Bot.

    A handle is a Session id, a directory, and an Agent name at once, so any of them in use takes it: another Agent
    named so, another Agent's Bot record (removed ones too, since setting them again reconnects), a ``ses_<handle>``
    Session not run by ``agent_id``, or an existing directory, which is someone's memory. A Bot reconnecting to its
    own record's handle never asks.
    """
    owner_rows = conn.execute(
        select(agents.c.id).where(
            (agents.c.normalized_name == handle)
            | (func.json_extract(agents.c.metadata_json, f"$.{BOT_METADATA_KEY}.handle") == handle)
        )
    ).scalars().all()
    if any(owner != agent_id for owner in owner_rows):
        return True
    session_agent = conn.execute(
        select(agent_sessions.c.agent_id).where(agent_sessions.c.id == bot_session_id(handle)).limit(1)
    ).first()
    if session_agent is not None and (agent_id is None or session_agent[0] != agent_id):
        return True
    return bot_directory(handle).exists()


def free_handle(conn: Connection, base: str, *, agent_id: Optional[str] = None) -> str:
    """``base``, or ``base-2``, ``base-3``... skipping reserved handles and taken ones (D2 step 4)."""
    if not is_valid_handle(base):
        raise BotError("bot_handle_invalid", f"'{base}' is not a valid Bot handle", handle=base)
    candidate, number = base, 1
    while candidate in RESERVED_BOT_HANDLES or handle_taken(conn, candidate, agent_id=agent_id):
        number += 1
        candidate = _with_suffix(base, number)
    return candidate


def require_new_handle(conn: Connection, handle: str, *, agent_id: Optional[str] = None) -> str:
    """A handle a caller chose: valid, not reserved, and free. Never suffixed: the caller asked for this one."""
    if not is_valid_handle(handle):
        raise BotError(
            "bot_handle_invalid",
            f"'{handle}' is not a valid Bot handle: 2 to 24 lowercase letters, digits, or hyphens, starting with a "
            "letter and not ending with a hyphen",
            handle=handle,
        )
    if handle in RESERVED_BOT_HANDLES:
        raise BotError("bot_handle_reserved", f"Bot handle '{handle}' is reserved", handle=handle)
    if handle_taken(conn, handle, agent_id=agent_id):
        raise BotError("bot_handle_taken", f"Bot handle '{handle}' is already taken", status=409, handle=handle)
    return handle


def fallback_handle_base(display_name: str) -> str:
    """The handle base without a model: the normalized ASCII name, else the transliteration, else ``bot``."""
    return ascii_name_handle(display_name) or transliterated_handle(display_name) or "bot"


# --- the Bot ----------------------------------------------------------------------------------------------------


@dataclass(frozen=True)
class Bot:
    handle: str
    display_name: str
    avatar: Optional[dict[str, Any]]
    position: int
    agent: VibeAgent

    @property
    def builtin(self) -> bool:
        return is_main_bot_agent(self.agent)

    @property
    def session_id(self) -> str:
        return bot_session_id(self.handle)

    @property
    def directory(self) -> Path:
        return bot_directory(self.handle)

    @property
    def role(self) -> str:
        return str(self.agent.description or "")

    def avatar_payload(self) -> Optional[dict[str, Any]]:
        avatar = self.avatar or {}
        if avatar.get("kind") == "emoji":
            return {"kind": "emoji", "emoji": avatar.get("emoji"), "hue": avatar.get("hue")}
        if avatar.get("kind") == "image":
            image = self.directory / AVATAR_FILENAME
            try:
                version = int(image.stat().st_mtime_ns)
            except OSError:
                version = None
            if version is not None:
                return {"kind": "image", "url": f"/api/bots/{self.handle}/avatar?v={version}"}
        return {"kind": "mascot"} if self.builtin else None

    def to_payload(self) -> dict[str, Any]:
        return {
            "handle": self.handle,
            # Empty means the main Bot's localized default name (D5).
            "display_name": self.display_name,
            "avatar": self.avatar_payload(),
            "role": self.role,
            "agent_name": self.agent.name,
            "session_id": self.session_id,
            "position": self.position,
            "builtin": self.builtin,
        }


def bot_from_agent(agent: VibeAgent) -> Optional[Bot]:
    """The Bot an Agent is, or None: archived, a removed role, or no Bot record."""
    if agent.archived_at is not None:
        return None
    record = agent_bot_record(agent)
    if record is None:
        return None
    try:
        position = int(record.get("position") or 0)
    except (TypeError, ValueError):
        position = 0
    avatar = record.get("avatar")
    return Bot(
        handle=str(record["handle"]),
        display_name=str(record.get("display_name") or ""),
        avatar=dict(avatar) if isinstance(avatar, dict) else None,
        position=0 if is_main_bot_agent(agent) else position,
        agent=agent,
    )


def _display_order(bot: Bot) -> tuple[int, int, str]:
    return (0 if bot.builtin else 1, bot.position, bot.handle)


def _agent_rows(conn: Connection) -> list[VibeAgent]:
    rows = conn.execute(
        select(agents).where(agents.c.archived_at.is_(None)).where(
            func.json_extract(agents.c.metadata_json, f"$.{BOT_METADATA_KEY}.handle").is_not(None)
        )
    ).mappings().all()
    return [VibeAgentStore._from_row(row) for row in rows]


def list_bots_in(conn: Connection) -> list[Bot]:
    """Every Bot in display order: the main Bot first, then by position."""
    bots = [bot for bot in map(bot_from_agent, _agent_rows(conn)) if bot is not None]
    return sorted(bots, key=_display_order)


def hidden_bot_session_ids(conn: Connection, context: AuthorizationContext | None) -> list[str]:
    """Bots' Sessions a reader may not see: every one for a non-Owner (D1), else those of removed Bots."""
    owner = context is None or context.is_instance_owner
    return sorted(stored_hidden_bot_session_ids(conn, owner=owner))


# --- directories ------------------------------------------------------------------------------------------------


def ensure_bot_directory(handle: str) -> Path:
    """The Bot's working directory: created with ``git init`` and nothing else (D7). Idempotent."""
    directory = bot_directory(handle)
    directory.mkdir(parents=True, exist_ok=True)
    if not (directory / ".git").exists():
        init_bot_repository(directory)
    return directory


def init_bot_repository(directory: Path) -> bool:
    from core.bot_git import bot_git_environment
    from core.git_binary import resolve_git

    git = resolve_git()
    if git is None:
        logger.warning("Git is unavailable; the Bot directory %s starts without history", directory)
        return False
    try:
        result = subprocess.run(
            [str(git.path), "-c", "init.defaultBranch=main", "init", "--quiet", str(directory)],
            check=False,
            capture_output=True,
            text=True,
            env=bot_git_environment(),
            timeout=GIT_INIT_TIMEOUT_SECONDS,
        )
    except (OSError, subprocess.SubprocessError):
        logger.warning("git init failed for the Bot directory %s", directory, exc_info=True)
        return False
    if result.returncode != 0:
        logger.warning("git init failed for the Bot directory %s: %s", directory, result.stderr.strip())
        return False
    return True


# --- validation -------------------------------------------------------------------------------------------------


def _clean_display_name(value: Any, *, required: bool) -> str:
    name = " ".join(str(value or "").split())
    if not name and required:
        raise BotError("bot_display_name_required", "A Bot needs a display name")
    if len(name) > DISPLAY_NAME_MAX_LENGTH:
        raise BotError(
            "bot_display_name_too_long", f"A Bot's display name has at most {DISPLAY_NAME_MAX_LENGTH} characters"
        )
    return name


def clean_emoji_avatar(value: Any) -> Optional[dict[str, Any]]:
    """An emoji avatar (``{"emoji": ..., "hue": 0-359}``), or None to clear it."""
    if value is None:
        return None
    if not isinstance(value, Mapping):
        raise BotError("bot_avatar_invalid", "An avatar is an object with an emoji and a hue")
    emoji = str(value.get("emoji") or "").strip()
    hue = value.get("hue")
    if (
        not emoji
        or len(emoji) > EMOJI_MAX_LENGTH
        or any(char.isspace() or ord(char) < 32 for char in emoji)
        or isinstance(hue, bool)
        or not isinstance(hue, int)
        or not 0 <= hue < 360
    ):
        raise BotError("bot_avatar_invalid", "An emoji avatar needs one emoji and a hue from 0 to 359")
    return {"kind": "emoji", "emoji": emoji, "hue": hue}


def scaled_avatar_png(data: bytes) -> bytes:
    """An uploaded image as a ``AVATAR_SIZE`` square PNG, center-cropped (D5)."""
    from PIL import Image, ImageOps, UnidentifiedImageError

    if not data:
        raise BotError("bot_avatar_invalid", "The avatar upload is empty")
    if len(data) > AVATAR_MAX_UPLOAD_BYTES:
        raise BotError("bot_avatar_too_large", "The avatar upload is larger than 10 MB", status=413)
    try:
        with Image.open(io.BytesIO(data)) as image:
            image = ImageOps.exif_transpose(image)
            image = image.convert("RGBA")
            image = ImageOps.fit(image, (AVATAR_SIZE, AVATAR_SIZE), Image.Resampling.LANCZOS)
            output = io.BytesIO()
            image.save(output, format="PNG", optimize=True)
            return output.getvalue()
    except (UnidentifiedImageError, OSError, ValueError, Image.DecompressionBombError) as exc:
        raise BotError("bot_avatar_invalid", "The avatar upload is not a readable image") from exc


# --- the service ------------------------------------------------------------------------------------------------


class BotService:
    """Bot operations over the Agent catalog, Sessions, and directories. Owner only (D1)."""

    def __init__(self, store: Optional[VibeAgentStore] = None) -> None:
        self._own_store = store is None
        self.store = store or VibeAgentStore()
        self.engine = self.store.engine

    def close(self) -> None:
        if self._own_store:
            self.store.close()

    def __enter__(self) -> "BotService":
        return self

    def __exit__(self, *_exc: Any) -> None:
        self.close()

    # reads

    def list_bots(self, *, authorization_context: Any = None) -> list[Bot]:
        require_instance_role(authorization_context, "owner")
        with self.engine.connect() as conn:
            return list_bots_in(conn)

    def get_bot(self, handle: str, *, authorization_context: Any = None) -> Bot:
        require_instance_role(authorization_context, "owner")
        with self.engine.connect() as conn:
            return self._require_bot(conn, handle)

    @staticmethod
    def _require_bot(conn: Connection, handle: str) -> Bot:
        handle = str(handle or "").strip()
        for bot in list_bots_in(conn):
            if bot.handle == handle:
                return bot
        raise _not_found(handle)

    # the Bot's Session and directory

    def ensure_home(self, bot: Bot, *, authorization_context: Any = None) -> dict[str, Any]:
        """Prepare the Bot's directory and Session, creating what is missing; returns the Session payload."""
        from storage import workbench_sessions_service

        context = require_instance_role(authorization_context, "owner")
        directory = ensure_bot_directory(bot.handle)
        with self.engine.begin() as conn:
            return workbench_sessions_service.ensure_bot_session(
                conn,
                session_id=bot.session_id,
                agent={"id": bot.agent.id, "name": bot.agent.name},
                workdir=str(directory),
                title=bot.display_name or None,
                authorization_context=context,
            )

    def ensure_main_bot(self, *, authorization_context: Any = None) -> Bot:
        """The main Bot with its Agent, directory, and ``ses_main``, created or repaired on use."""
        require_instance_role(authorization_context, "owner")
        bot = bot_from_agent(self.store.ensure_main_bot_agent())
        if bot is None:
            raise BotError("bot_main_unavailable", "The main Bot's Agent is unavailable", status=409)
        self.ensure_home(bot, authorization_context=authorization_context)
        return bot

    # writes

    def create_bot(
        self,
        *,
        display_name: Any,
        handle: Optional[str] = None,
        role: Any = None,
        avatar: Any = None,
        model: Optional[str] = None,
        reasoning_effort: Optional[str] = None,
        authorization_context: Any = None,
    ) -> Bot:
        """A new Vibey Agent and its Bot (D4 ``create``): its directory and Session are created with it.

        The Agent is named after the handle. Its role is its description (D1). Without a model it follows the
        main Bot's model and effort (D5).
        """
        context = require_instance_role(authorization_context, "owner")
        name = _clean_display_name(display_name, required=True)
        avatar_record = clean_emoji_avatar(avatar)
        if not str(model or "").strip():
            # The main Bot's model, or Vibey's while the main Bot has none yet.
            for follows in (self.store.get_main_bot_agent(), self.store.get_builtin_default_agent_for_backend("vibey")):
                if follows is not None and str(follows.model or "").strip():
                    model, reasoning_effort = follows.model, reasoning_effort or follows.reasoning_effort
                    break
        requested = str(handle or "").strip() or None
        chosen: dict[str, str] = {}

        def claim(conn: Connection, agent: VibeAgent) -> None:
            # Decided under the writer lock, in the inserting transaction, so two creates cannot take one handle.
            if requested is not None:
                resolved = require_new_handle(conn, requested)
            else:
                resolved = free_handle(conn, fallback_handle_base(name))
            if resolved != agent.normalized_name:
                raise _HandleMoved(resolved)
            chosen["handle"] = resolved

        base = requested or fallback_handle_base(name)
        for _attempt in range(5):
            with self.engine.connect() as conn:
                candidate = require_new_handle(conn, base) if requested else free_handle(conn, base)
            try:
                agent = self.store._create(
                    name=candidate,
                    backend=BOT_BACKEND,
                    description=str(role or "").strip() or None,
                    model=model,
                    reasoning_effort=reasoning_effort,
                    store_metadata={
                        BOT_METADATA_KEY: {
                            "handle": candidate,
                            "display_name": name,
                            "avatar": avatar_record,
                            "position": self._next_position(),
                        }
                    },
                    user_context=context,
                    before_insert=claim,
                )
            except _HandleMoved:
                continue
            break
        else:
            raise BotError("bot_handle_taken", "Could not reserve a Bot handle; try again", status=409)
        bot = bot_from_agent(agent)
        assert bot is not None
        self.ensure_home(bot, authorization_context=context)
        publish_bots_changed(bot.handle)
        return bot

    def set_bot(
        self,
        agent_name: str,
        *,
        display_name: Any,
        avatar: Any = None,
        authorization_context: Any = None,
    ) -> Bot:
        """Make an existing enabled Vibey Agent a Bot (D4 ``set``).

        Its handle is its Agent name, or the handle it had if it was a Bot before, which reconnects its Session and
        directory (D1).
        """
        context = require_instance_role(authorization_context, "owner")
        name = _clean_display_name(display_name, required=True)
        avatar_record = clean_emoji_avatar(avatar)
        try:
            normalized = normalize_agent_name(agent_name)
        except ValueError as exc:
            raise BotError("bot_agent_not_found", f"Agent '{agent_name}' not found", status=404) from exc
        with self.engine.begin() as conn:
            reserve_write_lock(conn)
            row = conn.execute(select(agents).where(agents.c.normalized_name == normalized).limit(1)).mappings().first()
            if row is None or row["archived_at"] is not None:
                raise BotError("bot_agent_not_found", f"Agent '{agent_name}' not found", status=404)
            agent = VibeAgentStore._from_row(row)
            VibeAgentStore._require_manageable_agent(conn, agent, user_context=context)
            if agent.backend != BOT_BACKEND:
                raise BotError(
                    "bot_agent_backend", f"Only Vibey Agents can be Bots; '{agent.name}' runs on {agent.backend}"
                )
            if is_builtin_default_agent(agent):
                # Vibey stays an ordinary worker: listed among Agents, mentionable, and the default (bots.md D9).
                raise BotError("bot_agent_builtin", f"The built-in Agent '{agent.name}' cannot be a Bot", status=409)
            if _is_default_agent(conn, agent):
                raise BotError(
                    "bot_agent_default", f"Agent '{agent.name}' is the default Agent; choose another default first",
                    status=409,
                )
            if not agent.enabled:
                raise BotError("bot_agent_disabled", f"Agent '{agent.name}' is disabled", status=409)
            if agent_bot_record(agent) is not None:
                raise BotError("bot_agent_is_bot", f"Agent '{agent.name}' is already a Bot", status=409)
            previous = agent.metadata.get(BOT_METADATA_KEY)
            previous = dict(previous) if isinstance(previous, dict) else {}
            handle = str(previous.get("handle") or "")
            if not is_valid_handle(handle):
                handle = free_handle(conn, normalize_handle(agent.normalized_name) or fallback_handle_base(name),
                                     agent_id=agent.id)
            record = {
                "handle": handle,
                "display_name": name,
                "avatar": avatar_record if avatar is not None else previous.get("avatar"),
                "position": self._next_position(conn),
            }
            self._write_record(conn, agent, record)
            agent = self._reload(conn, agent.id)
            self._sync_session_title(conn, bot_session_id(handle), name)
        bot = bot_from_agent(agent)
        assert bot is not None
        self.ensure_home(bot, authorization_context=context)
        publish_bots_changed(bot.handle)
        return bot

    def update_bot(
        self,
        handle: str,
        *,
        display_name: Any = ...,
        avatar: Any = ...,
        position: Any = ...,
        authorization_context: Any = None,
    ) -> Bot:
        """Change a Bot's display name, emoji avatar, or position among the other Bots (D5 ``PATCH``)."""
        context = require_instance_role(authorization_context, "owner")
        with self.engine.begin() as conn:
            reserve_write_lock(conn)
            bot = self._require_bot(conn, handle)
            VibeAgentStore._require_manageable_agent(conn, bot.agent, user_context=context)
            record = dict(agent_bot_record(bot.agent) or {})
            if display_name is not ...:
                record["display_name"] = _clean_display_name(display_name, required=not bot.builtin)
            if avatar is not ...:
                record["avatar"] = clean_emoji_avatar(avatar)
            self._write_record(conn, bot.agent, record)
            if position is not ...:
                if bot.builtin:
                    raise BotError("bot_main_position", "The main Bot is always first")
                if isinstance(position, bool) or not isinstance(position, int) or position < 1:
                    raise BotError("bot_position_invalid", "A Bot's position is a whole number from 1")
                self._move(conn, bot.agent.id, position)
            if display_name is not ...:
                self._sync_session_title(conn, bot.session_id, record["display_name"])
            updated = self._require_bot(conn, handle)
        publish_bots_changed(handle)
        return updated

    def remove_bot(self, handle: str, *, authorization_context: Any = None) -> Bot:
        """Drop the Bot role, keeping the Agent, the Session, and the directory (D4 ``remove``)."""
        context = require_instance_role(authorization_context, "owner")
        with self.engine.begin() as conn:
            reserve_write_lock(conn)
            bot = self._require_bot(conn, handle)
            if bot.builtin:
                raise BotError("bot_main_not_removable", "The main Bot cannot be removed", status=409)
            VibeAgentStore._require_manageable_agent(conn, bot.agent, user_context=context)
            record = dict(agent_bot_record(bot.agent) or {})
            record["removed_at"] = _now()
            self._write_record(conn, bot.agent, record)
            self._compact_positions(conn)
        publish_bots_changed(handle)
        return bot

    def set_avatar_image(self, handle: str, data: bytes, *, authorization_context: Any = None) -> Bot:
        """Store an uploaded avatar as ``avatar.png`` in the Bot's directory, scaled to 256px (D5)."""
        require_instance_role(authorization_context, "owner")
        png = scaled_avatar_png(data)
        bot = self.get_bot(handle, authorization_context=authorization_context)
        directory = ensure_bot_directory(bot.handle)
        target = directory / AVATAR_FILENAME
        temporary = directory / f".{AVATAR_FILENAME}.tmp"
        temporary.write_bytes(png)
        temporary.replace(target)
        with self.engine.begin() as conn:
            reserve_write_lock(conn)
            bot = self._require_bot(conn, handle)
            record = dict(agent_bot_record(bot.agent) or {})
            record["avatar"] = {"kind": "image"}
            self._write_record(conn, bot.agent, record)
            updated = self._require_bot(conn, handle)
        publish_bots_changed(handle)
        return updated

    def avatar_path(self, handle: str, *, authorization_context: Any = None) -> Path:
        bot = self.get_bot(handle, authorization_context=authorization_context)
        path = bot.directory / AVATAR_FILENAME
        if (bot.avatar or {}).get("kind") != "image" or not path.is_file():
            raise BotError("bot_avatar_missing", f"Bot '{handle}' has no uploaded avatar", status=404)
        return path

    # internals

    @staticmethod
    def _reload(conn: Connection, agent_id: str) -> VibeAgent:
        return VibeAgentStore._from_row(conn.execute(select(agents).where(agents.c.id == agent_id)).mappings().one())

    @staticmethod
    def _write_record(conn: Connection, agent: VibeAgent, record: dict[str, Any]) -> None:
        current = conn.execute(select(agents.c.metadata_json).where(agents.c.id == agent.id)).scalar_one()
        try:
            metadata = json.loads(current or "{}")
        except (TypeError, ValueError):
            metadata = {}
        if not isinstance(metadata, dict):
            metadata = {}
        metadata[BOT_METADATA_KEY] = record
        conn.execute(
            update(agents)
            .where(agents.c.id == agent.id)
            .values(metadata_json=json.dumps(metadata, ensure_ascii=False, separators=(",", ":")), updated_at=_now())
        )

    def _next_position(self, conn: Optional[Connection] = None) -> int:
        if conn is None:
            with self.engine.connect() as fresh:
                return self._next_position(fresh)
        others = [bot.position for bot in list_bots_in(conn) if not bot.builtin]
        return max(others, default=0) + 1

    def _move(self, conn: Connection, agent_id: str, position: int) -> None:
        ordered = [bot for bot in list_bots_in(conn) if not bot.builtin]
        moving = next(bot for bot in ordered if bot.agent.id == agent_id)
        ordered.remove(moving)
        ordered.insert(min(position, len(ordered) + 1) - 1, moving)
        self._renumber(conn, ordered)

    def _compact_positions(self, conn: Connection) -> None:
        self._renumber(conn, [bot for bot in list_bots_in(conn) if not bot.builtin])

    def _renumber(self, conn: Connection, ordered: Iterable[Bot]) -> None:
        for index, bot in enumerate(ordered, start=1):
            if bot.position != index:
                record = dict(agent_bot_record(self._reload(conn, bot.agent.id)) or {})
                record["position"] = index
                self._write_record(conn, bot.agent, record)

    @staticmethod
    def _sync_session_title(conn: Connection, session_id: str, display_name: str) -> None:
        """A Bot's Session is titled by its display name; the main Bot's empty name clears it (the UI's default)."""
        conn.execute(
            update(agent_sessions)
            .where(agent_sessions.c.id == session_id)
            .values(
                title=display_name or None,
                updated_at=datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
            )
        )


def _is_default_agent(conn: Connection, agent: VibeAgent) -> bool:
    """Whether the instance's recorded default Agent is ``agent``: new chats start on it, so it cannot be a Bot."""
    name = VibeAgentStore._default_agent_name(conn)
    try:
        return bool(name) and normalize_agent_name(name) == agent.normalized_name
    except ValueError:
        return False


class _HandleMoved(Exception):
    """The handle checked before the insert was taken by the time the insert held the lock."""

    def __init__(self, handle: str) -> None:
        super().__init__(handle)
        self.handle = handle