Skip to content

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

24.5 KB
Raw Blame
"""A management app wired the way `main` wires it, against the test database.

The agent bridge side is a bare FastAPI app behind the real
`BearerAuthMiddleware` with the real `ManagementAuthenticator`; the gateway
side is mounted at `/gateway` with the real `get_current_user`. Only what
those need from the rest of the server is stubbed: the agent bridge's session
and protocol, and the gateway's config. The protocol is a real
`AgentCore` with its collaborators faked out, so registration writes
real rows, and with a real connection registry and event buffer, so the
controller stream and the act-as routes run against Core's own state. The
agent routes are mounted too, for a controller to act on.

Requests go through `httpx.AsyncClient` over `ASGITransport`, for the reason
`gateway/test_tenant_resolution.py` gives.
"""

from __future__ import annotations

import asyncio
import json
import uuid
from collections.abc import AsyncIterator, Callable
from dataclasses import dataclass, field
from datetime import UTC, datetime, timedelta
from pathlib import Path
from types import SimpleNamespace
from typing import Any

import httpx
from fastapi import FastAPI
from sqlalchemy import insert
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker

from switch_core.bridges.agent import dependencies as bridge_deps
from switch_core.bridges.agent.api.activity_routes import router as activity_router
from switch_core.bridges.agent.api.handlers import router as api_router
from switch_core.bridges.agent.api.operations import router as operations_router
from switch_core.bridges.agent.api_key_cache import ApiKeyCache
from switch_core.bridges.agent.auth import BearerAuthMiddleware, ControllerPrincipal
from switch_core.bridges.agent.controller_auth_cache import ControllerAuthCache
from switch_core.bridges.agent.protocol.agent_connections import AgentConnectionRegistry
from switch_core.bridges.agent.protocol.agent_core import AgentCore
from switch_core.bridges.agent.protocol.controller_presence import (
    ControllerConnectionError,
)
from switch_core.bridges.agent.protocol.controller_stream import IDLE
from switch_core.config import ControllerRelease
from switch_core.connections.broker import ServiceBroker
from switch_core.db.models import (
    TENANT_ZERO_ID,
    Client,
    Room,
    TenantMember,
    User,
    room_agents,
)
from switch_core.db.stores.agent_session_store import AgentSessionStore
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.api_key_store import ApiKeyStore
from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.switch_core_process_store import SwitchCoreProcessStore
from switch_core.db.stores.template_store import TemplateStore
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway import dependencies as gw_deps
from switch_core.gateway.auth import create_jwt
from switch_core.gateway.providers import router as providers_router
from switch_core.keys import Keyring
from switch_core.management import controller_routes
from switch_core.management.dependencies import get_authenticator, get_management
from switch_core.management.errors import ManagementError
from switch_core.management.wiring import Management, build_management
from switch_core.process_lease import ProcessLease
from switch_core.signals import SignalBus
from switch_core.user_changes import LocalUserChanges, SignalUserChanges
from tests.db_buffer import db_buffer_on
from tests.switch_core.connections.fake_vendor import FakeVendor
from tests.switch_core.connections.github_seed import github_broker

TEST_KEYRING = Keyring.parse("test:" + "x" * 40, legacy_secret=None)

TOKEN_SECRET = "unit-test-controller-token-secret-0123456789"  # gitleaks:allow
STATUS_INTERVAL = 60
SERVER_URL = "https://switch-api.example.test"

FIXTURES = Path(__file__).resolve().parents[1] / "fixtures" / "agent_controllers"


def fixture(name: str) -> Any:
    return json.loads((FIXTURES / name).read_text())


# Where the status fixture's controller says it makes agents' workspaces.
WORKSPACES_DIR: str = fixture("status_request.json")["machine"]["workspaces_dir"]


@dataclass
class Clock:
    """A clock a test moves by hand."""

    now: datetime = field(default_factory=lambda: datetime.now(UTC))

    def __call__(self) -> datetime:
        return self.now

    def advance(self, **delta: float) -> None:
        self.now = self.now + timedelta(**delta)


class _FakeClientLifecycle:
    def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
        self._session_factory = session_factory

    async def stop(self, client_id: str) -> None:
        return None

    async def delete_record(self, session: AsyncSession, client_id: str) -> None:
        return None

    async def create_client(self, *, client_type: str, display_name: str) -> Client:
        async with self._session_factory() as session:
            client = Client(
                transport_user_id=f"@{display_name}:test",
                display_name=display_name,
                type=client_type,
            )
            session.add(client)
            await session.commit()
            return client

    def start_client(self, client: Client) -> None:
        return None

    def announce(self, tenant_id: str, client_ids: object = None) -> None:
        return None

    def get_by_agent_id(self, agent_id: str) -> None:
        """No client is ever started here."""
        return None

    def get(self, client_id: str) -> None:
        """No client is ever started here, so a rename has no actor to tell."""
        return None


class _NoBridges:
    def bridges_for_tenant(self, tenant_id: str) -> list[object]:
        return []


def protocol_service(
    session_factory: async_sessionmaker[AsyncSession], cache: ApiKeyCache
) -> AgentCore:
    svc = object.__new__(AgentCore)
    svc.session_factory = session_factory  # type: ignore[assignment]
    svc.agent_store = AgentStore()
    svc.api_key_store = ApiKeyStore()
    svc.api_key_cache = cache
    svc.client_lifecycle = _FakeClientLifecycle(session_factory)  # type: ignore[assignment]
    svc.collab_lifecycle = _NoBridges()  # type: ignore[assignment]
    svc.config = SimpleNamespace(  # type: ignore[assignment]
        keyring=TEST_KEYRING, third_party_avatars_enabled=True
    )
    svc.telemetry = None
    svc.event_buffer = db_buffer_on(session_factory)
    svc.connections = AgentConnectionRegistry()
    svc.approval_outcomes = None  # type: ignore[assignment]
    svc.room_store = RoomStore()
    svc.agent_session_store = AgentSessionStore()
    svc.user_store = UserStore()
    svc.room_role_store = RoomRoleStore()
    return svc


@dataclass
class Harness:
    app: FastAPI
    # Mounted at `/gateway` on `app`, for a test to add routes to.
    gateway_app: FastAPI
    management: Management
    # This process's signal bus, started only by a test that runs several
    # processes against one database.
    bus: SignalBus
    protocol: AgentCore
    cache: ApiKeyCache
    controller_auth_cache: ControllerAuthCache
    clock: Clock
    session_factory: async_sessionmaker[AsyncSession]
    user_changes: LocalUserChanges
    broker: ServiceBroker
    vendor: FakeVendor

    def client(self) -> httpx.AsyncClient:
        return httpx.AsyncClient(
            transport=httpx.ASGITransport(app=self.app), base_url="http://test"
        )

    def middleware(self) -> BearerAuthMiddleware:
        async def _app(scope: Any, receive: Any, send: Any) -> None:
            return None

        return BearerAuthMiddleware(
            _app,
            agent_store=AgentStore(),
            api_key_store=ApiKeyStore(),
            api_key_cache=self.cache,
            session_factory=self.session_factory,
            controller_auth=self.management.authenticator,
        )


def _no_listening_engine() -> Any:
    raise AssertionError("the harness's signal bus is never started")


def build_harness(
    session_factory: async_sessionmaker[AsyncSession],
    *,
    controller_auth_ttl_seconds: float = 5,
    server_url: str | None = SERVER_URL,
    third_party_avatars: bool = True,
    controller_release: ControllerRelease | None = None,
    signal_engine: Callable[[], Any] = _no_listening_engine,
) -> Harness:
    """The controller-token cache is on, as it is by default in production,
    so every management test runs through it."""
    clock = Clock()
    cache = ApiKeyCache(ttl_seconds=5, max_entries=64)
    controller_auth_cache = ControllerAuthCache(
        ttl_seconds=controller_auth_ttl_seconds, max_entries=64
    )
    protocol = protocol_service(session_factory, cache)
    process_id = str(uuid.uuid4())
    signal_bus = SignalBus(session_factory, signal_engine, process_id=process_id)
    user_changes = LocalUserChanges()
    management = build_management(
        token_secret=TOKEN_SECRET,
        status_interval_seconds=STATUS_INTERVAL,
        server_url=server_url,
        third_party_avatars=third_party_avatars,
        controller_release=controller_release,
        session_factory=session_factory,
        presence=protocol.connections.controllers,
        auth_cache=controller_auth_cache,
        clock=clock,
        # Never started unless a test runs several processes: with one, every
        # nudge is delivered locally and what it would publish goes nowhere.
        signal_bus=signal_bus,
        lease=ProcessLease(
            process_id=process_id,
            session_factory=session_factory,
            processes=SwitchCoreProcessStore(),
            key_ids=[key.id for key in TEST_KEYRING.keys],
        ),
        user_changes=SignalUserChanges(local=user_changes, bus=signal_bus),
    )

    async def _session() -> AsyncIterator[AsyncSession]:
        async with session_factory() as session:
            yield session

    agent_app = FastAPI()
    gateway_app = FastAPI()
    gateway_app.include_router(providers_router)
    vendor = FakeVendor()
    broker = github_broker(session_factory, TEST_KEYRING, vendor)
    agent_app.state.service_broker = broker
    gateway_app.state.service_broker = broker
    management.install(
        agent_bridge_app=agent_app, gateway_app=gateway_app, protocol=protocol
    )
    # `install` sets management's request dependencies in module state, one
    # per process, and two harnesses in one test are two processes: each app
    # is pointed at its own, or the first's routes record what they do as the
    # second process.
    for app in (agent_app, gateway_app):
        app.dependency_overrides[get_management] = lambda: management.service
        app.dependency_overrides[get_authenticator] = lambda: management.authenticator

    agent_app.include_router(activity_router)
    agent_app.include_router(api_router, prefix="/agents")
    agent_app.include_router(operations_router)
    agent_app.dependency_overrides[bridge_deps.get_session] = _session
    agent_app.dependency_overrides[bridge_deps.get_session_factory] = lambda: (
        session_factory
    )
    agent_app.dependency_overrides[bridge_deps.get_protocol] = lambda: protocol

    gateway_app.dependency_overrides[gw_deps.get_session] = _session
    gateway_app.dependency_overrides[gw_deps.get_session_factory] = lambda: (
        session_factory
    )
    gateway_app.dependency_overrides[gw_deps.get_user_store] = lambda: UserStore()
    gateway_app.dependency_overrides[gw_deps.get_protocol] = lambda: protocol
    gateway_app.dependency_overrides[gw_deps.get_template_store] = lambda: (
        TemplateStore()
    )
    gateway_app.dependency_overrides[gw_deps.get_config] = lambda: SimpleNamespace(
        keyring=TEST_KEYRING,
        gateway_tenant_choice_enabled=False,
        third_party_avatars_enabled=third_party_avatars,
        feature_flags={"agent_management": True, "switch_buddy": True},
    )
    agent_app.mount("/gateway", gateway_app)
    agent_app.add_middleware(
        BearerAuthMiddleware,
        agent_store=AgentStore(),
        api_key_store=ApiKeyStore(),
        api_key_cache=cache,
        session_factory=session_factory,
        controller_auth=management.authenticator,
    )
    return Harness(
        app=agent_app,
        gateway_app=gateway_app,
        management=management,
        bus=signal_bus,
        protocol=protocol,
        cache=cache,
        controller_auth_cache=controller_auth_cache,
        clock=clock,
        session_factory=session_factory,
        user_changes=user_changes,
        broker=broker,
        vendor=vendor,
    )


async def add_member(
    session_factory: async_sessionmaker[AsyncSession],
    name: str,
    tenant_id: str = TENANT_ZERO_ID,
) -> User:
    async with session_factory() as session:
        user = User(name=name, email=f"{name}@example.invalid", role="user")
        session.add(user)
        await session.flush()
        session.add(TenantMember(tenant_id=tenant_id, user_id=user.id, role="member"))
        await session.commit()
        return user


def cookies_for(user: User, tenant_id: str = TENANT_ZERO_ID) -> dict[str, str]:
    return {
        "switch_auth": create_jwt(
            user.id,
            user.email,
            user.role,
            TEST_KEYRING,
            tenant_id,
            session_version=0,
            auth_time=datetime.now(UTC),
        )
    }


def bearer(token: str) -> dict[str, str]:
    return {"Authorization": f"Bearer {token}"}


def platform() -> dict[str, str]:
    return {"os": "linux", "arch": "x64", "os_version": "6.1.0"}


def status_report(
    seq: int,
    *,
    providers: list[dict[str, Any]] | None = None,
    agents: list[dict[str, Any]] | None = None,
) -> dict[str, Any]:
    """The status fixture, with its sequence and optionally its lists replaced."""
    report = fixture("status_request.json")
    report["seq"] = seq
    if providers is not None:
        report["providers"] = providers
    if agents is not None:
        report["agents"] = agents
    return report


def provider(
    name: str,
    *,
    installed: bool = True,
    auth: str = "ok",
    auth_problem: str | None = None,
) -> dict[str, Any]:
    return {
        "provider": name,
        "installed": installed,
        "version": "1.0.0" if installed else None,
        "auth": auth,
        "auth_source": "local" if installed else None,
        "checked_at": "2026-01-01T00:00:00Z",
        **({"auth_problem": auth_problem} if auth_problem else {}),
    }


@dataclass
class EnrolledController:
    controller_id: str
    credential: str
    access_token: str
    owner: User
    # To connect the controller as a running one is connected.
    harness: Harness

    @property
    def headers(self) -> dict[str, str]:
        return bearer(self.access_token)


async def enroll_console(
    harness: Harness, client: httpx.AsyncClient, owner: User, name: str = "laptop"
) -> EnrolledController:
    """Enroll a console controller for `owner` and exchange its credential."""
    response = await client.post(
        "/gateway/management/controllers",
        json={
            "name": name,
            "kind": "console",
            "platform": platform(),
            "version": "0.1.0",
        },
        cookies=cookies_for(owner),
    )
    assert response.status_code == 201, response.text
    body = response.json()
    token = await client.post(
        f"/v1/management/controllers/{body['controller_id']}/token",
        json={"credential": body["credential"]},
    )
    assert token.status_code == 200, token.text
    return EnrolledController(
        controller_id=body["controller_id"],
        credential=body["credential"],
        access_token=token.json()["access_token"],
        owner=owner,
        harness=harness,
    )


async def enroll_daemon(
    harness: Harness, client: httpx.AsyncClient, owner: User, name: str = "build-box"
) -> EnrolledController:
    """Enroll a headless controller for `owner` with a one-time code, as
    `switch-agent-controller enroll` does, and exchange its credential."""
    code = await client.post(
        "/gateway/management/enrollment-codes", cookies=cookies_for(owner)
    )
    assert code.status_code == 201, code.text
    body = fixture("enroll_request.json")
    body["proof"]["code"] = code.json()["code"]
    body["controller"]["name"] = name
    enrolled = await client.post("/v1/management/controllers/enroll", json=body)
    assert enrolled.status_code == 201, enrolled.text
    controller_id = enrolled.json()["controller_id"]
    credential = enrolled.json()["credential"]
    token = await client.post(
        f"/v1/management/controllers/{controller_id}/token",
        json={"credential": credential},
    )
    assert token.status_code == 200, token.text
    return EnrolledController(
        controller_id=controller_id,
        credential=credential,
        access_token=token.json()["access_token"],
        owner=owner,
        harness=harness,
    )


async def report_status(
    client: httpx.AsyncClient,
    controller: EnrolledController,
    seq: int,
    *,
    providers: list[dict[str, Any]] | None = None,
    agents: list[dict[str, Any]] | None = None,
) -> httpx.Response:
    """Report status as a running controller does: one whose socket is
    attached, connected first unless it already is."""
    await ensure_connected(client, controller)
    return await report_status_only(
        client, controller, seq, providers=providers, agents=agents
    )


async def report_status_only(
    client: httpx.AsyncClient,
    controller: EnrolledController,
    seq: int,
    *,
    providers: list[dict[str, Any]] | None = None,
    agents: list[dict[str, Any]] | None = None,
) -> httpx.Response:
    """Report status without opening a connection."""
    return await client.put(
        f"/v1/management/controllers/{controller.controller_id}/status",
        json=status_report(seq, providers=providers, agents=agents),
        headers=controller.headers,
    )


def definition(provider_name: str = "claude", **overrides: Any) -> dict[str, Any]:
    return {
        "provider": provider_name,
        "model": None,
        "instructions": "",
        "auto_mode": True,
        "auto_approve": False,
        "directory": None,
        "isolation": "shared",
        **overrides,
    }


async def create_managed_agent(
    client: httpx.AsyncClient,
    owner: User,
    *,
    name: str,
    controller_id: str | None,
    desired_state: str = "running",
    definition_body: dict[str, Any] | None = None,
) -> httpx.Response:
    return await client.post(
        "/gateway/management/agents",
        json={
            "name": name,
            "description": f"{name} description",
            "controller_id": controller_id,
            "desired_state": desired_state,
            "definition": definition_body or definition(),
        },
        cookies=cookies_for(owner),
    )


async def place_agent(
    client: httpx.AsyncClient,
    controller: EnrolledController,
    *,
    name: str,
) -> str:
    """Create a managed agent on `controller`, which must accept placements."""
    await report_status(client, controller, 1, providers=[provider("claude")])
    created = await create_managed_agent(
        client,
        controller.owner,
        name=name,
        controller_id=controller.controller_id,
        definition_body=definition(),
    )
    assert created.status_code == 201, created.text
    return str(created.json()["agent_id"])


async def add_room(
    session_factory: async_sessionmaker[AsyncSession],
    *agent_ids: str,
    name: str = "room",
) -> str:
    """A room with these agents as members."""
    async with session_factory() as session:
        room = Room(
            transport_room_id=f"!{uuid.uuid4().hex}:test.local",
            name=name,
            description=f"{name} description",
        )
        session.add(room)
        await session.flush()
        for agent_id in agent_ids:
            await session.execute(
                insert(room_agents).values(room_id=room.id, agent_id=agent_id)
            )
        await session.commit()
        return room.id


def parse_frame(frame: dict[str, Any]) -> tuple[str, dict[str, Any]]:
    return frame["event"], frame["data"]


async def take(
    stream: AsyncIterator[dict[str, Any]], count: int, timeout: float = 3.0
) -> list[tuple[str, dict[str, Any]]]:
    """The next `count` frames off a stream, idle ticks skipped."""
    frames: list[tuple[str, dict[str, Any]]] = []

    async def pump() -> None:
        while len(frames) < count:
            raw = await anext(stream)
            if raw is IDLE:
                continue
            frames.append(parse_frame(raw))

    await asyncio.wait_for(pump(), timeout=timeout)
    return frames


@dataclass
class Answer:
    """What the socket would have said, shaped like an HTTP response: a beat
    or an attach either succeeds or is refused with the contract's envelope."""

    status_code: int
    body: dict[str, Any]

    @property
    def text(self) -> str:
        return json.dumps(self.body)

    def json(self) -> dict[str, Any]:
        return self.body


def _principal(controller: EnrolledController) -> ControllerPrincipal:
    return ControllerPrincipal(
        controller_id=controller.controller_id,
        owner_id=controller.owner.id,
        tenant_id=TENANT_ZERO_ID,
    )


async def open_connection(
    client: httpx.AsyncClient,
    controller: EnrolledController,
    cursors: dict[str, int | str] | None = None,
) -> dict[str, Any]:
    response = await client.post(
        f"/v1/controllers/{controller.controller_id}/connection",
        json={"cursors": cursors or {}},
        headers=controller.headers,
    )
    assert response.status_code == 201, response.text
    return dict(response.json())


async def connect(
    client: httpx.AsyncClient, controller: EnrolledController
) -> dict[str, Any]:
    """Connect the controller as its socket would, and record it: the
    connection opened, its socket attached, this process's lease claimed and
    the transition written. Returns the open's response."""
    harness = controller.harness
    opened = await open_connection(client, controller)
    presence = harness.protocol.connections.controllers
    conn = presence.current_connection(controller.controller_id)
    assert conn is not None
    presence.attach_stream(conn)
    await harness.management.lease.renew()
    await harness.management.ledger.flush_all()
    return opened


async def ensure_connected(
    client: httpx.AsyncClient, controller: EnrolledController
) -> None:
    """Connect the controller unless its socket is already attached, and
    record it either way."""
    harness = controller.harness
    presence = harness.protocol.connections.controllers
    conn = presence.current_connection(controller.controller_id)
    if conn is None or not conn.stream_attached:
        await connect(client, controller)
        return
    await harness.management.lease.renew()
    await harness.management.ledger.flush_all()


async def open_stream(
    harness: Harness,
    controller: EnrolledController,
    opened: dict[str, Any],
) -> AsyncIterator[dict[str, Any]]:
    """The frames the controller's socket would send, from the route's own
    stream: the socket adds only pings around them."""
    return await controller_routes.attach_stream(
        principal=_principal(controller),
        management=harness.management.service,
        protocol=harness.protocol,
        session_factory=harness.session_factory,
        connection_id=opened["connection_id"],
        generation=opened["generation"],
    )


async def attach(
    harness: Harness,
    controller: EnrolledController,
    connection_id: str,
    generation: int,
) -> Answer:
    """An attach, answered as the socket's `refused` frame would be."""
    try:
        stream = await open_stream(
            harness,
            controller,
            {"connection_id": connection_id, "generation": generation},
        )
    except ManagementError as error:
        return Answer(error.status_code, error.body())
    await stream.aclose()  # type: ignore[attr-defined]
    return Answer(200, {})


async def beat(
    harness: Harness,
    controller: EnrolledController,
    *,
    connection_id: str,
    generation: int,
    cursors: dict[str, int],
) -> Answer:
    """A pong, answered as the socket would: the agents on success, the
    refusal its `evicted` frame would name otherwise."""
    try:
        agents = await controller_routes.record_beat(
            principal=_principal(controller),
            protocol=harness.protocol,
            connection_id=connection_id,
            generation=generation,
            cursors=cursors,
        )
    except ControllerConnectionError as exc:
        error = controller_routes._connection_refusal(exc)
        return Answer(error.status_code, error.body())
    return Answer(200, {"agents": agents})