app.py

"""Full Hub application with both API and GUI routes.

This module is for LOCAL DEVELOPMENT ONLY. It includes:
- All API routes from api_app.py
- GUI routes (login, callback, logout, home, profile, livekit-test, agent detail)

For Lambda deployment, use api_app.py instead (via lambda_handler.py).
"""

from __future__ import annotations

import base64
import dataclasses
import html
import json
import logging
import os
import secrets
import uuid
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Optional

from agent_hub.action_service import (
    ActionServiceError,
    approve_action,
    create_action,
    load_action,
    mark_action_completed,
    record_action_dispatch_started,
    reject_action,
    reserve_action_for_execution,
)
from agent_hub.auth import (
    AuthenticatedUser,
    ensure_user_row,
    list_cognito_users,
    lookup_cognito_user_by_email,
)
from agent_hub.broadcast import broadcast_event
from agent_hub.cognito import (
    CognitoAuthError,
    CognitoUserInfo,  # noqa: F401 — used via module attr in tests
    build_login_url,
    build_logout_url,
    get_user_info_from_tokens,
)
from agent_hub.livekit_tokens import mint_livekit_join_token  # noqa: F401 — used via module attr in tests
from agent_hub.memberships import (
    SpaceInfo,  # noqa: F401 — used via module attr in tests
    check_agent_permission,
    grant_membership,
    list_agents_for_user,
    list_spaces_for_user,
    revoke_membership,
    update_membership,
)
from agent_hub.memory_taxonomy import (
    classify_memory_kinds,
    memory_kind_options,
    normalize_memory_kind,
)
from agent_hub.personas import DEFAULT_AGENT_PERSONA_INSTRUCTIONS, DEFAULT_AGENT_PERSONA_NAME
from agent_hub.secrets import get_secret_json
from agent_hub.session_tokens import mint_ws_session_token

# Import the API app and its shared state
from api_app import (
    LiveKitTokenIn,
    LiveKitTokenOut,
    _get_db,
    _get_s3,
    _get_sqs,
    _mint_livekit_token_for_user,
    _session_secret,
    api_app,
    get_config,
)
from daylily_auth_cognito.browser.session import (
    CONFIG_STATE_KEY,
    CognitoWebAuthError,
    CognitoWebSessionConfig,
    SessionPrincipal,
    clear_session_principal,
    complete_cognito_callback,
    load_session_principal,
)
from daylily_tapdb.web import TapdbHostBridge, TapdbHostNavLink, create_tapdb_dag_router, create_tapdb_web_app
from fastapi import FastAPI as _FastAPI
from fastapi import HTTPException, Request
from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse, RedirectResponse
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates
from pydantic import BaseModel, Field
from starlette.responses import Response

logger = logging.getLogger(__name__)
logging.basicConfig(level=os.getenv("LOG_LEVEL", "INFO"))
# Avoid leaking AWS response payloads (can include secrets) in local logs.
for _name in ("botocore", "urllib3", "httpcore", "httpx"):
    logging.getLogger(_name).setLevel(logging.WARNING)


# -----------------------------
# Startup Configuration Validation
# -----------------------------


class ConfigurationError(Exception):
    """Raised when critical configuration is missing or invalid."""

    pass


def _is_placeholder(value: str | None) -> bool:
    """Check if a value is a placeholder or empty."""
    if not value:
        return True
    v = str(value).strip().upper()
    return v in ("", "REPLACE_ME", "CHANGEME", "TODO", "XXX", "YOUR_KEY_HERE", "YOUR_SECRET_HERE")


def _validate_critical_secrets(cfg) -> list[str]:
    """Validate all critical secrets at startup.

    Returns a list of configuration errors. Empty list means all valid.
    """
    errors: list[str] = []

    # 1. Cognito Configuration
    if not cfg.cognito_user_pool_id:
        errors.append("COGNITO_USER_POOL_ID not set")
    if not cfg.cognito_user_pool_client_id:
        errors.append("COGNITO_APP_CLIENT_ID not set")
    if not cfg.cognito_domain:
        errors.append("COGNITO_DOMAIN not set")

    # 2. Database Configuration (required for any operation)
    if not cfg.db_resource_arn:
        errors.append("DB_RESOURCE_ARN not set")
    if not cfg.db_secret_arn:
        errors.append("DB_SECRET_ARN not set")

    # 3. LiveKit Configuration (required for voice/video features)
    if not cfg.livekit_url:
        errors.append("LIVEKIT_URL not set")
    if not cfg.livekit_secret_arn:
        errors.append("LIVEKIT_SECRET_ARN not set")
    else:
        try:
            # Clear cache to get fresh value
            get_secret_json.cache_clear()
            lk_secret = get_secret_json(cfg.livekit_secret_arn)
            lk_api_key = lk_secret.get("api_key", "")
            lk_api_secret = lk_secret.get("api_secret", "")
            if _is_placeholder(lk_api_key):
                errors.append("LiveKit api_key is a placeholder (REPLACE_ME). Update secret in AWS Secrets Manager.")
            if _is_placeholder(lk_api_secret):
                errors.append("LiveKit api_secret is a placeholder (REPLACE_ME). Update secret in AWS Secrets Manager.")
        except Exception as e:
            errors.append(f"Failed to read LiveKit secret: {e}")

    # 4. OpenAI Configuration (required for embeddings/AI features)
    if cfg.openai_secret_arn:
        try:
            # Clear cache to get fresh value
            get_secret_json.cache_clear()
            openai_secret = get_secret_json(cfg.openai_secret_arn)
            openai_api_key = openai_secret.get("api_key", "")
            if _is_placeholder(openai_api_key):
                errors.append("OpenAI api_key is a placeholder (REPLACE_ME). Update secret in AWS Secrets Manager.")
        except Exception as e:
            errors.append(f"Failed to read OpenAI secret: {e}")

    # 5. Session Secret (required for secure sessions)
    if not cfg.session_secret_key and not cfg.session_secret_arn:
        errors.append(
            "SESSION_SECRET_KEY or SESSION_SECRET_ARN not set - sessions will use random key (not persistent)"
        )

    return errors


def validate_configuration_or_fail():
    """Validate all critical configuration and fail hard if any issues.

    This is called at startup to ensure the GUI won't run with misconfigured secrets.
    """
    cfg = get_config()
    errors = _validate_critical_secrets(cfg)

    if errors:
        logger.critical("Critical configuration validation failed with %d issue(s).", len(errors))
        raise ConfigurationError("Critical configuration validation failed.")


# Use the API app as the base - all API routes are already defined
app = api_app

# Get config from api_app
_cfg = get_config()

# Setup Jinja2 templates and static files
_TEMPLATES_DIR = Path(__file__).parent / "templates"
_STATIC_DIR = Path(__file__).parent / "static"

# Mount static files
app.mount("/static", StaticFiles(directory=str(_STATIC_DIR)), name="static")

# Setup Jinja2 templates
templates = Jinja2Templates(directory=str(_TEMPLATES_DIR))


@dataclass(frozen=True)
class TapdbRuntimeConfig:
    config_path: str
    env_name: str


class MarvainTapdbConfigError(RuntimeError):
    """Raised when the embedded TapDB runtime is not configured."""


_tapdb_web_asgi_app: Any | None = None
_tapdb_dag_asgi_app: Any | None = None
_TAPDB_MOUNT_PATH = "/tapdb"


def _requested_app_path(scope: dict[str, Any]) -> str:
    root_path = str(scope.get("root_path") or "").rstrip("/")
    path = str(scope.get("path") or "") or "/"
    target = f"{root_path}{path}" or "/"
    query_string = scope.get("query_string") or b""
    if query_string:
        target = f"{target}?{query_string.decode('utf-8')}"
    return target


def _tapdb_child_scope(scope: dict[str, Any], user: AuthenticatedUser) -> dict[str, Any]:
    scoped = dict(scope)
    path = str(scoped.get("path") or "")
    if path == _TAPDB_MOUNT_PATH:
        scoped["path"] = "/"
    elif path.startswith(f"{_TAPDB_MOUNT_PATH}/"):
        scoped["path"] = path[len(_TAPDB_MOUNT_PATH) :]

    root_path = str(scoped.get("root_path") or "").rstrip("/")
    if not root_path.endswith(_TAPDB_MOUNT_PATH):
        scoped["root_path"] = f"{root_path}{_TAPDB_MOUNT_PATH}"
    scoped["marvain_authenticated_user"] = user
    scoped["tapdb_host_user"] = _tapdb_user_payload(user)
    return scoped


def _resolve_tapdb_runtime_config() -> TapdbRuntimeConfig:
    config_path = str(os.getenv("MARVAIN_TAPDB_CONFIG_PATH") or os.getenv("TAPDB_CONFIG_PATH") or "").strip()
    if not config_path:
        raise MarvainTapdbConfigError(
            "TapDB runtime is not configured. Set TAPDB_CONFIG_PATH or MARVAIN_TAPDB_CONFIG_PATH."
        )

    resolved = Path(config_path).expanduser().resolve()
    if not resolved.exists():
        raise MarvainTapdbConfigError(f"TapDB config file not found: {resolved}")

    env_name = str(os.getenv("MARVAIN_TAPDB_ENV") or os.getenv("TAPDB_ENV") or _cfg.stage or "").strip()
    if not env_name:
        raise MarvainTapdbConfigError("TapDB environment is not configured. Set TAPDB_ENV or MARVAIN_TAPDB_ENV.")

    return TapdbRuntimeConfig(config_path=str(resolved), env_name=env_name)


def _tapdb_user_payload(user: AuthenticatedUser) -> dict[str, Any]:
    return {
        "uid": str(user.user_id),
        "username": str(user.email),
        "email": str(user.email),
        "display_name": str(user.email),
        "role": "admin",
        "is_active": True,
    }


def _tapdb_host_user(request: Request) -> dict[str, Any] | None:
    scoped_tapdb_user = request.scope.get("tapdb_host_user")
    if isinstance(scoped_tapdb_user, dict):
        return scoped_tapdb_user
    scoped_user = request.scope.get("marvain_authenticated_user")
    user = scoped_user if isinstance(scoped_user, AuthenticatedUser) else _gui_get_user(request)
    if not user:
        return None
    return _tapdb_user_payload(user)


def _tapdb_host_bridge() -> TapdbHostBridge:
    return TapdbHostBridge(
        auth_mode="host_session",
        service_name="marvain",
        app_name="TapDB",
        shell_title="Marvain TapDB",
        shell_subtitle="Native semantic graph",
        home_url="/",
        login_url="/login",
        logout_url="/logout",
        resolve_user=_tapdb_host_user,
        nav_links=(TapdbHostNavLink(label="Marvain", href="/"),),
    )


def _build_tapdb_web_asgi_app() -> Any:
    cfg = _resolve_tapdb_runtime_config()
    return create_tapdb_web_app(
        config_path=cfg.config_path,
        env_name=cfg.env_name,
        host_bridge=_tapdb_host_bridge(),
    )


def _get_tapdb_web_asgi_app() -> Any:
    global _tapdb_web_asgi_app
    if _tapdb_web_asgi_app is None:
        _tapdb_web_asgi_app = _build_tapdb_web_asgi_app()
    return _tapdb_web_asgi_app


def _build_tapdb_dag_asgi_app() -> _FastAPI:
    cfg = _resolve_tapdb_runtime_config()
    dag_app = _FastAPI()
    router = create_tapdb_dag_router(
        config_path=cfg.config_path,
        env_name=cfg.env_name,
        service_name="marvain",
    )
    dag_app.include_router(router)
    return dag_app


def _get_tapdb_dag_asgi_app() -> Any:
    global _tapdb_dag_asgi_app
    if _tapdb_dag_asgi_app is None:
        _tapdb_dag_asgi_app = _build_tapdb_dag_asgi_app()
    return _tapdb_dag_asgi_app


def _tapdb_config_error_response(exc: Exception) -> JSONResponse:
    logger.info("TapDB runtime configuration unavailable: %s", exc.__class__.__name__)
    return JSONResponse(
        status_code=503,
        content={
            "detail": "TapDB runtime is not configured. Set TAPDB_CONFIG_PATH or MARVAIN_TAPDB_CONFIG_PATH.",
            "code": "tapdb_runtime_not_configured",
        },
    )


def _tapdb_runtime_error_response(_exc: Exception) -> JSONResponse:
    return JSONResponse(
        status_code=503,
        content={
            "detail": (
                "TapDB runtime is not available. Check TAPDB_CONFIG_PATH or MARVAIN_TAPDB_CONFIG_PATH "
                "and TAPDB_ENV or MARVAIN_TAPDB_ENV."
            ),
            "code": "tapdb_runtime_unavailable",
        },
    )


async def _dispatch_asgi_app(asgi_app: Any, request: Request) -> Response:
    body = await request.body()
    sent_body = False

    async def receive() -> dict[str, Any]:
        nonlocal sent_body
        if sent_body:
            return {"type": "http.request", "body": b"", "more_body": False}
        sent_body = True
        return {"type": "http.request", "body": body, "more_body": False}

    status_code = 500
    headers: list[tuple[bytes, bytes]] = []
    chunks: list[bytes] = []

    async def send(message: dict[str, Any]) -> None:
        nonlocal status_code, headers
        if message["type"] == "http.response.start":
            status_code = int(message["status"])
            headers = list(message.get("headers") or [])
        elif message["type"] == "http.response.body":
            chunks.append(message.get("body") or b"")

    await asgi_app(request.scope, receive, send)
    return Response(
        content=b"".join(chunks),
        status_code=status_code,
        headers={k.decode("latin-1"): v.decode("latin-1") for k, v in headers},
    )


class MarvainTapdbMount:
    """Lazy TapDB UI mount guarded by the Marvain browser session."""

    async def __call__(self, scope, receive, send) -> None:
        request = Request(scope, receive)
        user = _gui_get_user(request)
        if not user:
            if str(scope.get("path") or "").startswith("/api/"):
                await JSONResponse(status_code=401, content={"detail": "Not authenticated"})(scope, receive, send)
                return
            await RedirectResponse(url="/login", status_code=302)(scope, receive, send)
            return

        try:
            tapdb_app = _get_tapdb_web_asgi_app()
            await tapdb_app(_tapdb_child_scope(scope, user), receive, send)
        except MarvainTapdbConfigError as exc:
            await _tapdb_config_error_response(exc)(scope, receive, send)
        except (RuntimeError, ValueError) as exc:
            await _tapdb_config_error_response(exc)(scope, receive, send)
        except Exception as exc:
            logger.warning("Embedded TapDB request failed: %s", exc.__class__.__name__)
            await _tapdb_runtime_error_response(exc)(scope, receive, send)


app.mount("/tapdb", MarvainTapdbMount(), name="tapdb")


async def _api_tapdb_dag_proxy(request: Request) -> Response:
    user = _gui_get_user(request)
    if not user:
        return JSONResponse(status_code=401, content={"detail": "Not authenticated"})
    try:
        return await _dispatch_asgi_app(_get_tapdb_dag_asgi_app(), request)
    except MarvainTapdbConfigError as exc:
        return _tapdb_config_error_response(exc)
    except (RuntimeError, ValueError) as exc:
        return _tapdb_config_error_response(exc)


app.add_api_route("/api/dag", _api_tapdb_dag_proxy, methods=["GET", "POST"], name="api_tapdb_dag_root")
app.add_api_route("/api/dag/{path:path}", _api_tapdb_dag_proxy, methods=["GET", "POST"], name="api_tapdb_dag")


@app.middleware("http")
async def _gui_cache_control_middleware(request: Request, call_next):
    """Disable caching for dynamic GUI pages to avoid stale auth/script state."""
    response = await call_next(request)
    path = str(request.url.path or "")
    if path.startswith("/static/"):
        return response
    if path.startswith("/api/"):
        if path == "/api/ws-auth-token":
            response.headers["Cache-Control"] = "no-store"
        return response
    response.headers["Cache-Control"] = "no-store"
    response.headers["Pragma"] = "no-cache"
    response.headers["Expires"] = "0"
    return response


# -----------------------------
# Startup Event - Validate Configuration
# -----------------------------


@app.on_event("startup")
async def startup_validate_configuration():
    """Validate critical configuration on startup.

    This runs when the GUI server starts and will raise an exception
    (crashing the server) if critical secrets are missing or invalid.
    """
    logger.info("Validating critical configuration...")
    validate_configuration_or_fail()
    logger.info("Configuration validation passed - all critical secrets are set")


# -----------------------------
# GUI Routes (local development only)
# -----------------------------


def _parse_expires_at(value: str | None):
    """Parse a consent expiry value.

    The consent modal uses <input type="date"> which submits 'YYYY-MM-DD'. Treat
    that as inclusive (expires end-of-day UTC), not midnight, so "today" works.
    """
    if not value:
        return None
    v = str(value).strip()
    if not v:
        return None
    from datetime import date, datetime, timezone
    from datetime import time as dt_time

    try:
        if len(v) == 10 and v[4] == "-" and v[7] == "-":
            d = date.fromisoformat(v)
            return datetime.combine(d, dt_time(23, 59, 59), tzinfo=timezone.utc)
        dt = datetime.fromisoformat(v.replace("Z", "+00:00"))
        if dt.tzinfo is None:
            dt = dt.replace(tzinfo=timezone.utc)
        return dt
    except Exception:
        return None


def _get_ws_context(request: Request) -> dict[str, str | None]:
    """Get WebSocket context for template rendering.

    Returns dict with ws_url only; token is fetched via authenticated API call.
    """
    raw_ws_url = getattr(_cfg, "ws_api_url", None)
    ws_url = raw_ws_url.strip() if isinstance(raw_ws_url, str) else None
    return {
        "ws_url": ws_url,
    }


def _cookie_secure(request: Request) -> bool:
    # Prefer explicit config for reverse-proxy/Tailscale setups.
    if str(os.getenv("HTTPS_ENABLED", "")).strip().lower() in ("true", "1", "yes"):
        return True
    xf_proto = str(request.headers.get("x-forwarded-proto") or "").split(",", 1)[0].strip().lower()
    if xf_proto == "https":
        return True
    try:
        return str(request.url.scheme).lower() == "https"
    except Exception:
        return False


def _public_base_url(request: Request) -> str:
    """Resolve the externally-reachable base URL for OAuth redirects.

    For remote access (e.g. via Tailscale serve), the GUI may be reachable at a
    different hostname/scheme than the local bind address. Set PUBLIC_BASE_URL
    to the externally reachable origin (no path), e.g.:
      https://my-host.tailnet-123.ts.net
    """
    raw = str(os.getenv("PUBLIC_BASE_URL", "")).strip()
    if raw:
        return raw.rstrip("/")
    return str(request.base_url).rstrip("/")


def _web_session_config(request: Request) -> CognitoWebSessionConfig:
    base_url = _public_base_url(request)
    return CognitoWebSessionConfig(
        domain=str(_cfg.cognito_domain or ""),
        client_id=str(_cfg.cognito_user_pool_client_id or ""),
        redirect_uri=f"{base_url}/auth/callback",
        logout_uri=f"{base_url}/logged-out",
        session_secret_key=_session_secret,
        session_cookie_name="marvain_session",
        session_max_age=3600 * 8,
        public_base_url=base_url,
        auth_mode="cognito",
        scope="openid email profile aws.cognito.signin.user.admin",
        client_secret=_cfg.cognito_user_pool_client_secret,
        same_site="lax",
        allow_insecure_http=base_url.startswith("http://"),
        server_instance_id=f"marvain-{_cfg.stage}",
    )


def _register_web_session_config(request: Request) -> CognitoWebSessionConfig:
    session_cfg = _web_session_config(request)
    request.app.state.__dict__[CONFIG_STATE_KEY] = session_cfg
    return session_cfg


def _safe_next_path(next_path: str | None) -> str:
    """Return a safe relative path to redirect to after login.

    We only allow absolute-path relative URLs like "/profile".
    """
    nxt = str(next_path or "").strip()
    if not nxt:
        return "/"
    if not nxt.startswith("/"):
        return "/"
    if nxt.startswith("//"):
        return "/"
    # Prevent obvious scheme-like or header injection forms.
    if ":" in nxt or "\r" in nxt or "\n" in nxt:
        return "/"
    return nxt


def _gui_path(request: Request, path: str) -> str:
    """Prefix `path` with ASGI root_path (e.g. API Gateway stage).

    Starlette/FastAPI do not automatically apply `root_path` to string URLs like
    "/login". We do it explicitly so redirects/links work behind stage-based
    deployments.
    """

    root = str(request.scope.get("root_path") or "")
    if not root:
        return path
    if root.endswith("/") and path.startswith("/"):
        return root[:-1] + path
    return root + path


def _safe_next_app_path(request: Request, next_path: str | None) -> str:
    """Return a safe app-internal path (no root_path prefix) for the `next` param."""

    nxt = _safe_next_path(next_path)
    root = str(request.scope.get("root_path") or "")
    if root and nxt.startswith(root):
        # Strip root_path if a caller included it.
        nxt = nxt[len(root) :] or "/"
        if not nxt.startswith("/"):
            nxt = "/" + nxt
        nxt = _safe_next_path(nxt)
    return nxt


def _encode_next_cookie(path: str) -> str:
    """Encode a normalized next-path for safe storage in a cookie."""
    # Path is already normalized by _safe_next_app_path; we further make it opaque.
    data = path.encode("utf-8")
    return base64.urlsafe_b64encode(data).decode("ascii")


def _decode_next_cookie(value: Optional[str]) -> str:
    """Decode a next-path from cookie storage, falling back to root on error."""
    if not value:
        return "/"
    try:
        raw = base64.urlsafe_b64decode(value.encode("ascii"), validate=True)
        path = raw.decode("utf-8", errors="strict")
    except Exception:
        return "/"
    # Re-apply safety normalization to be defensive.
    return _safe_next_path(path)


def _gui_get_user(request: Request) -> AuthenticatedUser | None:
    """Get the authenticated user from the session."""
    if not request.session.get("user_sub") or not request.session.get("email"):
        return None

    _register_web_session_config(request)
    try:
        principal = load_session_principal(request)
    except Exception:
        logger.exception("Invalid GUI session principal")
        request.session.clear()
        return None
    if principal is None:
        return None

    user_sub = principal.user_sub
    email = principal.email
    app_context = dict(principal.app_context or {})
    user_id = str(app_context.get("user_id") or "").strip()

    if not user_id:
        # User exists in session but doesn't have a user_id - need to ensure row
        try:
            user_id = ensure_user_row(_get_db(), cognito_sub=user_sub, email=email)
            app_context["user_id"] = user_id
            request.session["app_context"] = app_context
        except Exception:
            logger.exception("Failed to ensure user row")
            return None

    return AuthenticatedUser(
        user_id=user_id,
        cognito_sub=user_sub,
        email=email,
    )


def _gui_redirect_to_login(*, request: Request, next_path: str | None = None, clear_session: bool = False) -> Response:
    safe_next = _safe_next_app_path(request, next_path)
    request.session["_marvain_login_next"] = safe_next
    resp: Response = RedirectResponse(url=_gui_path(request, "/login"), status_code=302)
    if clear_session:
        clear_session_principal(request)
        request.session["_marvain_login_next"] = safe_next
    return resp


def _gui_html_page(*, title: str, body_html: str) -> HTMLResponse:
    # Minimal HTML; no templating dependency in Phase 4.
    t = html.escape(title)
    doc = (
        "<!doctype html>\n"
        "<html><head><meta charset='utf-8'>"
        f"<title>{t}</title>"
        "<meta name='viewport' content='width=device-width, initial-scale=1'>"
        "</head><body style='font-family: system-ui, -apple-system, sans-serif; max-width: 960px; margin: 2rem auto; padding: 0 1rem;'>"
        f"{body_html}"
        "</body></html>"
    )
    return HTMLResponse(content=doc)


def _gui_error_page(*, request: Request, title: str, message: str, status_code: int = 400) -> HTMLResponse:
    login_href = html.escape(_gui_path(request, "/login"))
    body = f"<h1>{html.escape(title)}</h1><p>{html.escape(message)}</p><p><a href='{login_href}'>Log in</a></p>"
    resp = _gui_html_page(title=title, body_html=body)
    resp.status_code = status_code
    return resp


@app.get("/login", name="login", response_model=None)
def gui_login(request: Request, next: str | None = None) -> Response:
    """Initiate Cognito login flow."""
    # Check if Cognito is configured
    if not _cfg.cognito_user_pool_id or not _cfg.cognito_domain:
        return _gui_error_page(
            request=request,
            title="Authentication Not Configured",
            message="Cognito authentication is not configured. Please set COGNITO_USER_POOL_ID and COGNITO_DOMAIN.",
            status_code=503,
        )

    session_cfg = _register_web_session_config(request)

    state = secrets.token_urlsafe(32)
    request.session[session_cfg.state_session_key] = state
    stored_next = request.session.pop("_marvain_login_next", None)
    request.session[session_cfg.next_path_session_key] = _safe_next_app_path(request, next or stored_next)

    try:
        cfg = dataclasses.replace(_cfg, cognito_redirect_uri=session_cfg.redirect_uri)
        login_url = build_login_url(cfg, state=state)
        return RedirectResponse(url=login_url, status_code=302)
    except CognitoAuthError as e:
        logger.error(f"Failed to build login URL: {e}")
        return _gui_error_page(
            request=request,
            title="Authentication Error",
            message=str(e),
            status_code=500,
        )


@app.get("/auth/callback", name="auth_callback")
async def gui_auth_callback(
    request: Request,
    code: str | None = None,
    state: str | None = None,
    error: str | None = None,
    error_description: str | None = None,
) -> Response:
    """Handle OAuth callback from Cognito."""
    # Check for OAuth errors from Cognito
    if error:
        logger.warning(f"OAuth error: {error} - {error_description}")
        return _gui_error_page(
            request=request,
            title="Authentication Error",
            message=f"{error}: {error_description or 'Unknown error'}",
            status_code=400,
        )

    if not code:
        return _gui_error_page(
            request=request,
            title="Missing Authorization Code",
            message="No authorization code was provided by the identity provider.",
            status_code=400,
        )

    try:
        session_cfg = _register_web_session_config(request)
        cfg = dataclasses.replace(_cfg, cognito_redirect_uri=session_cfg.redirect_uri)

        async def resolve_principal(tokens: dict[str, Any], _request: Request) -> SessionPrincipal:
            id_token = tokens.get("id_token")
            access_token = tokens.get("access_token")

            if not id_token:
                raise CognitoWebAuthError("missing_id_token", "No ID token in response from identity provider")

            cognito_user = await get_user_info_from_tokens(cfg, str(id_token), str(access_token or ""))
            user_id = ensure_user_row(
                _get_db(),
                cognito_sub=cognito_user.sub,
                email=cognito_user.email,
            )
            logger.info(f"User {cognito_user.email} ({cognito_user.sub}) logged in")
            return SessionPrincipal(
                user_sub=cognito_user.sub,
                email=cognito_user.email,
                name=cognito_user.name,
                roles=cognito_user.roles,
                cognito_groups=cognito_user.cognito_groups,
                app_context={"user_id": user_id},
            )

        resp = await complete_cognito_callback(
            request,
            session_cfg,
            code=code,
            state=state,
            resolve_principal=resolve_principal,
        )
        resp.headers["Cache-Control"] = "no-store"
        return resp

    except CognitoWebAuthError as e:
        logger.error(f"Cognito web auth error: {e}")
        return _gui_error_page(
            request=request,
            title="Authentication Error",
            message=str(e),
            status_code=e.status_code,
        )
    except CognitoAuthError as e:
        logger.error(f"Cognito auth error: {e}")
        return _gui_error_page(
            request=request,
            title="Authentication Error",
            message=str(e),
            status_code=401,
        )
    except Exception:
        logger.exception("Unexpected error during OAuth callback")
        return _gui_error_page(
            request=request,
            title="Authentication Error",
            message="An unexpected error occurred. Please try again.",
            status_code=500,
        )


@app.get("/logout", name="logout")
def gui_logout(request: Request) -> Response:
    """Clear session and redirect to Cognito logout or logged-out page."""
    clear_session_principal(request)
    request.session.clear()

    resp: Response
    if _cfg.cognito_domain and _cfg.cognito_user_pool_client_id:
        # Redirect to Cognito logout
        try:
            logout_url = build_logout_url(_cfg, redirect_uri=f"{_public_base_url(request)}/logged-out")
            resp = RedirectResponse(url=logout_url, status_code=302)
        except CognitoAuthError:
            resp = RedirectResponse(url=_gui_path(request, "/logged-out"), status_code=302)
    else:
        resp = RedirectResponse(url=_gui_path(request, "/logged-out"), status_code=302)

    resp.headers["Cache-Control"] = "no-store"
    return resp


@app.get("/logged-out", name="logged_out")
def gui_logged_out(request: Request) -> HTMLResponse:
    login_href = html.escape(_gui_path(request, "/login"))
    return _gui_html_page(title="Logged out", body_html=f"<h1>Logged out</h1><p><a href='{login_href}'>Log in</a></p>")


@app.get("/api/ws-auth-token", name="api_ws_auth_token")
async def api_ws_auth_token(request: Request) -> JSONResponse:
    """Return a Marvain session-scoped WS auth token for the current GUI user."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    token = mint_ws_session_token(
        secret_key=_session_secret,
        user_id=user.user_id,
        cognito_sub=user.cognito_sub,
        email=user.email,
    )
    resp = JSONResponse({"access_token": token, "token_type": "marvain_session"})
    resp.headers["Cache-Control"] = "no-store"
    return resp


@app.get("/", name="gui_home")
def gui_home(request: Request) -> Response:
    """Home dashboard - central hub with status overview and navigation."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(
            request=request, next_path=str(request.scope.get("path") or "/"), clear_session=False
        )

    db = _get_db()

    # Get agents for user
    agents = list_agents_for_user(db, user_id=user.user_id)

    # Get spaces for user
    spaces = list_spaces_for_user(db, user_id=user.user_id)

    # Get pending actions count
    pending_actions = 0
    try:
        rows = db.query(
            """
            SELECT COUNT(*) as cnt FROM actions a
            INNER JOIN agent_memberships m ON a.agent_id = m.agent_id
            WHERE m.user_id = :user_id::uuid AND m.revoked_at IS NULL AND a.status = 'proposed'
        """,
            {"user_id": str(user.user_id)},
        )
        if rows:
            pending_actions = rows[0].get("cnt", 0) or 0
    except Exception as e:
        logger.warning(f"Failed to fetch pending actions: {e}")

    # Convert agents to dicts for template
    agents_data = [
        {
            "agent_id": str(a.agent_id),
            "name": a.name,
            "role": a.role,
            "disabled": a.disabled,
        }
        for a in agents
    ]

    # Get devices count and recent devices for the user's agents
    devices_count = 0
    devices_data: list[dict] = []
    agent_ids = [str(a.agent_id) for a in agents]
    if agent_ids:
        try:
            placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
            params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
            count_rows = db.query(
                f"SELECT COUNT(*) as cnt FROM devices WHERE agent_id::TEXT IN ({placeholders})",
                params,
            )
            if count_rows:
                devices_count = count_rows[0].get("cnt", 0) or 0

            dev_rows = db.query(
                f"""SELECT d.device_id::TEXT as device_id, d.name,
                           a.name as agent_name, d.revoked_at
                    FROM devices d
                    JOIN agents a ON a.agent_id = d.agent_id
                    WHERE d.agent_id::TEXT IN ({placeholders})
                    ORDER BY d.created_at DESC LIMIT 5""",
                params,
            )
            for row in dev_rows:
                devices_data.append(
                    {
                        "device_id": str(row.get("device_id", "")),
                        "name": row.get("name") or "Unnamed Device",
                        "agent_name": row.get("agent_name", ""),
                        "revoked": row.get("revoked_at") is not None,
                    }
                )
        except Exception as e:
            logger.warning(f"Failed to fetch devices for home: {e}")

    # --- Dense dashboard: recent actions (last 10) ---
    recent_actions: list[dict] = []
    if agent_ids:
        try:
            placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
            params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
            act_rows = db.query(
                f"""SELECT ac.action_id::TEXT as action_id, ac.kind, ac.status,
                           ac.created_at::TEXT as created_at,
                           a.name as agent_name
                    FROM actions ac
                    JOIN agents a ON a.agent_id = ac.agent_id
                    WHERE ac.agent_id::TEXT IN ({placeholders})
                    ORDER BY ac.created_at DESC LIMIT 10""",
                params,
            )
            for row in act_rows:
                recent_actions.append(
                    {
                        "action_id": row.get("action_id", ""),
                        "kind": row.get("kind", ""),
                        "status": row.get("status", ""),
                        "created_at": row.get("created_at", ""),
                        "agent_name": row.get("agent_name", ""),
                    }
                )
        except Exception as e:
            logger.warning(f"Failed to fetch recent actions for home: {e}")

    # --- Dense dashboard: agent online/offline via device heartbeats ---
    agents_status: list[dict] = []
    if agent_ids:
        try:
            placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
            params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
            status_rows = db.query(
                f"""SELECT a.agent_id::TEXT as agent_id, a.name, a.disabled,
                           COALESCE(d.online_count, 0) as online_devices,
                           COALESCE(d.total_count, 0) as total_devices
                    FROM agents a
                    LEFT JOIN (
                        SELECT agent_id,
                               COUNT(*) FILTER (
                                   WHERE last_heartbeat_at > now() - interval '60 seconds'
                                     AND revoked_at IS NULL
                               ) as online_count,
                               COUNT(*) FILTER (WHERE revoked_at IS NULL) as total_count
                        FROM devices
                        GROUP BY agent_id
                    ) d ON d.agent_id = a.agent_id
                    WHERE a.agent_id::TEXT IN ({placeholders})""",
                params,
            )
            for row in status_rows:
                online = (row.get("online_devices") or 0) > 0
                agents_status.append(
                    {
                        "agent_id": row.get("agent_id", ""),
                        "name": row.get("name", ""),
                        "disabled": row.get("disabled", False),
                        "online": online and not row.get("disabled", False),
                        "online_devices": row.get("online_devices", 0),
                        "total_devices": row.get("total_devices", 0),
                    }
                )
        except Exception as e:
            logger.warning(f"Failed to fetch agent status for home: {e}")

    # --- Dense dashboard: recent events (last 10) ---
    recent_events: list[dict] = []
    if agent_ids:
        try:
            placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
            params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
            evt_rows = db.query(
                f"""SELECT e.event_id::TEXT as event_id, e.type,
                           e.created_at::TEXT as created_at,
                           a.name as agent_name, s.name as space_name
                    FROM events e
                    JOIN agents a ON a.agent_id = e.agent_id
                    LEFT JOIN spaces s ON s.space_id = e.space_id
                    WHERE e.agent_id::TEXT IN ({placeholders})
                    ORDER BY e.created_at DESC LIMIT 10""",
                params,
            )
            for row in evt_rows:
                recent_events.append(
                    {
                        "event_id": row.get("event_id", ""),
                        "type": row.get("type", ""),
                        "created_at": row.get("created_at", ""),
                        "agent_name": row.get("agent_name", ""),
                        "space_name": row.get("space_name") or "",
                    }
                )
        except Exception as e:
            logger.warning(f"Failed to fetch recent events for home: {e}")

    return templates.TemplateResponse(
        request,
        "home.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "home",
            "agents": agents_data,
            "agents_count": len(agents_data),
            "spaces_count": len(spaces),
            "pending_actions": pending_actions,
            "devices_count": devices_count,
            "devices": devices_data,
            "recent_actions": recent_actions,
            "agents_status": agents_status,
            "recent_events": recent_events,
            **_get_ws_context(request),
        },
    )


# ---------------------------------------------------------------------------
# Dashboard HTMX partial endpoints (auto-refresh fragments)
# ---------------------------------------------------------------------------


@app.get("/dashboard/kpi-strip", name="gui_dashboard_kpi")
def gui_dashboard_kpi(request: Request) -> Response:
    """HTMX partial: compact KPI strip for dashboard auto-refresh."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)
    spaces = list_spaces_for_user(db, user_id=user.user_id)
    agent_ids = [str(a.agent_id) for a in agents]

    pending_actions = 0
    devices_count = 0
    online_agents = 0

    if agent_ids:
        placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
        params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
        try:
            rows = db.query(
                f"""SELECT
                      (SELECT COUNT(*) FROM actions ac
                       WHERE ac.agent_id::TEXT IN ({placeholders}) AND ac.status = 'proposed') as pending,
                      (SELECT COUNT(*) FROM devices
                       WHERE agent_id::TEXT IN ({placeholders}) AND revoked_at IS NULL) as devices,
                      (SELECT COUNT(DISTINCT agent_id) FROM devices
                       WHERE agent_id::TEXT IN ({placeholders}) AND revoked_at IS NULL
                         AND last_heartbeat_at > now() - interval '60 seconds') as online""",
                params,
            )
            if rows:
                pending_actions = rows[0].get("pending", 0) or 0
                devices_count = rows[0].get("devices", 0) or 0
                online_agents = rows[0].get("online", 0) or 0
        except Exception as e:
            logger.warning(f"Dashboard KPI query failed: {e}")

    from starlette.responses import HTMLResponse

    warn = "kpi-warn" if pending_actions > 0 else ""
    html = (
        '<div class="kpi-strip">'
        f'<div class="kpi-item"><span class="kpi-value">{online_agents}</span>'
        '<span class="kpi-label">Agents Online</span></div>'
        f'<div class="kpi-item {warn}"><span class="kpi-value">'
        f"{pending_actions}</span>"
        '<span class="kpi-label">Pending Actions</span></div>'
        f'<div class="kpi-item"><span class="kpi-value">{devices_count}'
        '</span><span class="kpi-label">Devices</span></div>'
        f'<div class="kpi-item"><span class="kpi-value">{len(spaces)}'
        '</span><span class="kpi-label">Spaces</span></div>'
        f'<div class="kpi-item"><span class="kpi-value">{len(agents)}'
        '</span><span class="kpi-label">Agents</span></div>'
        "</div>"
    )
    return HTMLResponse(content=html)


@app.get("/dashboard/activity-feed", name="gui_dashboard_activity")
def gui_dashboard_activity(request: Request) -> Response:
    """HTMX partial: recent events activity feed."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)
    agent_ids = [str(a.agent_id) for a in agents]

    events_html = ""
    if agent_ids:
        try:
            placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
            params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
            rows = db.query(
                f"""SELECT e.type, e.created_at::TEXT as created_at,
                           a.name as agent_name, s.name as space_name
                    FROM events e
                    JOIN agents a ON a.agent_id = e.agent_id
                    LEFT JOIN spaces s ON s.space_id = e.space_id
                    WHERE e.agent_id::TEXT IN ({placeholders})
                    ORDER BY e.created_at DESC LIMIT 15""",
                params,
            )
            for row in rows:
                etype = row.get("type", "")
                ts = (row.get("created_at") or "")[:19]
                agent = row.get("agent_name", "")
                space = row.get("space_name") or ""
                space_tag = f' <span class="badge badge-outline">{space}</span>' if space else ""
                events_html += (
                    f'<div class="feed-item">'
                    f'<span class="feed-time">{ts}</span>'
                    f'<span class="badge badge-info">{agent}</span>'
                    f"{space_tag}"
                    f'<span class="feed-type">{etype}</span>'
                    f"</div>"
                )
        except Exception as e:
            logger.warning(f"Dashboard activity feed query failed: {e}")

    if not events_html:
        events_html = '<div class="text-muted text-sm" style="padding:0.5rem">No recent events</div>'

    from starlette.responses import HTMLResponse

    return HTMLResponse(content=events_html)


@app.get("/dashboard/recent-actions", name="gui_dashboard_actions")
def gui_dashboard_actions(request: Request) -> Response:
    """HTMX partial: recent actions table with inline approve/reject."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)
    agent_ids = [str(a.agent_id) for a in agents]

    rows_html = ""
    if agent_ids:
        try:
            placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
            params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
            rows = db.query(
                f"""SELECT ac.action_id::TEXT as action_id, ac.kind, ac.status,
                           ac.created_at::TEXT as created_at,
                           a.name as agent_name
                    FROM actions ac
                    JOIN agents a ON a.agent_id = ac.agent_id
                    WHERE ac.agent_id::TEXT IN ({placeholders})
                    ORDER BY ac.created_at DESC LIMIT 10""",
                params,
            )
            for row in rows:
                aid = row.get("action_id", "")
                status = row.get("status", "")
                _bcls = {
                    "proposed": "warning",
                    "approved": "info",
                    "executed": "success",
                    "failed": "error",
                    "rejected": "error",
                }
                badge_cls = _bcls.get(status, "info")
                ts = (row.get("created_at") or "")[:19]
                actions_col = ""
                if status == "proposed":
                    actions_col = (
                        '<button class="btn btn-sm btn-success" '
                        f'hx-post="/api/actions/{aid}/approve" '
                        'hx-target="#dashboard-actions" '
                        'hx-swap="innerHTML" '
                        'hx-confirm="Approve this action?">'
                        '<i class="fas fa-check"></i></button> '
                        '<button class="btn btn-sm btn-danger-outline" '
                        f'hx-post="/api/actions/{aid}/reject" '
                        'hx-target="#dashboard-actions" '
                        'hx-swap="innerHTML" '
                        'hx-confirm="Reject this action?">'
                        '<i class="fas fa-times"></i></button>'
                    )
                aname = row.get("agent_name", "")
                akind = row.get("kind", "")
                rows_html += (
                    f'<tr><td class="text-sm">{ts}</td>'
                    f"<td>{aname}</td>"
                    f"<td><code>{akind}</code></td>"
                    f'<td><span class="badge badge-{badge_cls}">'
                    f"{status}</span></td>"
                    f"<td>{actions_col}</td></tr>"
                )
        except Exception as e:
            logger.warning(f"Dashboard recent actions query failed: {e}")

    if not rows_html:
        rows_html = '<tr><td colspan="5" class="text-muted text-sm">No recent actions</td></tr>'

    from starlette.responses import HTMLResponse

    table_html = (
        "<table class='table table-dense'><thead><tr>"
        "<th>Time</th><th>Agent</th><th>Kind</th>"
        "<th>Status</th><th></th></tr></thead>"
        f"<tbody>{rows_html}</tbody></table>"
    )
    return HTMLResponse(content=table_html)


# ---------------------------------------------------------------------------
# Spaces API endpoints
# ---------------------------------------------------------------------------


class SpaceCreate(BaseModel):
    """Request body for creating a space."""

    agent_id: str = Field(..., description="ID of the agent that owns this space")
    name: str = Field(..., description="Name of the space")
    privacy_mode: bool = Field(False, description="Whether privacy mode is enabled")
    livekit_room_mode: str = Field(
        default="ephemeral",
        description="LiveKit room mode: 'ephemeral' (default) or 'stable' (location spaces).",
    )


class SpaceResponse(BaseModel):
    """Response body for space operations."""

    space_id: str
    agent_id: str
    name: str
    privacy_mode: bool


def _max_spaces_per_agent() -> int:
    raw = getattr(_cfg, "max_spaces_per_agent", 5)
    try:
        value = int(raw)
    except (TypeError, ValueError):
        value = 5
    return max(1, value)


@app.post("/api/spaces", name="api_create_space")
def api_create_space(request: Request, body: SpaceCreate) -> SpaceResponse:
    """Create a new space."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Check user has admin permission on the agent
    if not check_agent_permission(db, user_id=user.user_id, agent_id=body.agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")

    # Enforce per-agent space limit.
    try:
        rows = db.query(
            "SELECT COUNT(*)::INT AS count FROM spaces WHERE agent_id = :agent_id::uuid",
            {"agent_id": body.agent_id},
        )
        existing_count = int((rows[0].get("count") if rows else 0) or 0)
    except Exception as e:
        logger.error("Failed to count existing spaces for agent %s: %s", body.agent_id, e)
        raise HTTPException(status_code=500, detail="Failed to validate space limit")

    space_limit = _max_spaces_per_agent()
    if existing_count >= space_limit:
        raise HTTPException(status_code=409, detail=f"Space limit reached ({space_limit}) for this agent")

    # Create the space
    space_id = str(uuid.uuid4())
    room_mode = str(body.livekit_room_mode or "ephemeral").strip().lower()
    if room_mode not in ("ephemeral", "stable"):
        raise HTTPException(status_code=400, detail="Invalid livekit_room_mode (expected 'ephemeral' or 'stable')")
    try:
        db.execute(
            """
            INSERT INTO spaces (space_id, agent_id, name, privacy_mode, livekit_room_mode)
            VALUES (:space_id::uuid, :agent_id::uuid, :name, :privacy_mode, :livekit_room_mode)
        """,
            {
                "space_id": space_id,
                "agent_id": body.agent_id,
                "name": body.name,
                "privacy_mode": body.privacy_mode,
                "livekit_room_mode": room_mode,
            },
        )
    except Exception as e:
        logger.error(f"Failed to create space: {e}")
        raise HTTPException(status_code=500, detail="Failed to create space")

    return SpaceResponse(
        space_id=space_id,
        agent_id=body.agent_id,
        name=body.name,
        privacy_mode=body.privacy_mode,
    )


@app.delete("/api/spaces/{space_id}", name="api_delete_space")
def api_delete_space(request: Request, space_id: str) -> dict:
    """Delete a space."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Get the space and check permission (require admin/owner on the agent)
    rows = db.query(
        """
        SELECT s.space_id, s.agent_id, s.name
        FROM spaces s
        INNER JOIN agent_memberships m ON s.agent_id = m.agent_id
        WHERE s.space_id = :space_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.role IN ('admin', 'owner')
          AND m.revoked_at IS NULL
    """,
        {"space_id": space_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Space not found or permission denied")

    space_name = rows[0].get("name", "")

    try:
        db.execute(
            """
            DELETE FROM spaces WHERE space_id = :space_id::uuid
        """,
            {"space_id": space_id},
        )
    except Exception as e:
        logger.error(f"Failed to delete space: {e}")
        raise HTTPException(status_code=500, detail="Failed to delete space")

    return {"message": "Space deleted", "space_id": space_id, "name": space_name}


class SpaceUpdate(BaseModel):
    name: str | None = None
    privacy_mode: bool | None = None


@app.patch("/api/spaces/{space_id}", name="api_update_space")
def api_update_space(request: Request, space_id: str, body: SpaceUpdate) -> dict:
    """Update a space's name or privacy mode."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Check user has admin permission on the space's agent
    rows = db.query(
        """
        SELECT s.space_id, s.name, s.privacy_mode
        FROM spaces s
        INNER JOIN agent_memberships m ON s.agent_id = m.agent_id
        WHERE s.space_id = :space_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.role IN ('admin', 'owner')
          AND m.revoked_at IS NULL
    """,
        {"space_id": space_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Space not found or permission denied")

    # Build the update query dynamically
    updates = []
    params = {"space_id": space_id}

    if body.name is not None:
        if len(body.name.strip()) == 0:
            raise HTTPException(status_code=400, detail="Name cannot be empty")
        updates.append("name = :name")
        params["name"] = body.name.strip()

    if body.privacy_mode is not None:
        updates.append("privacy_mode = :privacy_mode")
        params["privacy_mode"] = body.privacy_mode

    if not updates:
        raise HTTPException(status_code=400, detail="No fields to update")

    try:
        db.execute(
            f"""
            UPDATE spaces SET {", ".join(updates)} WHERE space_id = :space_id::uuid
        """,
            params,
        )
    except Exception as e:
        logger.error(f"Failed to update space: {e}")
        raise HTTPException(status_code=500, detail="Failed to update space")

    return {"message": "Space updated", "space_id": space_id}


@app.get("/api/spaces/{space_id}", name="api_get_space")
def api_get_space(request: Request, space_id: str) -> dict:
    """Get space details."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    rows = db.query(
        """
        SELECT s.space_id::TEXT as space_id, s.agent_id::TEXT as agent_id,
               s.name, s.privacy_mode, s.created_at::TEXT as created_at,
               a.name as agent_name
        FROM spaces s
        INNER JOIN agents a ON s.agent_id = a.agent_id
        INNER JOIN agent_memberships m ON s.agent_id = m.agent_id
        WHERE s.space_id = :space_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.role IN ('member', 'admin', 'owner')
          AND m.revoked_at IS NULL
    """,
        {"space_id": space_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Space not found or permission denied")

    row = rows[0]
    return {
        "space_id": row["space_id"],
        "agent_id": row["agent_id"],
        "agent_name": row.get("agent_name", ""),
        "name": row["name"],
        "privacy_mode": row["privacy_mode"],
        "created_at": row["created_at"],
    }


# ---------------------------------------------------------------------------
# Devices API endpoints
# ---------------------------------------------------------------------------


class DeviceCreate(BaseModel):
    """Request body for registering a device."""

    agent_id: str = Field(..., description="ID of the agent this device belongs to")
    name: str = Field(..., description="Name of the device")
    scopes: list[str] = Field(default_factory=list, description="Scopes assigned to the device")
    location_label: str | None = Field(
        default=None, description="Human-readable location label (e.g., Kitchen, Lab Bench 3)"
    )
    location_coords: dict | None = Field(default=None, description="Optional geographic coordinates: {lat, lng}")


class DeviceResponse(BaseModel):
    """Response body for device registration."""

    device_id: str
    agent_id: str
    name: str
    scopes: list[str]
    token: str  # Only returned on creation, not stored
    location_label: str | None = None
    location_coords: dict | None = None


class DeviceRotateTokenResponse(BaseModel):
    """Response for token rotation."""

    device_id: str
    token: str


@app.post("/api/devices", name="api_create_device")
def api_create_device(request: Request, body: DeviceCreate) -> DeviceResponse:
    """Register a new device."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Check user has admin permission on the agent
    if not check_agent_permission(db, user_id=user.user_id, agent_id=body.agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")

    # Generate device token and hash it
    import hashlib

    device_token = secrets.token_urlsafe(32)
    token_hash = hashlib.sha256(device_token.encode()).hexdigest()

    # Create the device
    device_id = str(uuid.uuid4())
    try:
        import json

        db.execute(
            """
            INSERT INTO devices (device_id, agent_id, name, scopes, token_hash,
                                 location_label, location_coords, provisioned_at, provisioned_by)
            VALUES (:device_id::uuid, :agent_id::uuid, :name, :scopes::jsonb, :token_hash,
                    :location_label, :location_coords::jsonb, NOW(), :provisioned_by)
        """,
            {
                "device_id": device_id,
                "agent_id": body.agent_id,
                "name": body.name,
                "scopes": json.dumps(body.scopes),
                "token_hash": token_hash,
                "location_label": body.location_label,
                "location_coords": json.dumps(body.location_coords) if body.location_coords else None,
                "provisioned_by": str(user.user_id),
            },
        )
    except Exception as e:
        logger.error(f"Failed to register device: {e}")
        raise HTTPException(status_code=500, detail="Failed to register device")

    return DeviceResponse(
        device_id=device_id,
        agent_id=body.agent_id,
        name=body.name,
        scopes=body.scopes,
        token=device_token,  # Return token only on creation
        location_label=body.location_label,
        location_coords=body.location_coords,
    )


@app.post("/api/devices/{device_id}/revoke", name="api_revoke_device")
def api_revoke_device(request: Request, device_id: str) -> dict:
    """Revoke a device's access."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Get the device and check permission (require admin)
    rows = db.query(
        """
        SELECT d.device_id, d.agent_id
        FROM devices d
        INNER JOIN agent_memberships m ON d.agent_id = m.agent_id
        WHERE d.device_id = :device_id::uuid AND m.user_id = :user_id::uuid AND m.role IN ('admin', 'owner') AND m.revoked_at IS NULL
    """,
        {"device_id": device_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Device not found or permission denied")

    try:
        db.execute(
            """
            UPDATE devices SET revoked_at = NOW() WHERE device_id = :device_id::uuid
        """,
            {"device_id": device_id},
        )
    except Exception as e:
        logger.error(f"Failed to revoke device: {e}")
        raise HTTPException(status_code=500, detail="Failed to revoke device")

    return {"message": "Device revoked", "device_id": device_id}


@app.post("/api/devices/{device_id}/rotate-token", name="api_rotate_device_token")
def api_rotate_device_token(request: Request, device_id: str) -> DeviceRotateTokenResponse:
    """Rotate a device token and return the new token once."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    rows = db.query(
        """
        SELECT d.device_id::TEXT as device_id
        FROM devices d
        INNER JOIN agent_memberships m ON d.agent_id = m.agent_id
        WHERE d.device_id = :device_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.role IN ('admin', 'owner')
          AND m.revoked_at IS NULL
    """,
        {"device_id": device_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Device not found or permission denied")

    import hashlib

    new_token = secrets.token_urlsafe(32)
    token_hash = hashlib.sha256(new_token.encode()).hexdigest()
    try:
        db.execute(
            """
            UPDATE devices
            SET token_hash = :token_hash, revoked_at = NULL
            WHERE device_id = :device_id::uuid
        """,
            {"device_id": device_id, "token_hash": token_hash},
        )
    except Exception as e:
        logger.error(f"Failed to rotate token for device {device_id}: {e}")
        raise HTTPException(status_code=500, detail="Failed to rotate token")

    return DeviceRotateTokenResponse(device_id=device_id, token=new_token)


@app.post("/api/devices/{device_id}/delete", name="api_delete_device")
def api_delete_device(request: Request, device_id: str) -> dict:
    """Delete a device permanently."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Get the device and check permission (require admin/owner)
    rows = db.query(
        """
        SELECT d.device_id, d.agent_id
        FROM devices d
        INNER JOIN agent_memberships m ON d.agent_id = m.agent_id
        WHERE d.device_id = :device_id::uuid AND m.user_id = :user_id::uuid AND m.role IN ('admin', 'owner') AND m.revoked_at IS NULL
    """,
        {"device_id": device_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Device not found or permission denied")

    try:
        db.execute(
            """
            DELETE FROM devices WHERE device_id = :device_id::uuid
        """,
            {"device_id": device_id},
        )
    except Exception as e:
        logger.error(f"Failed to delete device: {e}")
        raise HTTPException(status_code=500, detail="Failed to delete device")

    return {"message": "Device deleted", "device_id": device_id}


class DeviceLocationUpdate(BaseModel):
    """Request body for updating device location."""

    location_label: str | None = Field(default=None, description="Human-readable location label")
    location_coords: dict | None = Field(default=None, description="Optional geographic coordinates: {lat, lng}")


@app.patch("/api/devices/{device_id}/location", name="api_update_device_location")
def api_update_device_location(request: Request, device_id: str, body: DeviceLocationUpdate) -> dict:
    """Update a device's location information."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Check permission
    rows = db.query(
        """
        SELECT d.device_id, d.agent_id
        FROM devices d
        INNER JOIN agent_memberships m ON d.agent_id = m.agent_id
        WHERE d.device_id = :device_id::uuid AND m.user_id = :user_id::uuid AND m.role IN ('admin', 'owner') AND m.revoked_at IS NULL
    """,
        {"device_id": device_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Device not found or permission denied")

    import json as json_module

    try:
        db.execute(
            """
            UPDATE devices
            SET location_label = :location_label,
                location_coords = :location_coords::jsonb
            WHERE device_id = :device_id::uuid
        """,
            {
                "device_id": device_id,
                "location_label": body.location_label,
                "location_coords": json_module.dumps(body.location_coords) if body.location_coords else None,
            },
        )
    except Exception as e:
        logger.error(f"Failed to update device location: {e}")
        raise HTTPException(status_code=500, detail="Failed to update device location")

    return {
        "message": "Location updated",
        "device_id": device_id,
        "location_label": body.location_label,
        "location_coords": body.location_coords,
    }


class DeviceLaunchSatellite(BaseModel):
    """Request body for launching a satellite daemon for a device."""

    device_token: str = Field(..., description="Device authentication token")
    idempotency_key: str = Field(..., description="Client-generated idempotency key")


class HostProcessRequest(BaseModel):
    idempotency_key: str = Field(..., description="Client-generated idempotency key")


class AgentWorkerHostProcessRequest(HostProcessRequest):
    agent_id: str = Field(..., description="Agent that owns the worker lifecycle action")


def _create_host_process_action(
    *,
    db,
    agent_id: str,
    user_id: str,
    operation: str,
    args: dict[str, Any],
    idempotency_key: str,
) -> dict[str, Any]:
    return create_action(
        db,
        agent_id=agent_id,
        space_id=None,
        kind="host_process",
        payload={"operation": operation, "args": args},
        required_scopes=["devices:launch"],
        requested_approval_mode="manual_immediate",
        approved_by_user_id=user_id,
        idempotency_key=idempotency_key,
        request_actor_type="user",
        request_actor_id=user_id,
        request_origin=f"gui:{operation}",
        audit_bucket=_cfg.audit_bucket,
    )


def _run_host_process_action(
    *,
    db,
    created: dict[str, Any],
    dispatch_details: dict[str, Any],
    execute_fn,
) -> tuple[dict[str, Any], dict[str, Any]]:
    action_id = str(created["action_id"])
    current = load_action(db, action_id) or created
    current_status = str(current.get("status") or created.get("status") or "")
    if current_status in {"executed", "failed", "rejected", "device_timeout"}:
        return current, current.get("result") or {}

    reserved = reserve_action_for_execution(db, action_id)
    if not reserved:
        current = load_action(db, action_id) or current
        return current, current.get("result") or {}

    record_action_dispatch_started(
        db,
        action_id=action_id,
        audit_bucket=_cfg.audit_bucket,
        details=dispatch_details,
    )

    try:
        result = execute_fn()
        action = mark_action_completed(
            db,
            action_id=action_id,
            ok=True,
            result=result,
            error=None,
            audit_bucket=_cfg.audit_bucket,
        )
        return action, result
    except HTTPException as exc:
        mark_action_completed(
            db,
            action_id=action_id,
            ok=False,
            result=None,
            error=str(exc.detail),
            audit_bucket=_cfg.audit_bucket,
        )
        raise
    except Exception as exc:
        mark_action_completed(
            db,
            action_id=action_id,
            ok=False,
            result=None,
            error=str(exc),
            audit_bucket=_cfg.audit_bucket,
        )
        raise


@app.post("/api/devices/{device_id}/launch-satellite", name="api_launch_satellite")
def api_launch_satellite(request: Request, device_id: str, body: DeviceLaunchSatellite) -> dict:
    """Launch the remote satellite daemon for a device.

    This is a LOCAL-DEV-ONLY endpoint. It spawns the satellite daemon as a
    background subprocess on the machine running the GUI server.
    """
    import subprocess as _sp

    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Verify device exists and user has permission — the DB-returned device_id
    # is server-controlled (not user-tainted) so safe for paths/commands.
    rows = db.query(
        """
        SELECT d.device_id, d.agent_id, d.name
        FROM devices d
        INNER JOIN agent_memberships m ON d.agent_id = m.agent_id
        WHERE d.device_id = :device_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.revoked_at IS NULL
    """,
        {"device_id": device_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Device not found or permission denied")

    # Use the DB-returned device_id (server-controlled, not user-tainted)
    verified_device_id: str = rows[0]["device_id"]

    ws_url = _cfg.ws_api_url
    if not ws_url:
        raise HTTPException(status_code=500, detail="WebSocket URL not configured (WS_API_URL)")
    hub_rest_url = str(request.base_url).rstrip("/")

    # Resolve the daemon script path relative to the repo root
    repo_root = Path(__file__).resolve().parent.parent.parent
    daemon_script = (repo_root / "apps" / "remote_satellite" / "daemon.py").resolve()
    if not daemon_script.exists():
        raise HTTPException(status_code=500, detail="Satellite daemon script not found")

    # Build the command — pass device_token via env var (not CLI arg) to avoid
    # command-injection taint. The daemon reads MARVAIN_DEVICE_TOKEN from env.
    import sys

    cmd = [
        sys.executable,
        str(daemon_script),
        "--hub-ws-url",
        ws_url,
        "--hub-rest-url",
        hub_rest_url,
    ]
    env = {**os.environ, "MARVAIN_DEVICE_TOKEN": body.device_token}

    # Use verified (DB-returned) device_id for file paths — not user input
    pid_file = repo_root / f".marvain-satellite-{verified_device_id}.pid"
    log_file = repo_root / f".marvain-satellite-{verified_device_id}.log"

    created = _create_host_process_action(
        db=db,
        agent_id=str(rows[0]["agent_id"]),
        user_id=str(user.user_id),
        operation="launch_satellite",
        args={"device_id": verified_device_id},
        idempotency_key=body.idempotency_key,
    )

    def _execute() -> dict[str, Any]:
        if pid_file.exists():
            try:
                old_pid = int(pid_file.read_text().strip())
                os.kill(old_pid, 0)
                return {
                    "status": "already_running",
                    "pid": old_pid,
                    "device_id": verified_device_id,
                    "message": f"Satellite daemon already running (PID {old_pid})",
                }
            except (ProcessLookupError, ValueError, OSError):
                pid_file.unlink(missing_ok=True)
        try:
            with open(log_file, "w") as lf:
                proc = _sp.Popen(
                    cmd,
                    stdin=_sp.DEVNULL,
                    stdout=lf,
                    stderr=_sp.STDOUT,
                    start_new_session=True,
                    env=env,
                )
            pid_file.write_text(str(proc.pid))
            logger.info(f"Launched satellite daemon for device {verified_device_id} (PID {proc.pid})")
        except Exception as e:
            logger.error(f"Failed to launch satellite daemon: {e}")
            raise HTTPException(status_code=500, detail=f"Failed to launch satellite: {e}")

        return {
            "status": "launched",
            "pid": proc.pid,
            "device_id": verified_device_id,
            "device_name": rows[0].get("name", ""),
            "log_file": str(log_file),
            "message": f"Satellite daemon started (PID {proc.pid})",
        }

    action, result = _run_host_process_action(
        db=db,
        created=created,
        dispatch_details={"operation": "launch_satellite", "device_id": verified_device_id},
        execute_fn=_execute,
    )
    return {**result, "action_id": action["action_id"], "action_status": action["status"]}


# ---------------------------------------------------------------------------
# Agent Worker Lifecycle Management (LOCAL-DEV-ONLY)
# ---------------------------------------------------------------------------

_AGENT_PID_FILENAME = ".marvain-agent.pid"
_AGENT_LOG_FILENAME = ".marvain-agent.log"


def _agent_pid_file() -> Path:
    """Return the path to the agent worker PID file in the repo root."""
    return Path(__file__).resolve().parent.parent.parent / _AGENT_PID_FILENAME


def _agent_log_file() -> Path:
    """Return the path to the agent worker log file in the repo root."""
    return Path(__file__).resolve().parent.parent.parent / _AGENT_LOG_FILENAME


def _process_alive(pid: int) -> bool:
    """Check whether a process with *pid* is running."""
    try:
        os.kill(pid, 0)
        return True
    except (OSError, ProcessLookupError):
        return False


def _agent_worker_status_dict() -> dict:
    """Return the current agent worker status as a JSON-safe dict."""
    pid_file = _agent_pid_file()
    log_file = _agent_log_file()
    if not pid_file.exists():
        return {"status": "stopped", "pid": None, "log_file": str(log_file)}
    try:
        pid = int(pid_file.read_text().strip())
    except (ValueError, OSError):
        pid_file.unlink(missing_ok=True)
        return {"status": "stopped", "pid": None, "log_file": str(log_file)}
    if _process_alive(pid):
        return {"status": "running", "pid": pid, "log_file": str(log_file)}
    # Stale PID file
    pid_file.unlink(missing_ok=True)
    return {"status": "stopped", "pid": None, "log_file": str(log_file)}


def _read_marvain_config() -> dict:
    """Read ~/.config/marvain/marvain-config.yaml and return its dict."""
    import yaml

    p = Path(os.path.expanduser("~/.config/marvain/marvain-config.yaml"))
    if not p.exists():
        return {}
    with open(p) as fh:
        return yaml.safe_load(fh) or {}


@app.get("/api/agent-worker/status", name="api_agent_worker_status")
def api_agent_worker_status(request: Request) -> dict:
    """Return the current agent worker status (running/stopped, PID)."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    return _agent_worker_status_dict()


@app.post("/api/agent-worker/stop", name="api_agent_worker_stop")
def api_agent_worker_stop(request: Request, body: AgentWorkerHostProcessRequest) -> dict:
    """Stop the agent worker process."""
    import signal
    import time

    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    db = _get_db()
    if not check_agent_permission(db, user_id=user.user_id, agent_id=body.agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")

    created = _create_host_process_action(
        db=db,
        agent_id=body.agent_id,
        user_id=str(user.user_id),
        operation="stop_agent_worker",
        args={},
        idempotency_key=body.idempotency_key,
    )

    def _execute() -> dict[str, Any]:
        pid_file = _agent_pid_file()
        if not pid_file.exists():
            return {"status": "stopped", "message": "Agent worker is not running (no PID file)"}

        try:
            pid = int(pid_file.read_text().strip())
        except (ValueError, OSError):
            pid_file.unlink(missing_ok=True)
            return {"status": "stopped", "message": "Removed invalid PID file"}

        if not _process_alive(pid):
            pid_file.unlink(missing_ok=True)
            return {"status": "stopped", "message": "Agent worker was already stopped (stale PID)"}

        try:
            os.kill(pid, signal.SIGTERM)
            for _ in range(20):
                time.sleep(0.25)
                if not _process_alive(pid):
                    break
            else:
                os.kill(pid, signal.SIGKILL)
                time.sleep(0.5)
        except (OSError, ProcessLookupError):
            pass

        pid_file.unlink(missing_ok=True)
        stopped = not _process_alive(pid)
        return {
            "status": "stopped" if stopped else "error",
            "pid": None if stopped else pid,
            "message": "Agent worker stopped" if stopped else f"Failed to stop PID {pid}",
        }

    action, result = _run_host_process_action(
        db=db,
        created=created,
        dispatch_details={"operation": "stop_agent_worker"},
        execute_fn=_execute,
    )
    return {**result, "action_id": action["action_id"], "action_status": action["status"]}


@app.post("/api/agent-worker/launch", name="api_agent_worker_launch")
def api_agent_worker_launch(request: Request, body: AgentWorkerHostProcessRequest) -> dict:
    """Launch the agent worker process.

    Reads marvain-config.yaml for LiveKit/OpenAI secret ARNs and bootstrap
    data, fetches credentials from Secrets Manager, then spawns the worker
    as a background subprocess.
    """
    import subprocess as _sp
    import sys

    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    db = _get_db()
    if not check_agent_permission(db, user_id=user.user_id, agent_id=body.agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")

    repo_root = Path(__file__).resolve().parent.parent.parent
    worker_dir = repo_root / "apps" / "agent_worker"
    if not (worker_dir / "worker.py").exists():
        raise HTTPException(status_code=500, detail="Agent worker script not found")

    # --- Gather credentials ---------------------------------------------------
    livekit_url = _cfg.livekit_url
    livekit_secret_arn = _cfg.livekit_secret_arn
    openai_secret_arn = _cfg.openai_secret_arn

    if not livekit_url:
        raise HTTPException(status_code=500, detail="LIVEKIT_URL not configured")
    if not livekit_secret_arn:
        raise HTTPException(status_code=500, detail="LIVEKIT_SECRET_ARN not configured")
    if not openai_secret_arn:
        raise HTTPException(status_code=500, detail="OPENAI_SECRET_ARN not configured")

    try:
        lk = get_secret_json(livekit_secret_arn)
        livekit_api_key = lk.get("api_key", "")
        livekit_api_secret = lk.get("api_secret", "")
        if not livekit_api_key or not livekit_api_secret:
            raise HTTPException(status_code=500, detail="LiveKit secret missing api_key/api_secret")
    except HTTPException:
        raise
    except Exception as exc:
        raise HTTPException(status_code=500, detail=f"Failed to fetch LiveKit secret: {exc}")

    try:
        oai = get_secret_json(openai_secret_arn)
        openai_api_key = oai.get("api_key", "")
        if not openai_api_key or openai_api_key == "REPLACE_ME":
            raise HTTPException(status_code=500, detail="OpenAI secret missing api_key")
    except HTTPException:
        raise
    except Exception as exc:
        raise HTTPException(status_code=500, detail=f"Failed to fetch OpenAI secret: {exc}")

    # Read additional config from marvain-config.yaml (HubRestApiBase, bootstrap)
    mcfg = _read_marvain_config()
    default_env = mcfg.get("default_env", "dev")
    env_cfg = mcfg.get("envs", {}).get(default_env, {})
    resources = env_cfg.get("resources", {})
    bootstrap = env_cfg.get("bootstrap", {})

    # --- Build subprocess environment ----------------------------------------
    env = {**os.environ}
    env["LIVEKIT_URL"] = livekit_url
    env["LIVEKIT_API_KEY"] = livekit_api_key
    env["LIVEKIT_API_SECRET"] = livekit_api_secret
    env["OPENAI_API_KEY"] = openai_api_key

    hub_api_base = resources.get("HubRestApiBase", "")
    if hub_api_base:
        env["HUB_API_BASE"] = hub_api_base

    device_token = bootstrap.get("device_token", "")
    space_id = bootstrap.get("space_id", "")
    if device_token:
        env["HUB_DEVICE_TOKEN"] = device_token
    if space_id:
        env["SPACE_ID"] = space_id

    # AWS credentials (inherit from GUI process)
    aws_profile = env_cfg.get("aws_profile", os.getenv("AWS_PROFILE", ""))
    aws_region = env_cfg.get("aws_region", os.getenv("AWS_REGION", "us-east-1"))
    if aws_profile:
        env["AWS_PROFILE"] = aws_profile
    env["AWS_REGION"] = aws_region
    env["AWS_DEFAULT_REGION"] = aws_region

    # --- Spawn ----------------------------------------------------------------
    cmd = [sys.executable, "worker.py", "dev"]
    log_file = _agent_log_file()
    pid_file = _agent_pid_file()
    created = _create_host_process_action(
        db=db,
        agent_id=body.agent_id,
        user_id=str(user.user_id),
        operation="launch_agent_worker",
        args={},
        idempotency_key=body.idempotency_key,
    )

    def _execute() -> dict[str, Any]:
        cur = _agent_worker_status_dict()
        if cur["status"] == "running":
            return {
                "status": "already_running",
                "pid": cur["pid"],
                "message": f"Agent worker already running (PID {cur['pid']})",
            }
        try:
            with open(log_file, "w") as lf:
                proc = _sp.Popen(
                    cmd,
                    cwd=str(worker_dir),
                    env=env,
                    stdin=_sp.DEVNULL,
                    stdout=lf,
                    stderr=_sp.STDOUT,
                    start_new_session=True,
                )
            pid_file.write_text(str(proc.pid))
            logger.info("Launched agent worker (PID %s)", proc.pid)
        except Exception as exc:
            logger.error("Failed to launch agent worker: %s", exc)
            raise HTTPException(status_code=500, detail=f"Failed to launch agent worker: {exc}")

        return {
            "status": "launched",
            "pid": proc.pid,
            "log_file": str(log_file),
            "message": f"Agent worker started (PID {proc.pid})",
        }

    action, result = _run_host_process_action(
        db=db,
        created=created,
        dispatch_details={"operation": "launch_agent_worker"},
        execute_fn=_execute,
    )
    return {**result, "action_id": action["action_id"], "action_status": action["status"]}


@app.post("/api/agent-worker/restart", name="api_agent_worker_restart")
def api_agent_worker_restart(request: Request, body: AgentWorkerHostProcessRequest) -> dict:
    """Restart the agent worker (stop then launch)."""
    import time

    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    db = _get_db()
    if not check_agent_permission(db, user_id=user.user_id, agent_id=body.agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")

    created = _create_host_process_action(
        db=db,
        agent_id=body.agent_id,
        user_id=str(user.user_id),
        operation="restart_agent_worker",
        args={},
        idempotency_key=body.idempotency_key,
    )

    def _execute() -> dict[str, Any]:
        stop_result = api_agent_worker_stop(
            request,
            AgentWorkerHostProcessRequest(agent_id=body.agent_id, idempotency_key=f"{body.idempotency_key}:stop"),
        )
        time.sleep(1)
        launch_result = api_agent_worker_launch(
            request,
            AgentWorkerHostProcessRequest(agent_id=body.agent_id, idempotency_key=f"{body.idempotency_key}:launch"),
        )
        return {"status": "restarted", "stop": stop_result, "launch": launch_result}

    action, result = _run_host_process_action(
        db=db,
        created=created,
        dispatch_details={"operation": "restart_agent_worker"},
        execute_fn=_execute,
    )
    return {**result, "action_id": action["action_id"], "action_status": action["status"]}


# ---------------------------------------------------------------------------
# Agents API endpoints (session-based auth for GUI)
# ---------------------------------------------------------------------------


class AgentCreate(BaseModel):
    """Request body for creating an agent."""

    name: str = Field(..., min_length=1, max_length=255, description="Name of the agent")
    relationship_label: str | None = Field(None, max_length=255, description="Optional label for the relationship")


class AgentResponse(BaseModel):
    """Response body for agent creation."""

    agent_id: str
    name: str
    role: str
    relationship_label: str | None
    disabled: bool


def _seed_default_persona(*, agent_id: str, transaction_id: str | None = None) -> str:
    """Create the required active default persona for a newly created agent."""
    persona_id = str(uuid.uuid4())
    _get_db().execute(
        """
        INSERT INTO personas(persona_id, agent_id, name, instructions, is_default, lifecycle_state)
        VALUES (:persona_id::uuid, :agent_id::uuid, :name, :instructions, true, 'active')
        """,
        {
            "persona_id": persona_id,
            "agent_id": agent_id,
            "name": DEFAULT_AGENT_PERSONA_NAME,
            "instructions": DEFAULT_AGENT_PERSONA_INSTRUCTIONS,
        },
        transaction_id=transaction_id,
    )
    return persona_id


@app.post("/api/agents", name="api_create_agent")
def api_create_agent(request: Request, body: AgentCreate) -> AgentResponse:
    """Create a new agent and make the creating user the owner."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    agent_id = str(uuid.uuid4())

    # Use a transaction to ensure atomicity
    tx = db.begin()
    try:
        # Create the agent
        db.execute(
            "INSERT INTO agents(agent_id, name, disabled) VALUES (:agent_id::uuid, :name, false)",
            {"agent_id": agent_id, "name": body.name},
            transaction_id=tx,
        )

        # Make the creating user the owner
        db.execute(
            """
            INSERT INTO agent_memberships (agent_id, user_id, role, relationship_label)
            VALUES (:agent_id::uuid, :user_id::uuid, 'owner', :relationship_label)
            """,
            {"agent_id": agent_id, "user_id": user.user_id, "relationship_label": body.relationship_label},
            transaction_id=tx,
        )

        _seed_default_persona(agent_id=agent_id, transaction_id=tx)
        db.commit(tx)
    except Exception as e:
        db.rollback(tx)
        logger.error(f"Failed to create agent: {e}")
        raise HTTPException(status_code=500, detail="Failed to create agent")

    # Add audit log entry if audit bucket is configured
    if _cfg.audit_bucket:
        from agent_hub.audit import append_audit_entry

        append_audit_entry(
            db,
            bucket=_cfg.audit_bucket,
            agent_id=agent_id,
            entry_type="agent_created",
            entry={"user_id": user.user_id, "name": body.name},
        )

    return AgentResponse(
        agent_id=agent_id,
        name=body.name,
        role="owner",
        relationship_label=body.relationship_label,
        disabled=False,
    )


class AgentUpdate(BaseModel):
    name: str | None = None
    disabled: bool | None = None


@app.patch("/api/agents/{agent_id}", name="api_update_agent")
def api_update_agent(request: Request, agent_id: str, body: AgentUpdate) -> dict:
    """Update an agent's name or disabled status."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Check user has admin or owner permission
    if not check_agent_permission(db, user_id=user.user_id, agent_id=agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")

    # Build the update query dynamically
    updates = []
    params = {"agent_id": agent_id}

    if body.name is not None:
        if len(body.name.strip()) == 0:
            raise HTTPException(status_code=400, detail="Name cannot be empty")
        updates.append("name = :name")
        params["name"] = body.name.strip()

    if body.disabled is not None:
        updates.append("disabled = :disabled")
        params["disabled"] = body.disabled

    if not updates:
        raise HTTPException(status_code=400, detail="No fields to update")

    try:
        db.execute(
            f"""
            UPDATE agents SET {", ".join(updates)} WHERE agent_id = :agent_id::uuid
        """,
            params,
        )
    except Exception as e:
        logger.error(f"Failed to update agent: {e}")
        raise HTTPException(status_code=500, detail="Failed to update agent")

    return {"message": "Agent updated", "agent_id": agent_id}


@app.post("/api/agents/{agent_id}/delete", name="api_delete_agent")
def api_delete_agent(request: Request, agent_id: str) -> dict:
    """Delete an agent permanently.  Owner role required.

    Cascade deletes will remove all related spaces, devices, people,
    events, memories, actions, and audit_state rows automatically.
    """
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Only the *owner* may delete the entire agent.
    rows = db.query(
        """
        SELECT a.agent_id
        FROM agents a
        INNER JOIN agent_memberships m ON a.agent_id = m.agent_id
        WHERE a.agent_id = :agent_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.role = 'owner'
          AND m.revoked_at IS NULL
    """,
        {"agent_id": agent_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Agent not found or permission denied (owner required)")

    try:
        db.execute(
            "DELETE FROM agents WHERE agent_id = :agent_id::uuid",
            {"agent_id": agent_id},
        )
    except Exception as e:
        logger.error(f"Failed to delete agent: {e}")
        raise HTTPException(status_code=500, detail="Failed to delete agent")

    return {"message": "Agent deleted", "agent_id": agent_id}


@app.get("/api/agents/{agent_id}/summary", name="api_agent_summary")
def api_agent_summary(request: Request, agent_id: str) -> dict:
    """Return summary counts for an agent (devices, spaces, memories)."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Verify access
    rows = db.query(
        """
        SELECT 1
        FROM agent_memberships
        WHERE agent_id = :agent_id::uuid AND user_id = :user_id::uuid
          AND revoked_at IS NULL
    """,
        {"agent_id": agent_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Agent not found or permission denied")

    counts = db.query(
        """
        SELECT
          (SELECT count(*) FROM devices WHERE agent_id = :aid::uuid AND revoked_at IS NULL) AS device_count,
          (SELECT count(*) FROM spaces WHERE agent_id = :aid::uuid) AS space_count,
          (SELECT count(*) FROM memories WHERE agent_id = :aid::uuid) AS memory_count,
          (SELECT count(*) FROM events WHERE agent_id = :aid::uuid) AS event_count
    """,
        {"aid": agent_id},
    )
    row = counts[0] if counts else {}
    worker = _agent_worker_status_dict()
    return {
        "device_count": row.get("device_count", 0),
        "space_count": row.get("space_count", 0),
        "memory_count": row.get("memory_count", 0),
        "event_count": row.get("event_count", 0),
        "worker_status": worker["status"],
        "worker_pid": worker["pid"],
    }


@app.get("/api/agents/{agent_id}", name="api_get_agent")
def api_get_agent(request: Request, agent_id: str) -> dict:
    """Get agent details."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    rows = db.query(
        """
        SELECT a.agent_id::TEXT as agent_id, a.name, a.disabled,
               a.created_at::TEXT as created_at,
               mb.role, mb.relationship_label
        FROM agents a
        INNER JOIN agent_memberships mb ON a.agent_id = mb.agent_id
        WHERE a.agent_id = :agent_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN ('member', 'admin', 'owner')
          AND mb.revoked_at IS NULL
    """,
        {"agent_id": agent_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Agent not found or permission denied")

    row = rows[0]
    return {
        "agent_id": row["agent_id"],
        "name": row["name"],
        "disabled": row["disabled"],
        "role": row["role"],
        "relationship_label": row.get("relationship_label"),
        "created_at": row["created_at"],
    }


# ----- Membership Management API Endpoints -----


@app.get("/api/cognito/users", name="api_list_cognito_users")
def api_list_cognito_users(request: Request) -> list[dict]:
    """List all users in the Cognito user pool (for member selection)."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    if not _cfg.cognito_user_pool_id:
        raise HTTPException(status_code=500, detail="Cognito not configured")

    users = []
    for u in list_cognito_users(user_pool_id=_cfg.cognito_user_pool_id, region=_cfg.cognito_region):
        attrs = {a["Name"]: a["Value"] for a in u.get("Attributes", [])}
        email = attrs.get("email", u.get("Username", ""))
        if email:
            users.append(
                {
                    "email": email,
                    "status": u.get("UserStatus", "UNKNOWN"),
                    "enabled": u.get("Enabled", False),
                }
            )
    return users


class MemberAdd(BaseModel):
    email: str
    role: str = "member"
    relationship_label: str | None = None


class MemberUpdate(BaseModel):
    role: str
    relationship_label: str | None = None


class MemberResponse(BaseModel):
    user_id: str
    email: str | None
    role: str


@app.post("/api/agents/{agent_id}/memberships", name="api_add_member")
def api_add_member(request: Request, agent_id: str, body: MemberAdd) -> MemberResponse:
    """Add a member to an agent."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    if not check_agent_permission(db, agent_id=agent_id, user_id=user.user_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Forbidden")

    # Look up the user by email in Cognito
    if not _cfg.cognito_user_pool_id:
        raise HTTPException(status_code=500, detail="Cognito not configured")

    try:
        cognito_sub, resolved_email = lookup_cognito_user_by_email(
            user_pool_id=_cfg.cognito_user_pool_id, email=body.email
        )
    except LookupError:
        # Provide a more helpful error message
        raise HTTPException(
            status_code=404,
            detail=f"User '{body.email}' not found in Cognito. They must have a Cognito account before being added as a member. Use 'marvain cognito create-user' to create one.",
        )

    # Ensure user exists in local DB
    target_user_id = ensure_user_row(db, cognito_sub=cognito_sub, email=resolved_email or body.email)

    try:
        grant_membership(
            db, agent_id=agent_id, user_id=target_user_id, role=body.role, relationship_label=body.relationship_label
        )
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))

    if _cfg.audit_bucket:
        from agent_hub.audit import append_audit_entry

        append_audit_entry(
            db,
            bucket=_cfg.audit_bucket,
            agent_id=agent_id,
            entry_type="member_granted",
            entry={
                "by_user_id": user.user_id,
                "user_id": target_user_id,
                "email": resolved_email or body.email,
                "role": body.role,
            },
        )

    return MemberResponse(user_id=target_user_id, email=resolved_email or body.email, role=body.role)


@app.patch("/api/agents/{agent_id}/memberships/{member_user_id}", name="api_update_member")
def api_update_member(request: Request, agent_id: str, member_user_id: str, body: MemberUpdate) -> dict:
    """Update a member's role in an agent."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    if not check_agent_permission(db, agent_id=agent_id, user_id=user.user_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Forbidden")

    try:
        update_membership(
            db, agent_id=agent_id, user_id=member_user_id, role=body.role, relationship_label=body.relationship_label
        )
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))

    if _cfg.audit_bucket:
        from agent_hub.audit import append_audit_entry

        append_audit_entry(
            db,
            bucket=_cfg.audit_bucket,
            agent_id=agent_id,
            entry_type="member_updated",
            entry={"by_user_id": user.user_id, "user_id": member_user_id, "role": body.role},
        )

    return {"ok": True}


@app.delete("/api/agents/{agent_id}/memberships/{member_user_id}", name="api_delete_member")
def api_delete_member(request: Request, agent_id: str, member_user_id: str) -> dict:
    """Remove a member from an agent."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    if not check_agent_permission(db, agent_id=agent_id, user_id=user.user_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Forbidden")

    revoke_membership(db, agent_id=agent_id, user_id=member_user_id)

    if _cfg.audit_bucket:
        from agent_hub.audit import append_audit_entry

        append_audit_entry(
            db,
            bucket=_cfg.audit_bucket,
            agent_id=agent_id,
            entry_type="member_revoked",
            entry={"by_user_id": user.user_id, "user_id": member_user_id},
        )

    return {"ok": True}


class AutoApprovePolicyIn(BaseModel):
    name: str
    enabled: bool = True
    priority: int = 100
    action_kind: str = "*"
    required_scopes: list[str] = []
    time_window: dict[str, Any] = {}


def _as_json_list(value: Any) -> list[Any]:
    if isinstance(value, list):
        return value
    if isinstance(value, str):
        try:
            parsed = json.loads(value)
            if isinstance(parsed, list):
                return parsed
        except Exception:
            return []
    return []


def _as_json_dict(value: Any) -> dict[str, Any]:
    if isinstance(value, dict):
        return value
    if isinstance(value, str):
        try:
            parsed = json.loads(value)
            if isinstance(parsed, dict):
                return parsed
        except Exception:
            return {}
    return {}


@app.get("/api/agents/{agent_id}/auto-approve-policies", name="api_list_auto_approve_policies")
def api_list_auto_approve_policies(request: Request, agent_id: str) -> list[dict[str, Any]]:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    if not check_agent_permission(db, agent_id=agent_id, user_id=user.user_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Forbidden")

    rows = db.query(
        """
        SELECT policy_id::TEXT as policy_id, name, enabled, priority, action_kind,
               required_scopes::TEXT as required_scopes,
               time_window::TEXT as time_window,
               created_by::TEXT as created_by,
               created_at::TEXT as created_at,
               updated_at::TEXT as updated_at
        FROM action_auto_approve_policies
        WHERE agent_id = :agent_id::uuid
          AND revoked_at IS NULL
        ORDER BY priority ASC, created_at DESC
        """,
        {"agent_id": agent_id},
    )
    out: list[dict[str, Any]] = []
    for row in rows:
        out.append(
            {
                "policy_id": row.get("policy_id"),
                "name": row.get("name"),
                "enabled": bool(row.get("enabled")),
                "priority": int(row.get("priority") or 100),
                "action_kind": row.get("action_kind") or "*",
                "required_scopes": _as_json_list(row.get("required_scopes")),
                "time_window": _as_json_dict(row.get("time_window")),
                "created_by": row.get("created_by"),
                "created_at": row.get("created_at"),
                "updated_at": row.get("updated_at"),
            }
        )
    return out


@app.post("/api/agents/{agent_id}/auto-approve-policies", name="api_create_auto_approve_policy")
def api_create_auto_approve_policy(request: Request, agent_id: str, body: AutoApprovePolicyIn) -> dict[str, Any]:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    if not check_agent_permission(db, agent_id=agent_id, user_id=user.user_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Forbidden")

    policy_id = str(uuid.uuid4())
    db.execute(
        """
        INSERT INTO action_auto_approve_policies(
          policy_id, agent_id, name, enabled, priority, action_kind, required_scopes, time_window, created_by
        ) VALUES(
          :policy_id::uuid, :agent_id::uuid, :name, :enabled, :priority, :action_kind,
          :required_scopes::jsonb, :time_window::jsonb, :created_by::uuid
        )
        """,
        {
            "policy_id": policy_id,
            "agent_id": agent_id,
            "name": body.name.strip(),
            "enabled": bool(body.enabled),
            "priority": int(body.priority),
            "action_kind": str(body.action_kind or "*").strip(),
            "required_scopes": json.dumps([str(s) for s in (body.required_scopes or [])]),
            "time_window": json.dumps(body.time_window or {}),
            "created_by": str(user.user_id),
        },
    )
    return {"ok": True, "policy_id": policy_id}


@app.put("/api/agents/{agent_id}/auto-approve-policies/{policy_id}", name="api_update_auto_approve_policy")
def api_update_auto_approve_policy(
    request: Request, agent_id: str, policy_id: str, body: AutoApprovePolicyIn
) -> dict[str, Any]:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    if not check_agent_permission(db, agent_id=agent_id, user_id=user.user_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Forbidden")

    db.execute(
        """
        UPDATE action_auto_approve_policies
        SET name = :name,
            enabled = :enabled,
            priority = :priority,
            action_kind = :action_kind,
            required_scopes = :required_scopes::jsonb,
            time_window = :time_window::jsonb,
            updated_at = now()
        WHERE policy_id = :policy_id::uuid
          AND agent_id = :agent_id::uuid
          AND revoked_at IS NULL
        """,
        {
            "policy_id": policy_id,
            "agent_id": agent_id,
            "name": body.name.strip(),
            "enabled": bool(body.enabled),
            "priority": int(body.priority),
            "action_kind": str(body.action_kind or "*").strip(),
            "required_scopes": json.dumps([str(s) for s in (body.required_scopes or [])]),
            "time_window": json.dumps(body.time_window or {}),
        },
    )
    return {"ok": True}


@app.delete("/api/agents/{agent_id}/auto-approve-policies/{policy_id}", name="api_delete_auto_approve_policy")
def api_delete_auto_approve_policy(request: Request, agent_id: str, policy_id: str) -> dict[str, Any]:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    if not check_agent_permission(db, agent_id=agent_id, user_id=user.user_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Forbidden")

    db.execute(
        """
        UPDATE action_auto_approve_policies
        SET revoked_at = now(), updated_at = now()
        WHERE policy_id = :policy_id::uuid
          AND agent_id = :agent_id::uuid
          AND revoked_at IS NULL
        """,
        {"policy_id": policy_id, "agent_id": agent_id},
    )
    return {"ok": True}


@app.get("/agents", name="gui_agents")
def gui_agents(request: Request) -> Response:
    """Agents management - list all agents."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/agents")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)

    # Build agent data list
    agents_data = []
    for agent in agents:
        agents_data.append(
            {
                "agent_id": str(agent.agent_id),
                "name": agent.name,
                "role": agent.role,
                "relationship_label": agent.relationship_label,
                "disabled": agent.disabled,
            }
        )

    # Count by role
    owner_count = sum(1 for a in agents_data if a["role"] == "owner")
    admin_count = sum(1 for a in agents_data if a["role"] == "admin")
    member_count = sum(1 for a in agents_data if a["role"] == "member")

    return templates.TemplateResponse(
        request,
        "agents.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "agents",
            "agents": agents_data,
            "owner_count": owner_count,
            "admin_count": admin_count,
            "member_count": member_count,
            "total_count": len(agents_data),
            **_get_ws_context(request),
        },
    )


@app.get("/spaces", name="gui_spaces")
def gui_spaces(request: Request) -> Response:
    """Spaces management - list all spaces."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/spaces")

    db = _get_db()
    spaces = list_spaces_for_user(db, user_id=user.user_id)
    agents = list_agents_for_user(db, user_id=user.user_id)

    # Get privacy_mode and created_at for each space from database
    space_ids = [s.space_id for s in spaces]
    space_extra: dict[str, dict] = {}
    if space_ids:
        # Query for extra space data (privacy_mode, created_at)
        placeholders = ", ".join(f":id{i}" for i in range(len(space_ids)))
        params = {f"id{i}": sid for i, sid in enumerate(space_ids)}
        rows = db.query(
            f"SELECT space_id::TEXT as space_id, privacy_mode, created_at FROM spaces WHERE space_id::TEXT IN ({placeholders})",
            params,
        )
        for row in rows:
            sid = str(row.get("space_id", ""))
            space_extra[sid] = {
                "privacy_mode": row.get("privacy_mode", False),
                "created_at": row.get("created_at"),
            }

    # Build spaces data list
    spaces_data = []
    for space in spaces:
        extra = space_extra.get(space.space_id, {})
        created_at = extra.get("created_at")
        # Calculate relative time
        if created_at:
            try:
                from datetime import datetime, timezone

                if hasattr(created_at, "tzinfo"):
                    now = datetime.now(timezone.utc)
                    delta = now - created_at
                    if delta.days > 0:
                        created_at_relative = f"{delta.days}d ago"
                    elif delta.seconds >= 3600:
                        created_at_relative = f"{delta.seconds // 3600}h ago"
                    else:
                        created_at_relative = f"{delta.seconds // 60}m ago"
                else:
                    created_at_relative = str(created_at)[:10]
            except Exception:
                created_at_relative = str(created_at)[:10] if created_at else None
        else:
            created_at_relative = None

        spaces_data.append(
            {
                "space_id": space.space_id,
                "name": space.name,
                "agent_id": space.agent_id,
                "agent_name": space.agent_name,
                "privacy_mode": extra.get("privacy_mode", False),
                "created_at_relative": created_at_relative,
                "livekit_room_mode": getattr(space, "livekit_room_mode", "ephemeral"),
            }
        )

    # Build agents data for dropdown
    agents_data = [{"agent_id": a.agent_id, "name": a.name, "role": a.role} for a in agents]

    return templates.TemplateResponse(
        request,
        "spaces.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "spaces",
            "spaces": spaces_data,
            "agents": agents_data,
            **_get_ws_context(request),
        },
    )


@app.get("/devices", name="gui_devices")
def gui_devices(request: Request) -> Response:
    """Devices management - list registered devices."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/devices")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)

    # Get devices for all agents the user has access to
    agent_ids = [a.agent_id for a in agents]
    devices_data = []
    if agent_ids:
        placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
        params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
        rows = db.query(
            f"""SELECT d.device_id::TEXT as device_id, d.agent_id::TEXT as agent_id,
                       d.name, d.scopes, d.revoked_at, d.created_at, d.last_seen,
                       d.last_heartbeat_at, d.location_label, d.location_coords,
                       CASE
                           WHEN d.last_heartbeat_at > now() - interval '60 seconds' THEN true
                           ELSE false
                       END as is_online,
                       a.name as agent_name
                FROM devices d
                JOIN agents a ON a.agent_id = d.agent_id
                WHERE d.agent_id::TEXT IN ({placeholders})
                ORDER BY d.location_label NULLS LAST, d.created_at DESC""",
            params,
        )
        for row in rows:
            last_seen = row.get("last_seen")
            if last_seen:
                try:
                    from datetime import datetime, timezone

                    if hasattr(last_seen, "tzinfo"):
                        now = datetime.now(timezone.utc)
                        delta = now - last_seen
                        if delta.days > 0:
                            last_seen_relative = f"{delta.days}d ago"
                        elif delta.seconds >= 3600:
                            last_seen_relative = f"{delta.seconds // 3600}h ago"
                        else:
                            last_seen_relative = f"{delta.seconds // 60}m ago"
                    else:
                        last_seen_relative = str(last_seen)[:16]
                except Exception:
                    last_seen_relative = str(last_seen)[:16] if last_seen else None
            else:
                last_seen_relative = None

            scopes = row.get("scopes") or []
            if isinstance(scopes, str):
                import json

                try:
                    scopes = json.loads(scopes)
                except Exception:
                    scopes = []

            # Parse location_coords if it's a string
            location_coords = row.get("location_coords")
            if isinstance(location_coords, str):
                import json as json_mod

                try:
                    location_coords = json_mod.loads(location_coords)
                except Exception:
                    location_coords = None

            devices_data.append(
                {
                    "device_id": str(row.get("device_id", "")),
                    "agent_id": str(row.get("agent_id", "")),
                    "agent_name": row.get("agent_name", ""),
                    "name": row.get("name") or "Unnamed Device",
                    "scopes": scopes,
                    "revoked": row.get("revoked_at") is not None,
                    "is_online": bool(row.get("is_online")),
                    "last_heartbeat_at": str(row.get("last_heartbeat_at") or ""),
                    "last_seen_relative": last_seen_relative,
                    "location_label": row.get("location_label") or "",
                    "location_coords": location_coords,
                }
            )

    # Build agents data for dropdown
    agents_data = [{"agent_id": a.agent_id, "name": a.name, "role": a.role} for a in agents]

    return templates.TemplateResponse(
        request,
        "devices.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "devices",
            "devices": devices_data,
            "agents": agents_data,
            **_get_ws_context(request),
        },
    )


@app.get("/devices/{device_id}", name="gui_device_detail")
def gui_device_detail(request: Request, device_id: str) -> Response:
    """Device detail page - view a specific device."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path=f"/devices/{device_id}")

    db = _get_db()

    # Get device with permission check
    rows = db.query(
        """
        SELECT d.device_id::TEXT, d.agent_id::TEXT, d.name, d.scopes,
               d.revoked_at, d.created_at, d.last_seen, d.last_heartbeat_at,
               d.location_label, d.location_coords,
               d.provisioned_at, d.provisioned_by,
               a.name as agent_name,
               CASE
                   WHEN d.last_heartbeat_at > now() - interval '60 seconds' THEN true
                   ELSE false
               END as is_online
        FROM devices d
        JOIN agents a ON a.agent_id = d.agent_id
        JOIN agent_memberships m ON d.agent_id = m.agent_id
        WHERE d.device_id = :device_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.revoked_at IS NULL
    """,
        {"device_id": device_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Device not found")

    row = rows[0]

    # Parse scopes
    scopes = row.get("scopes") or []
    if isinstance(scopes, str):
        import json as json_module

        try:
            scopes = json_module.loads(scopes)
        except Exception:
            scopes = []

    # Format timestamps
    created_at = row.get("created_at")
    if created_at:
        created_at = str(created_at)[:19] if hasattr(created_at, "isoformat") else str(created_at)[:19]

    last_seen = row.get("last_seen")
    if last_seen:
        last_seen = str(last_seen)[:19] if hasattr(last_seen, "isoformat") else str(last_seen)[:19]

    # Parse location_coords
    location_coords = row.get("location_coords")
    if isinstance(location_coords, str):
        import json as json_mod2

        try:
            location_coords = json_mod2.loads(location_coords)
        except Exception:
            location_coords = None

    provisioned_at = row.get("provisioned_at")
    if provisioned_at:
        provisioned_at = str(provisioned_at)[:19] if hasattr(provisioned_at, "isoformat") else str(provisioned_at)[:19]

    device_data = {
        "device_id": str(row.get("device_id", "")),
        "agent_id": str(row.get("agent_id", "")),
        "agent_name": row.get("agent_name", ""),
        "name": row.get("name") or "Unnamed Device",
        "scopes": scopes,
        "revoked": row.get("revoked_at") is not None,
        "created_at": created_at,
        "last_seen": last_seen,
        "is_online": bool(row.get("is_online")),
        "location_label": row.get("location_label") or "",
        "location_coords": location_coords,
        "provisioned_at": provisioned_at,
        "provisioned_by": row.get("provisioned_by") or "",
    }

    return templates.TemplateResponse(
        request,
        "device_detail.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "devices",
            "device": device_data,
            "rest_url": str(request.base_url).rstrip("/"),
            **_get_ws_context(request),
        },
    )


# ---------------------------------------------------------------------------
# People & Consent API endpoints
# ---------------------------------------------------------------------------


class PersonCreate(BaseModel):
    """Request body for creating a person."""

    agent_id: str = Field(..., description="ID of the agent this person belongs to")
    display_name: str = Field(..., description="Display name of the person")


class PersonResponse(BaseModel):
    """Response body for person operations."""

    person_id: str
    agent_id: str
    display_name: str


class ConsentGrant(BaseModel):
    """A single consent grant."""

    type: str = Field(..., description="Type of consent: voice, face, recording, or global")
    expires_at: str | None = Field(None, description="Optional expiration date (ISO format)")


class ConsentUpdate(BaseModel):
    """Request body for updating consents."""

    consents: list[ConsentGrant] = Field(default_factory=list, description="List of consent grants")


class RecognitionEnrollmentCreate(BaseModel):
    """Consent-gated recognition enrollment request from the GUI."""

    person_id: str
    modality: str = Field(..., description="voice or face")
    artifact_bucket: str | None = None
    artifact_key: str | None = None
    artifact_uri: str | None = None
    content_type: str | None = None
    embedding: list[float] | None = None
    model: str | None = None
    metadata: dict[str, Any] = Field(default_factory=dict)


class RecognitionDecisionUpdate(BaseModel):
    """Optional reason supplied when deciding a recognition hypothesis."""

    reason: str | None = None


class BiometricProjectionRevoke(BaseModel):
    """Optional reason supplied when revoking a biometric projection."""

    reason: str | None = None


def _require_gui_admin_for_agent(db: Any, *, user: AuthenticatedUser, agent_id: str) -> None:
    if not check_agent_permission(db, user_id=user.user_id, agent_id=agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")


def _active_consent_for_person(db: Any, *, agent_id: str, person_id: str, modality: str) -> dict[str, Any] | None:
    consent_type = str(modality or "").strip().lower()
    rows = db.query(
        """
        SELECT consent_id::TEXT AS consent_id, consent_type
        FROM consent_grants
        WHERE agent_id = :agent_id::uuid
          AND person_id = :person_id::uuid
          AND consent_type IN (:consent_type, 'global')
          AND revoked_at IS NULL
          AND (expires_at IS NULL OR expires_at > now())
        ORDER BY CASE WHEN consent_type = :consent_type THEN 0 ELSE 1 END, granted_at DESC
        LIMIT 1
        """,
        {"agent_id": agent_id, "person_id": person_id, "consent_type": consent_type},
    )
    return rows[0] if rows else None


def _require_active_recognition_consent(db: Any, *, agent_id: str, person_id: str, modality: str) -> dict[str, Any]:
    consent = _active_consent_for_person(db, agent_id=agent_id, person_id=person_id, modality=modality)
    if not consent:
        raise HTTPException(status_code=403, detail=f"Missing active consent for {modality}")
    return consent


def _recognition_vector_literal(values: list[float], expected_dim: int) -> str:
    if len(values) != expected_dim:
        raise HTTPException(
            status_code=400, detail=f"Invalid embedding dim (expected {expected_dim}, got {len(values)})"
        )
    return "[" + ",".join(f"{float(x):.6f}" for x in values) + "]"


def _projection_table_for_modality(modality: str) -> tuple[str, str, int]:
    normalized = str(modality or "").strip().lower()
    if normalized == "voice":
        return "voiceprints", "voiceprint_id", 256
    if normalized == "face":
        return "faceprints", "faceprint_id", 512
    raise HTTPException(status_code=400, detail="modality must be voice or face")


@app.post("/api/people", name="api_create_person")
def api_create_person(request: Request, body: PersonCreate) -> PersonResponse:
    """Create a new person."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Check user has admin permission on the agent
    if not check_agent_permission(db, user_id=user.user_id, agent_id=body.agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")

    person_id = str(uuid.uuid4())
    try:
        db.execute(
            """
            INSERT INTO people (person_id, agent_id, display_name)
            VALUES (:person_id::uuid, :agent_id::uuid, :display_name)
        """,
            {
                "person_id": person_id,
                "agent_id": body.agent_id,
                "display_name": body.display_name,
            },
        )
    except Exception as e:
        logger.error(f"Failed to create person: {e}")
        raise HTTPException(status_code=500, detail="Failed to create person")

    return PersonResponse(
        person_id=person_id,
        agent_id=body.agent_id,
        display_name=body.display_name,
    )


@app.post("/api/people/{person_id}/consent", name="api_update_consent")
def api_update_consent(request: Request, person_id: str, body: ConsentUpdate) -> dict:
    """Update consent grants for a person."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Get the person and check permission
    rows = db.query(
        """
        SELECT p.person_id, p.agent_id
        FROM people p
        INNER JOIN agent_memberships m ON p.agent_id = m.agent_id
        WHERE p.person_id = :person_id::uuid AND m.user_id = :user_id::uuid AND m.role IN ('admin', 'owner') AND m.revoked_at IS NULL
    """,
        {"person_id": person_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Person not found or permission denied")

    agent_id = str(rows[0].get("agent_id", ""))

    try:
        from datetime import datetime, timezone

        # First, revoke all existing active consents for this person
        db.execute(
            """
            UPDATE consent_grants SET revoked_at = :now::timestamptz
            WHERE person_id = :person_id::uuid AND revoked_at IS NULL
        """,
            {"person_id": person_id, "now": datetime.now(timezone.utc).isoformat()},
        )

        # Then create new consent grants
        for consent in body.consents:
            consent_id = str(uuid.uuid4())
            expires_at = _parse_expires_at(consent.expires_at)

            db.execute(
                """
                INSERT INTO consent_grants (consent_id, agent_id, person_id, consent_type, expires_at)
                VALUES (:consent_id::uuid, :agent_id::uuid, :person_id::uuid, :consent_type,
                        CASE WHEN :expires_at IS NULL THEN NULL ELSE :expires_at::timestamptz END)
            """,
                {
                    "consent_id": consent_id,
                    "agent_id": agent_id,
                    "person_id": person_id,
                    "consent_type": str(consent.type or "").strip().lower(),
                    "expires_at": expires_at.isoformat() if expires_at else None,
                },
            )

    except Exception as e:
        logger.error(f"Failed to update consent: {e}")
        raise HTTPException(status_code=500, detail="Failed to update consent")

    return {"message": "Consent updated", "person_id": person_id}


@app.get("/api/people/{person_id}/consent", name="api_get_consent")
def api_get_consent(request: Request, person_id: str) -> JSONResponse:
    """Get active consent grants for a person (GUI only)."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Requires admin/owner on the agent owning the person.
    rows = db.query(
        """
        SELECT p.person_id, p.agent_id
        FROM people p
        INNER JOIN agent_memberships m ON p.agent_id = m.agent_id
        WHERE p.person_id = :person_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.role IN ('admin', 'owner')
          AND m.revoked_at IS NULL
        """,
        {"person_id": person_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Person not found or permission denied")

    from datetime import datetime, timezone

    consent_rows = db.query(
        """
        SELECT consent_type, expires_at
        FROM consent_grants
        WHERE person_id = :person_id::uuid
          AND revoked_at IS NULL
          AND (expires_at IS NULL OR expires_at > :now::timestamptz)
        ORDER BY granted_at DESC
        """,
        {"person_id": person_id, "now": datetime.now(timezone.utc).isoformat()},
    )

    consents: list[dict[str, Any]] = []
    for r in consent_rows:
        ct = str(r.get("consent_type") or "").strip().lower()
        exp = r.get("expires_at")
        exp_date = None
        if exp:
            try:
                if hasattr(exp, "date"):
                    exp_date = exp.date().isoformat()
                else:
                    exp_date = str(exp)[:10]
            except Exception:
                exp_date = None
        consents.append({"type": ct, "expires_at": exp_date})

    resp = JSONResponse({"person_id": person_id, "consents": consents})
    resp.headers["Cache-Control"] = "no-store"
    return resp


@app.post("/api/recognition/enrollments", name="api_recognition_create_enrollment")
def api_recognition_create_enrollment(request: Request, body: RecognitionEnrollmentCreate) -> dict[str, Any]:
    """Create a consent-gated enrollment observation and optional biometric projection."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    modality = str(body.modality or "").strip().lower()
    table_name, id_column, expected_dim = _projection_table_for_modality(modality)
    if body.embedding is None and not (body.artifact_key or body.artifact_uri):
        raise HTTPException(status_code=400, detail="Enrollment requires an artifact or embedding")

    db = _get_db()
    person_rows = db.query(
        """
        SELECT person_id::TEXT AS person_id, agent_id::TEXT AS agent_id
        FROM people
        WHERE person_id = :person_id::uuid
        LIMIT 1
        """,
        {"person_id": body.person_id},
    )
    if not person_rows:
        raise HTTPException(status_code=404, detail="Person not found")

    agent_id = str(person_rows[0].get("agent_id") or "")
    _require_gui_admin_for_agent(db, user=user, agent_id=agent_id)
    consent = _require_active_recognition_consent(db, agent_id=agent_id, person_id=body.person_id, modality=modality)
    consent_id = str(consent.get("consent_id") or "")

    artifact_id: str | None = None
    if body.artifact_key or body.artifact_uri:
        artifact_id = str(uuid.uuid4())
        uri = body.artifact_uri or (
            f"s3://{body.artifact_bucket}/{body.artifact_key}" if body.artifact_bucket and body.artifact_key else None
        )
        db.execute(
            """
            INSERT INTO artifact_references (
              artifact_id, agent_id, bucket, object_key, uri, media_type, lifecycle_state
            )
            VALUES (
              :artifact_id::uuid, :agent_id::uuid, :bucket, :object_key, :uri, :media_type, 'available'
            )
            """,
            {
                "artifact_id": artifact_id,
                "agent_id": agent_id,
                "bucket": body.artifact_bucket,
                "object_key": body.artifact_key,
                "uri": uri,
                "media_type": body.content_type or ("audio/webm" if modality == "voice" else "image/jpeg"),
            },
        )

    observation_id = str(uuid.uuid4())
    db.execute(
        """
        INSERT INTO recognition_observations (
          recognition_observation_id, agent_id, artifact_id, modality, lifecycle_state, model
        )
        VALUES (
          :observation_id::uuid, :agent_id::uuid,
          CASE WHEN :artifact_id IS NULL THEN NULL ELSE :artifact_id::uuid END,
          :modality, :lifecycle_state, :model
        )
        """,
        {
            "observation_id": observation_id,
            "agent_id": agent_id,
            "artifact_id": artifact_id,
            "modality": modality,
            "lifecycle_state": "embedded" if body.embedding is not None else "observed",
            "model": body.model,
        },
    )

    hypothesis_id = str(uuid.uuid4())
    db.execute(
        """
        INSERT INTO recognition_hypotheses (
          identity_hypothesis_id, recognition_observation_id, candidate_person_id, consent_id,
          confidence, decision, reason, decided_at
        )
        VALUES (
          :hypothesis_id::uuid, :observation_id::uuid, :person_id::uuid, :consent_id::uuid,
          :confidence, 'accepted', 'consented enrollment', now()
        )
        """,
        {
            "hypothesis_id": hypothesis_id,
            "observation_id": observation_id,
            "person_id": body.person_id,
            "consent_id": consent_id,
            "confidence": 1.0,
        },
    )

    projection_id: str | None = None
    if body.embedding is not None:
        projection_id = str(uuid.uuid4())
        db.execute(
            f"""
            INSERT INTO {table_name} (
              {id_column}, agent_id, person_id, embedding, model, consent_id, metadata
            )
            VALUES (
              :projection_id::uuid, :agent_id::uuid, :person_id::uuid,
              CAST(:embedding AS vector), :model, :consent_id::uuid, :metadata::jsonb
            )
            """,
            {
                "projection_id": projection_id,
                "agent_id": agent_id,
                "person_id": body.person_id,
                "embedding": _recognition_vector_literal(body.embedding, expected_dim),
                "model": body.model or ("resemblyzer" if modality == "voice" else "insightface-arcface"),
                "consent_id": consent_id,
                "metadata": json.dumps(body.metadata or {}),
            },
        )

    return {
        "ok": True,
        "person_id": body.person_id,
        "agent_id": agent_id,
        "modality": modality,
        "consent_id": consent_id,
        "artifact_id": artifact_id,
        "observation_id": observation_id,
        "hypothesis_id": hypothesis_id,
        "projection_id": projection_id,
    }


@app.post("/api/recognition/hypotheses/{hypothesis_id}/accept", name="api_recognition_accept_hypothesis")
def api_recognition_accept_hypothesis(
    request: Request, hypothesis_id: str, body: RecognitionDecisionUpdate | None = None
) -> dict[str, Any]:
    """Accept a proposed recognition hypothesis with active consent."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    rows = db.query(
        """
        SELECT rh.identity_hypothesis_id::TEXT AS hypothesis_id,
               rh.recognition_observation_id::TEXT AS observation_id,
               rh.candidate_person_id::TEXT AS person_id,
               rh.confidence,
               ro.agent_id::TEXT AS agent_id,
               ro.space_id::TEXT AS space_id,
               ro.location_id::TEXT AS location_id,
               ro.modality
        FROM recognition_hypotheses rh
        JOIN recognition_observations ro ON ro.recognition_observation_id = rh.recognition_observation_id
        WHERE rh.identity_hypothesis_id = :hypothesis_id::uuid
        LIMIT 1
        """,
        {"hypothesis_id": hypothesis_id},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Hypothesis not found")

    row = rows[0]
    agent_id = str(row.get("agent_id") or "")
    person_id = str(row.get("person_id") or "")
    modality = str(row.get("modality") or "").strip().lower()
    if not person_id:
        raise HTTPException(status_code=400, detail="No candidate person to accept")

    _require_gui_admin_for_agent(db, user=user, agent_id=agent_id)
    consent = _require_active_recognition_consent(db, agent_id=agent_id, person_id=person_id, modality=modality)
    consent_id = str(consent.get("consent_id") or "")
    reason = (body.reason if body else None) or "accepted by operator"

    db.execute(
        """
        UPDATE recognition_hypotheses
        SET decision = 'accepted', consent_id = :consent_id::uuid, reason = :reason, decided_at = now()
        WHERE identity_hypothesis_id = :hypothesis_id::uuid
        """,
        {"hypothesis_id": hypothesis_id, "consent_id": consent_id, "reason": reason},
    )
    db.execute(
        """
        UPDATE recognition_hypotheses
        SET decision = 'rejected', reason = 'superseded by accepted hypothesis', decided_at = now()
        WHERE recognition_observation_id = :observation_id::uuid
          AND identity_hypothesis_id <> :hypothesis_id::uuid
          AND decision = 'proposed'
        """,
        {"observation_id": row.get("observation_id"), "hypothesis_id": hypothesis_id},
    )
    db.execute(
        """
        UPDATE recognition_observations
        SET lifecycle_state = 'matched'
        WHERE recognition_observation_id = :observation_id::uuid
        """,
        {"observation_id": row.get("observation_id")},
    )

    presence_id = str(uuid.uuid4())
    db.execute(
        """
        INSERT INTO presence_assertions (
          presence_assertion_id, agent_id, space_id, location_id, person_id,
          identity_hypothesis_id, confidence, status
        )
        VALUES (
          :presence_id::uuid, :agent_id::uuid,
          CASE WHEN :space_id IS NULL THEN NULL ELSE :space_id::uuid END,
          CASE WHEN :location_id IS NULL THEN NULL ELSE :location_id::uuid END,
          :person_id::uuid, :hypothesis_id::uuid, :confidence, 'present'
        )
        """,
        {
            "presence_id": presence_id,
            "agent_id": agent_id,
            "space_id": row.get("space_id"),
            "location_id": row.get("location_id"),
            "person_id": person_id,
            "hypothesis_id": hypothesis_id,
            "confidence": float(row.get("confidence") or 0.0),
        },
    )
    return {
        "ok": True,
        "hypothesis_id": hypothesis_id,
        "decision": "accepted",
        "consent_id": consent_id,
        "presence_assertion_id": presence_id,
    }


@app.post("/api/recognition/hypotheses/{hypothesis_id}/reject", name="api_recognition_reject_hypothesis")
def api_recognition_reject_hypothesis(
    request: Request, hypothesis_id: str, body: RecognitionDecisionUpdate | None = None
) -> dict[str, Any]:
    """Reject a recognition hypothesis without creating a person."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    rows = db.query(
        """
        SELECT ro.agent_id::TEXT AS agent_id
        FROM recognition_hypotheses rh
        JOIN recognition_observations ro ON ro.recognition_observation_id = rh.recognition_observation_id
        WHERE rh.identity_hypothesis_id = :hypothesis_id::uuid
        LIMIT 1
        """,
        {"hypothesis_id": hypothesis_id},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Hypothesis not found")

    agent_id = str(rows[0].get("agent_id") or "")
    _require_gui_admin_for_agent(db, user=user, agent_id=agent_id)
    db.execute(
        """
        UPDATE recognition_hypotheses
        SET decision = 'rejected', reason = :reason, decided_at = now()
        WHERE identity_hypothesis_id = :hypothesis_id::uuid
        """,
        {"hypothesis_id": hypothesis_id, "reason": (body.reason if body else None) or "rejected by operator"},
    )
    return {"ok": True, "hypothesis_id": hypothesis_id, "decision": "rejected"}


@app.post("/api/recognition/observations/{observation_id}/no-match", name="api_recognition_observation_no_match")
def api_recognition_observation_no_match(
    request: Request, observation_id: str, body: RecognitionDecisionUpdate | None = None
) -> dict[str, Any]:
    """Mark an observation as no-match without creating a person."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    rows = db.query(
        """
        SELECT recognition_observation_id::TEXT AS observation_id, agent_id::TEXT AS agent_id
        FROM recognition_observations
        WHERE recognition_observation_id = :observation_id::uuid
        LIMIT 1
        """,
        {"observation_id": observation_id},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Observation not found")

    agent_id = str(rows[0].get("agent_id") or "")
    _require_gui_admin_for_agent(db, user=user, agent_id=agent_id)
    reason = (body.reason if body else None) or "marked no-match by operator"
    db.execute(
        """
        UPDATE recognition_observations
        SET lifecycle_state = 'no_match'
        WHERE recognition_observation_id = :observation_id::uuid
        """,
        {"observation_id": observation_id},
    )
    db.execute(
        """
        UPDATE recognition_hypotheses
        SET decision = 'rejected', reason = :reason, decided_at = now()
        WHERE recognition_observation_id = :observation_id::uuid
          AND decision = 'proposed'
        """,
        {"observation_id": observation_id, "reason": reason},
    )
    no_match_hypothesis_id = str(uuid.uuid4())
    db.execute(
        """
        INSERT INTO recognition_hypotheses (
          identity_hypothesis_id, recognition_observation_id, candidate_person_id,
          confidence, decision, reason, decided_at
        )
        VALUES (
          :hypothesis_id::uuid, :observation_id::uuid, NULL,
          0, 'no_match', :reason, now()
        )
        """,
        {"hypothesis_id": no_match_hypothesis_id, "observation_id": observation_id, "reason": reason},
    )
    return {
        "ok": True,
        "observation_id": observation_id,
        "decision": "no_match",
        "hypothesis_id": no_match_hypothesis_id,
    }


@app.post("/api/recognition/biometrics/{projection_id}/revoke", name="api_recognition_revoke_biometric")
def api_recognition_revoke_biometric(
    request: Request, projection_id: str, body: BiometricProjectionRevoke | None = None
) -> dict[str, Any]:
    """Revoke an active voiceprint or faceprint projection."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    rows = db.query(
        """
        SELECT 'voice' AS modality, voiceprint_id::TEXT AS projection_id,
               agent_id::TEXT AS agent_id, person_id::TEXT AS person_id
        FROM voiceprints
        WHERE voiceprint_id = :projection_id::uuid
        UNION ALL
        SELECT 'face' AS modality, faceprint_id::TEXT AS projection_id,
               agent_id::TEXT AS agent_id, person_id::TEXT AS person_id
        FROM faceprints
        WHERE faceprint_id = :projection_id::uuid
        LIMIT 1
        """,
        {"projection_id": projection_id},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Biometric projection not found")

    row = rows[0]
    modality = str(row.get("modality") or "")
    table_name, id_column, _expected_dim = _projection_table_for_modality(modality)
    agent_id = str(row.get("agent_id") or "")
    _require_gui_admin_for_agent(db, user=user, agent_id=agent_id)
    metadata = {"revocation_reason": (body.reason if body else None) or "revoked by operator"}
    db.execute(
        f"""
        UPDATE {table_name}
        SET revoked_at = now(),
            metadata = COALESCE(metadata, '{{}}'::jsonb) || :metadata::jsonb
        WHERE {id_column} = :projection_id::uuid
        """,
        {"projection_id": projection_id, "metadata": json.dumps(metadata)},
    )
    return {"ok": True, "projection_id": projection_id, "modality": modality, "revoked": True}


class PersonUpdate(BaseModel):
    display_name: str = Field(..., min_length=1, max_length=255)


@app.patch("/api/people/{person_id}", name="api_update_person")
def api_update_person(request: Request, person_id: str, body: PersonUpdate) -> dict:
    """Update a person's display name."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Check the person exists and user has admin permission on the agent
    rows = db.query(
        """
        SELECT p.person_id, p.agent_id, p.display_name
        FROM people p
        INNER JOIN agent_memberships mb ON p.agent_id = mb.agent_id
        WHERE p.person_id = :person_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN ('admin', 'owner')
          AND mb.revoked_at IS NULL
    """,
        {"person_id": person_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Person not found or permission denied")

    try:
        db.execute(
            """
            UPDATE people SET display_name = :display_name WHERE person_id = :person_id::uuid
        """,
            {"person_id": person_id, "display_name": body.display_name},
        )
    except Exception as e:
        logger.error(f"Failed to update person: {e}")
        raise HTTPException(status_code=500, detail="Failed to update person")

    return {"message": "Person updated", "person_id": person_id, "display_name": body.display_name}


@app.get("/api/people/{person_id}", name="api_get_person")
def api_get_person(request: Request, person_id: str) -> dict:
    """Get a person's details."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    rows = db.query(
        """
        SELECT p.person_id::TEXT as person_id, p.agent_id::TEXT as agent_id,
               p.display_name, p.created_at::TEXT as created_at, a.name as agent_name
        FROM people p
        INNER JOIN agents a ON p.agent_id = a.agent_id
        INNER JOIN agent_memberships mb ON p.agent_id = mb.agent_id
        WHERE p.person_id = :person_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN ('member', 'admin', 'owner')
          AND mb.revoked_at IS NULL
    """,
        {"person_id": person_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Person not found or permission denied")

    row = rows[0]
    return {
        "person_id": row["person_id"],
        "agent_id": row["agent_id"],
        "agent_name": row.get("agent_name", ""),
        "display_name": row["display_name"],
        "created_at": row["created_at"],
    }


class PersonLinkAccount(BaseModel):
    email: str | None = None
    user_id: str | None = None


@app.post("/api/people/{person_id}/link-account", name="api_link_person_account")
def api_link_person_account(request: Request, person_id: str, body: PersonLinkAccount) -> dict:
    """Link a Cognito user (users.user_id) to a Person for the owning agent."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    rows = db.query(
        """
        SELECT p.agent_id::TEXT as agent_id
        FROM people p
        JOIN agent_memberships m ON p.agent_id = m.agent_id
        WHERE p.person_id = :person_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.role IN ('admin', 'owner')
          AND m.revoked_at IS NULL
        LIMIT 1
        """,
        {"person_id": person_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Person not found or permission denied")

    agent_id = str(rows[0].get("agent_id") or "").strip()
    link_user_id = str(body.user_id or "").strip()
    email = str(body.email or "").strip()
    if not link_user_id and not email:
        raise HTTPException(status_code=400, detail="email or user_id is required")

    if email:
        if not _cfg.cognito_user_pool_id:
            raise HTTPException(status_code=500, detail="COGNITO_USER_POOL_ID not configured")
        try:
            cognito_sub, resolved_email = lookup_cognito_user_by_email(
                user_pool_id=_cfg.cognito_user_pool_id,
                email=email,
            )
        except LookupError as exc:
            raise HTTPException(status_code=404, detail=str(exc))
        link_user_id = ensure_user_row(db, cognito_sub=cognito_sub, email=(resolved_email or email))

    urows = db.query("SELECT 1 FROM users WHERE user_id = :user_id::uuid LIMIT 1", {"user_id": link_user_id})
    if not urows:
        raise HTTPException(status_code=404, detail="User not found")

    tx = db.begin()
    try:
        db.execute(
            """
            DELETE FROM person_accounts
            WHERE agent_id = :agent_id::uuid
              AND (user_id = :user_id::uuid OR person_id = :person_id::uuid)
            """,
            {"agent_id": agent_id, "user_id": link_user_id, "person_id": person_id},
            transaction_id=tx,
        )
        db.execute(
            """
            INSERT INTO person_accounts(person_account_id, agent_id, user_id, person_id)
            VALUES(:id::uuid, :agent_id::uuid, :user_id::uuid, :person_id::uuid)
            """,
            {"id": str(uuid.uuid4()), "agent_id": agent_id, "user_id": link_user_id, "person_id": person_id},
            transaction_id=tx,
        )
        db.commit(tx)
    except Exception:
        db.rollback(tx)
        raise

    return {"ok": True, "agent_id": agent_id, "person_id": person_id, "user_id": link_user_id}


class EnrollmentArtifactIn(BaseModel):
    artifact_key: str
    artifact_bucket: str | None = None
    content_type: str | None = None
    space_id: str | None = None


def _pick_space_for_agent(*, db, agent_id: str) -> str:
    rows = db.query(
        "SELECT space_id::TEXT as space_id FROM spaces WHERE agent_id = :agent_id::uuid ORDER BY created_at ASC LIMIT 1",
        {"agent_id": agent_id},
    )
    if not rows or not rows[0].get("space_id"):
        raise HTTPException(status_code=400, detail="Agent has no spaces (create a space first)")
    return str(rows[0]["space_id"])


def _enqueue_recognition_event(
    *, event_id: str, agent_id: str, space_id: str, person_id: str, event_type: str, payload: dict
) -> bool:
    qurl = str(os.getenv("RECOGNITION_QUEUE_URL", "")).strip()
    if not qurl:
        return False
    try:
        _get_sqs().send_message(
            QueueUrl=qurl,
            MessageBody=json.dumps(
                {
                    "event_id": event_id,
                    "agent_id": agent_id,
                    "space_id": space_id,
                    "device_id": None,
                    "person_id": person_id,
                    "type": event_type,
                    "payload": payload,
                }
            ),
        )
        return True
    except Exception as exc:
        logger.warning("Failed to enqueue recognition event: %s", exc)
        return False


def _create_recognition_event(
    *, request: Request, person_id: str, event_type: str, artifact: EnrollmentArtifactIn
) -> dict[str, Any]:
    """Server-side ingestion for enrollment events (browser -> S3 -> queue)."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    rows = db.query(
        """
        SELECT p.person_id::TEXT as person_id,
               p.agent_id::TEXT as agent_id
        FROM people p
        JOIN agent_memberships m ON p.agent_id = m.agent_id
        WHERE p.person_id = :person_id::uuid
          AND m.user_id = :user_id::uuid
          AND m.role IN ('admin', 'owner')
          AND m.revoked_at IS NULL
        LIMIT 1
        """,
        {"person_id": person_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Person not found or permission denied")
    agent_id = str(rows[0].get("agent_id") or "").strip()
    modality = "voice" if event_type == "voice.sample" else "face" if event_type == "face.snapshot" else ""
    if modality:
        _require_active_recognition_consent(db, agent_id=agent_id, person_id=person_id, modality=modality)

    # Choose a space for anchoring the event (events require space_id).
    space_id = str(artifact.space_id or "").strip()
    if space_id:
        # Ensure the space belongs to the same agent and the user can access it.
        srows = db.query(
            """
            SELECT 1
            FROM spaces s
            JOIN agent_memberships m ON s.agent_id = m.agent_id
            WHERE s.space_id = :space_id::uuid
              AND s.agent_id = :agent_id::uuid
              AND m.user_id = :user_id::uuid
              AND m.revoked_at IS NULL
            LIMIT 1
            """,
            {"space_id": space_id, "agent_id": agent_id, "user_id": str(user.user_id)},
        )
        if not srows:
            raise HTTPException(status_code=404, detail="Space not found")
    else:
        space_id = _pick_space_for_agent(db=db, agent_id=agent_id)

    artifact_key = str(artifact.artifact_key or "").strip()
    if not artifact_key:
        raise HTTPException(status_code=400, detail="artifact_key is required")
    artifact_bucket = str(artifact.artifact_bucket or "").strip() or str(_cfg.artifact_bucket or "").strip()
    if not artifact_bucket:
        raise HTTPException(status_code=500, detail="Artifact bucket not configured")

    payload = {
        "artifact_bucket": artifact_bucket,
        "artifact_key": artifact_key,
        "content_type": artifact.content_type,
        "enroll_person_id": person_id,
        "source": "browser_enrollment",
    }

    event_id = str(uuid.uuid4())
    db.execute(
        """
        INSERT INTO events(event_id, agent_id, space_id, person_id, type, payload)
        VALUES(:event_id::uuid, :agent_id::uuid, :space_id::uuid, :person_id::uuid, :type, :payload::jsonb)
        """,
        {
            "event_id": event_id,
            "agent_id": agent_id,
            "space_id": space_id,
            "person_id": person_id,
            "type": event_type,
            "payload": json.dumps(payload),
        },
    )

    queued = _enqueue_recognition_event(
        event_id=event_id,
        agent_id=agent_id,
        space_id=space_id,
        person_id=person_id,
        event_type=event_type,
        payload=payload,
    )

    try:
        broadcast_event(
            event_type="events.new",
            agent_id=agent_id,
            space_id=space_id,
            payload={"event": {"event_id": event_id, "type": event_type, "payload": payload, "person_id": person_id}},
        )
    except Exception:
        pass

    return {"ok": True, "event_id": event_id, "queued": queued, "space_id": space_id}


@app.post("/api/people/{person_id}/enroll/voice", name="api_enroll_voice")
def api_enroll_voice(request: Request, person_id: str, body: EnrollmentArtifactIn) -> dict[str, Any]:
    return _create_recognition_event(request=request, person_id=person_id, event_type="voice.sample", artifact=body)


@app.post("/api/people/{person_id}/enroll/face", name="api_enroll_face")
def api_enroll_face(request: Request, person_id: str, body: EnrollmentArtifactIn) -> dict[str, Any]:
    return _create_recognition_event(request=request, person_id=person_id, event_type="face.snapshot", artifact=body)


@app.get("/people", name="gui_people")
def gui_people(request: Request) -> Response:
    """People & consent management."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/people")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)
    spaces = list_spaces_for_user(db, user_id=user.user_id)

    # Get people for all agents the user has access to
    agent_ids = [a.agent_id for a in agents]
    people_data = []
    if agent_ids:
        from datetime import datetime, timezone

        placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
        params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
        rows = db.query(
            f"""SELECT p.person_id::TEXT as person_id, p.agent_id::TEXT as agent_id,
                       p.display_name, p.created_at,
                       a.name as agent_name
                FROM people p
                JOIN agents a ON a.agent_id = p.agent_id
                WHERE p.agent_id::TEXT IN ({placeholders})
                ORDER BY p.created_at DESC""",
            params,
        )

        # Build person list with consent status
        for row in rows:
            person_id = str(row.get("person_id", ""))
            created_at = row.get("created_at")
            created_at_relative = None
            if created_at:
                try:
                    if hasattr(created_at, "tzinfo"):
                        now = datetime.now(timezone.utc)
                        delta = now - created_at
                        if delta.days > 0:
                            created_at_relative = f"{delta.days}d ago"
                        elif delta.seconds >= 3600:
                            created_at_relative = f"{delta.seconds // 3600}h ago"
                        else:
                            created_at_relative = f"{delta.seconds // 60}m ago"
                except Exception:
                    pass

            # Get active consents for this person
            consent_rows = db.query(
                """
                SELECT consent_type, expires_at
                FROM consent_grants
                WHERE person_id = :person_id::uuid AND revoked_at IS NULL
                  AND (expires_at IS NULL OR expires_at > :now::timestamptz)
            """,
                {"person_id": person_id, "now": datetime.now(timezone.utc).isoformat()},
            )

            global_consent = None
            voice_consent = None
            face_consent = None
            recording_consent = None
            for cr in consent_rows:
                ct = str(cr.get("consent_type", "") or "").strip().lower()
                exp = cr.get("expires_at")
                exp_str = str(exp)[:10] if exp else "No expiry"
                if ct == "global":
                    global_consent = exp_str
                elif ct == "voice":
                    voice_consent = exp_str
                elif ct == "face":
                    face_consent = exp_str
                elif ct == "recording":
                    recording_consent = exp_str

            people_data.append(
                {
                    "person_id": person_id,
                    "agent_id": str(row.get("agent_id", "")),
                    "agent_name": row.get("agent_name", ""),
                    "display_name": row.get("display_name", ""),
                    "created_at_relative": created_at_relative,
                    "global_consent": global_consent,
                    "voice_consent": voice_consent,
                    "face_consent": face_consent,
                    "recording_consent": recording_consent,
                    "active_consents": bool(global_consent or voice_consent or face_consent or recording_consent),
                }
            )

    agents_data = [{"agent_id": a.agent_id, "name": a.name, "role": a.role} for a in agents]

    # Build spaces/devices by agent for enrollment UI.
    spaces_by_agent: dict[str, list[dict[str, Any]]] = {}
    for s in spaces:
        agent_id = str(s.agent_id)
        spaces_by_agent.setdefault(agent_id, []).append(
            {"space_id": str(s.space_id), "name": s.name, "livekit_room_mode": str(getattr(s, "livekit_room_mode", ""))}
        )

    devices_by_agent: dict[str, list[dict[str, Any]]] = {}
    if agent_ids:
        import json as json_mod

        placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
        params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
        rows = db.query(
            f"""SELECT d.device_id::TEXT as device_id, d.agent_id::TEXT as agent_id,
                       d.name, d.location_label, d.metadata,
                       CASE
                           WHEN d.last_heartbeat_at > now() - interval '60 seconds' THEN true
                           ELSE false
                       END as is_online,
                       a.name as agent_name
                FROM devices d
                JOIN agents a ON a.agent_id = d.agent_id
                WHERE d.agent_id::TEXT IN ({placeholders})
                  AND d.revoked_at IS NULL
                ORDER BY d.location_label NULLS LAST, d.created_at DESC""",
            params,
        )
        for r in rows:
            meta = r.get("metadata") or {}
            if isinstance(meta, str):
                try:
                    meta = json_mod.loads(meta)
                except Exception:
                    meta = {}
            if not isinstance(meta, dict):
                meta = {}
            agent_id = str(r.get("agent_id") or "")
            devices_by_agent.setdefault(agent_id, []).append(
                {
                    "device_id": str(r.get("device_id") or ""),
                    "name": str(r.get("name") or "Unnamed Device"),
                    "agent_id": agent_id,
                    "agent_name": str(r.get("agent_name") or ""),
                    "is_online": bool(r.get("is_online")),
                    "location_label": str(r.get("location_label") or ""),
                    "metadata": meta,
                    "location_space_id": str(meta.get("location_space_id") or ""),
                }
            )

    return templates.TemplateResponse(
        request,
        "people.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "people",
            "people": people_data,
            "agents": agents_data,
            "spaces_by_agent": spaces_by_agent,
            "devices_by_agent": devices_by_agent,
            **_get_ws_context(request),
        },
    )


@app.get("/actions", name="gui_actions")
def gui_actions(request: Request) -> Response:
    """Actions dashboard - pending actions and history."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/actions")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)
    spaces = list_spaces_for_user(db, user_id=user.user_id)

    # Get actions for all agents the user has access to
    agent_ids = [a.agent_id for a in agents]
    actions_data = []
    status_counts = {"proposed": 0, "approved": 0, "executed": 0, "failed": 0}
    action_kinds_set: set = set()

    if agent_ids:
        import json
        from datetime import datetime, timezone

        placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
        params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
        rows = db.query(
            f"""SELECT ac.action_id::TEXT as action_id, ac.agent_id::TEXT as agent_id,
                       ac.space_id::TEXT as space_id, ac.kind, ac.payload,
                       ac.required_scopes, ac.status, ac.created_at, ac.updated_at, ac.executed_at,
                       a.name as agent_name, s.name as space_name
                FROM actions ac
                JOIN agents a ON a.agent_id = ac.agent_id
                LEFT JOIN spaces s ON s.space_id = ac.space_id
                WHERE ac.agent_id::TEXT IN ({placeholders})
                ORDER BY ac.created_at DESC
                LIMIT 100""",
            params,
        )

        for row in rows:
            status = row.get("status", "")
            if status in status_counts:
                status_counts[status] += 1

            kind = row.get("kind", "")
            action_kinds_set.add(kind)

            created_at = row.get("created_at")
            created_at_relative = None
            if created_at:
                try:
                    if hasattr(created_at, "tzinfo"):
                        now = datetime.now(timezone.utc)
                        delta = now - created_at
                        if delta.days > 0:
                            created_at_relative = f"{delta.days}d ago"
                        elif delta.seconds >= 3600:
                            created_at_relative = f"{delta.seconds // 3600}h ago"
                        else:
                            created_at_relative = f"{delta.seconds // 60}m ago"
                except Exception:
                    pass

            payload = row.get("payload") or {}
            if isinstance(payload, str):
                try:
                    payload = json.loads(payload)
                except Exception:
                    payload = {}
            payload_str = json.dumps(payload) if payload else "{}"
            payload_preview = payload_str[:150] + ("..." if len(payload_str) > 150 else "")

            required_scopes = row.get("required_scopes") or []
            if isinstance(required_scopes, str):
                try:
                    required_scopes = json.loads(required_scopes)
                except Exception:
                    required_scopes = []

            actions_data.append(
                {
                    "action_id": str(row.get("action_id", "")),
                    "agent_id": str(row.get("agent_id", "")),
                    "agent_name": row.get("agent_name", ""),
                    "space_id": str(row.get("space_id", "")) if row.get("space_id") else None,
                    "space_name": row.get("space_name"),
                    "kind": kind,
                    "status": status,
                    "payload_str": payload_str,
                    "payload_preview": payload_preview,
                    "required_scopes": required_scopes,
                    "created_at_relative": created_at_relative,
                }
            )

    agents_data = [{"agent_id": a.agent_id, "name": a.name, "role": a.role} for a in agents]

    # Build spaces by agent for the create modal
    spaces_by_agent: dict = {}
    for space in spaces:
        agent_id = str(space.agent_id)
        if agent_id not in spaces_by_agent:
            spaces_by_agent[agent_id] = []
        spaces_by_agent[agent_id].append(
            {
                "space_id": str(space.space_id),
                "name": space.name,
            }
        )

    # Merge registered tool names so new tools appear even before any actions use them.
    from agent_hub.tools.registry import get_registry as _get_tool_registry

    action_kinds_set.update(t.name for t in _get_tool_registry().list_tools())

    return templates.TemplateResponse(
        request,
        "actions.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "actions",
            "actions": actions_data,
            "status_counts": status_counts,
            "action_kinds": sorted(action_kinds_set),
            "agents": agents_data,
            "spaces_by_agent": spaces_by_agent,
            **_get_ws_context(request),
        },
    )


@app.get("/actions/guide", name="gui_actions_guide")
def gui_actions_guide(request: Request) -> Response:
    """Actions guide - detailed documentation on configuring valid actions."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/actions/guide")

    return templates.TemplateResponse(
        request,
        "actions_guide.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "actions",
            **_get_ws_context(request),
        },
    )


# ---------------------------------------------------------------------------
# Tools (Tool Registry Catalog)
# ---------------------------------------------------------------------------


@app.get("/tools", name="gui_tools")
def gui_tools(request: Request) -> Response:
    """Tool catalog - list all registered tools."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/tools")

    from agent_hub.tools.registry import get_registry

    registry = get_registry()
    tools_data = [t.to_dict() for t in registry.list_tools()]

    return templates.TemplateResponse(
        request,
        "tools.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "tools",
            "tools": tools_data,
            **_get_ws_context(request),
        },
    )


@app.get("/api/tools", name="api_gui_tools")
def api_gui_tools(request: Request) -> JSONResponse:
    """Return all registered tools as JSON (GUI-authenticated)."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    from agent_hub.tools.registry import get_registry

    registry = get_registry()
    return JSONResponse({"tools": [t.to_dict() for t in registry.list_tools()]})


class ActionApproveReject(BaseModel):
    reason: str | None = None


@app.get("/api/actions/diagnostics", name="api_actions_diagnostics")
def api_actions_diagnostics(request: Request) -> dict:
    """Return Action Queue health and recent Tool Runner Lambda executions."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    import boto3 as _boto3

    region = _cfg.cognito_region or os.getenv("AWS_REGION", "us-east-1")

    # --- SQS queue health ---
    queue_health: dict = {"messages_available": None, "messages_in_flight": None, "error": None}
    if _cfg.action_queue_url:
        try:
            sqs = _get_sqs()
            attrs = sqs.get_queue_attributes(
                QueueUrl=_cfg.action_queue_url,
                AttributeNames=[
                    "ApproximateNumberOfMessages",
                    "ApproximateNumberOfMessagesNotVisible",
                    "ApproximateNumberOfMessagesDelayed",
                ],
            ).get("Attributes", {})
            queue_health["messages_available"] = int(attrs.get("ApproximateNumberOfMessages", 0))
            queue_health["messages_in_flight"] = int(attrs.get("ApproximateNumberOfMessagesNotVisible", 0))
            queue_health["messages_delayed"] = int(attrs.get("ApproximateNumberOfMessagesDelayed", 0))
        except Exception:
            logger.warning("Failed to read action queue health", exc_info=True)
            queue_health["error"] = "Action queue health is unavailable."
    else:
        queue_health["error"] = "ACTION_QUEUE_URL not configured"

    # --- Recent Tool Runner Lambda executions (from CloudWatch Logs) ---
    recent_executions: list[dict] = []
    logs_error: str | None = None
    # Derive log group from stack name or env
    stack_name = os.getenv("STACK_NAME", "")
    log_group = os.getenv(
        "TOOL_RUNNER_LOG_GROUP",
        f"/aws/lambda/{stack_name}-ToolRunnerFunction" if stack_name else "",
    )
    if not log_group:
        # Try to find it via the marvain config
        try:
            mcfg = _read_marvain_config()
            default_env = mcfg.get("default_env", "dev")
            env_cfg = mcfg.get("envs", {}).get(default_env, {})
            sn = env_cfg.get("stack_name", "")
            if sn:
                log_group = f"/aws/lambda/{sn}-ToolRunnerFunction"
        except Exception:
            pass

    if log_group:
        try:
            logs_client = _boto3.client("logs", region_name=region)
            import time as _time

            end_ms = int(_time.time() * 1000)
            start_ms = end_ms - (3600 * 1000)  # last hour

            resp = logs_client.filter_log_events(
                logGroupName=log_group,
                startTime=start_ms,
                endTime=end_ms,
                filterPattern="processed",
                limit=20,
                interleaved=True,
            )
            for ev in resp.get("events", []):
                ts = ev.get("timestamp", 0)
                recent_executions.append(
                    {
                        "timestamp": ts,
                        "timestamp_iso": __import__("datetime")
                        .datetime.fromtimestamp(ts / 1000, tz=__import__("datetime").timezone.utc)
                        .isoformat()
                        if ts
                        else None,
                        "message": "Tool runner processed an event.",
                        "log_stream": ev.get("logStreamName", ""),
                    }
                )
        except Exception:
            logger.warning("Failed to read tool runner logs", exc_info=True)
            logs_error = "Tool runner logs are unavailable."
    else:
        logs_error = "Could not determine Tool Runner log group"

    # --- Per-action status breakdown (recent) ---
    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)
    agent_ids = [a.agent_id for a in agents]
    action_timeline: list[dict] = []
    if agent_ids:
        placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
        params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
        rows = db.query(
            f"""SELECT action_id::TEXT, agent_id::TEXT, kind, status,
                       created_at::TEXT, updated_at::TEXT, approved_at::TEXT,
                       executed_at::TEXT, completed_at::TEXT,
                       result::TEXT, error
                FROM actions
                WHERE agent_id::TEXT IN ({placeholders})
                ORDER BY created_at DESC LIMIT 20""",
            params,
        )
        for row in rows:
            action_timeline.append(
                {
                    "action_id": row.get("action_id"),
                    "agent_id": row.get("agent_id"),
                    "kind": row.get("kind"),
                    "status": row.get("status"),
                    "created_at": row.get("created_at"),
                    "approved_at": row.get("approved_at"),
                    "executed_at": row.get("executed_at"),
                    "completed_at": row.get("completed_at"),
                    "error": "Action failed." if row.get("error") else None,
                }
            )

    return {
        "queue_health": queue_health,
        "recent_executions": recent_executions,
        "logs_error": logs_error,
        "log_group": log_group,
        "action_timeline": action_timeline,
        "region": region,
    }


@app.get("/api/actions/{action_id}", name="api_get_action")
def api_get_action(request: Request, action_id: str) -> dict:
    """Get action details."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Get the action and check permission (member role sufficient for viewing)
    rows = db.query(
        """
        SELECT ac.action_id::TEXT as action_id, ac.agent_id::TEXT as agent_id,
               ac.space_id::TEXT as space_id, ac.kind, ac.payload::TEXT as payload,
               ac.required_scopes::TEXT as required_scopes, ac.status,
               ac.created_at::TEXT as created_at, ac.updated_at::TEXT as updated_at,
               ac.executed_at::TEXT as executed_at, ac.approved_by::TEXT as approved_by,
               ac.approved_at::TEXT as approved_at, ac.result::TEXT as result,
               ac.error, ac.completed_at::TEXT as completed_at,
               a.name as agent_name, s.name as space_name
        FROM actions ac
        INNER JOIN agents a ON ac.agent_id = a.agent_id
        LEFT JOIN spaces s ON ac.space_id = s.space_id
        INNER JOIN agent_memberships mb ON ac.agent_id = mb.agent_id
        WHERE ac.action_id = :action_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN ('member', 'admin', 'owner')
          AND mb.revoked_at IS NULL
    """,
        {"action_id": action_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Action not found or permission denied")

    row = rows[0]

    # Parse JSON fields
    try:
        payload = json.loads(row.get("payload") or "{}")
    except Exception:
        payload = {}
    try:
        required_scopes = json.loads(row.get("required_scopes") or "[]")
    except Exception:
        required_scopes = []
    try:
        result = json.loads(row.get("result") or "null")
    except Exception:
        result = row.get("result")

    return {
        "action_id": row["action_id"],
        "agent_id": row["agent_id"],
        "agent_name": row.get("agent_name", ""),
        "space_id": row.get("space_id"),
        "space_name": row.get("space_name"),
        "kind": row["kind"],
        "payload": payload,
        "required_scopes": required_scopes,
        "status": row["status"],
        "created_at": row["created_at"],
        "updated_at": row.get("updated_at"),
        "executed_at": row.get("executed_at"),
        "approved_by": row.get("approved_by"),
        "approved_at": row.get("approved_at"),
        "result": result,
        "error": row.get("error"),
        "completed_at": row.get("completed_at"),
    }


@app.post("/api/actions/{action_id}/approve", name="api_approve_action")
def api_approve_action(request: Request, action_id: str) -> dict:
    """Approve a proposed action."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Get the action and check permission (admin/owner only)
    rows = db.query(
        """
        SELECT ac.action_id, ac.agent_id, ac.status
        FROM actions ac
        INNER JOIN agent_memberships mb ON ac.agent_id = mb.agent_id
        WHERE ac.action_id = :action_id::uuid AND mb.user_id = :user_id::uuid AND mb.role IN ('admin', 'owner') AND mb.revoked_at IS NULL
    """,
        {"action_id": action_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Action not found or permission denied")

    action = rows[0]
    if action.get("status") != "proposed":
        raise HTTPException(
            status_code=400, detail=f"Action is not in proposed status (current: {action.get('status')})"
        )

    try:
        approve_action(
            db,
            action_id=action_id,
            user_id=str(user.user_id),
            audit_bucket=_cfg.audit_bucket,
            sqs_client=_get_sqs(),
            action_queue_url=_cfg.action_queue_url,
        )
    except ActionServiceError as exc:
        if exc.code == "action_not_found":
            raise HTTPException(status_code=404, detail="Action not found") from exc
        if exc.code == "invalid_status":
            current_status = exc.extra.get("current_status")
            raise HTTPException(
                status_code=400,
                detail=f"Action is not in proposed status (current: {current_status})",
            ) from exc
        logger.error("Failed to approve action %s: %s", action_id, exc)
        raise HTTPException(status_code=500, detail="Failed to approve action") from exc

    return {"message": "Action approved", "action_id": action_id, "status": "approved"}


@app.post("/api/actions/{action_id}/reject", name="api_reject_action")
def api_reject_action(request: Request, action_id: str, body: ActionApproveReject | None = None) -> dict:
    """Reject a proposed action."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Get the action and check permission (admin/owner only)
    rows = db.query(
        """
        SELECT ac.action_id, ac.agent_id, ac.status
        FROM actions ac
        INNER JOIN agent_memberships mb ON ac.agent_id = mb.agent_id
        WHERE ac.action_id = :action_id::uuid AND mb.user_id = :user_id::uuid AND mb.role IN ('admin', 'owner') AND mb.revoked_at IS NULL
    """,
        {"action_id": action_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Action not found or permission denied")

    action = rows[0]
    if action.get("status") != "proposed":
        raise HTTPException(
            status_code=400, detail=f"Action is not in proposed status (current: {action.get('status')})"
        )

    try:
        reject_action(
            db,
            action_id=action_id,
            user_id=str(user.user_id),
            reason=(body.reason if body else ""),
            audit_bucket=_cfg.audit_bucket,
        )
    except ActionServiceError as exc:
        if exc.code == "action_not_found":
            raise HTTPException(status_code=404, detail="Action not found") from exc
        if exc.code == "invalid_status":
            current_status = exc.extra.get("current_status")
            raise HTTPException(
                status_code=400,
                detail=f"Action is not in proposed status (current: {current_status})",
            ) from exc
        logger.error("Failed to reject action %s: %s", action_id, exc)
        raise HTTPException(status_code=500, detail="Failed to reject action") from exc

    return {"message": "Action rejected", "action_id": action_id, "status": "rejected"}


class ActionCreate(BaseModel):
    agent_id: str
    space_id: str | None = None
    kind: str
    payload: dict
    required_scopes: list[str] = []
    auto_approve: bool = False
    idempotency_key: str


class PersonaCreate(BaseModel):
    agent_id: str
    name: str
    instructions: str
    is_default: bool = False


class LiveSessionSmokeIn(BaseModel):
    seed: str = "marvain-gui-live-session-smoke"
    transcript_text: str
    agent_id: str | None = None
    space_id: str | None = None
    device_id: str | None = None


class LiveSessionChatIn(BaseModel):
    text: str = Field(..., min_length=1, max_length=4000)


def _live_session_config_error() -> str | None:
    if not str(_cfg.livekit_url or "").strip():
        return "LIVEKIT_URL not configured"
    if not str(_cfg.livekit_secret_arn or "").strip():
        return "LIVEKIT_SECRET_ARN not configured"
    if not str(_cfg.openai_secret_arn or "").strip():
        return "OPENAI_SECRET_ARN not configured"
    return None


def _require_live_session_config() -> None:
    error = _live_session_config_error()
    if error:
        raise HTTPException(status_code=503, detail=error)

    try:
        livekit_secret = get_secret_json(str(_cfg.livekit_secret_arn))
    except Exception as exc:
        raise HTTPException(status_code=503, detail=f"Failed to read LiveKit secret: {exc}") from exc
    if _is_placeholder(str(livekit_secret.get("api_key") or "")) or _is_placeholder(
        str(livekit_secret.get("api_secret") or "")
    ):
        raise HTTPException(status_code=503, detail="LiveKit secret missing api_key/api_secret")

    try:
        openai_secret = get_secret_json(str(_cfg.openai_secret_arn))
    except Exception as exc:
        raise HTTPException(status_code=503, detail=f"Failed to read OpenAI secret: {exc}") from exc
    if _is_placeholder(str(openai_secret.get("api_key") or "")):
        raise HTTPException(status_code=503, detail="OpenAI secret missing api_key")


def _live_session_for_user(db: Any, *, user: AuthenticatedUser, session_id: str) -> dict[str, Any]:
    rows = db.query(
        """
        SELECT se.session_id::TEXT AS session_id, se.agent_id::TEXT AS agent_id,
               se.space_id::TEXT AS space_id, se.livekit_room, se.status,
               a.name AS agent_name, sp.name AS space_name
        FROM sessions se
        JOIN agents a ON a.agent_id = se.agent_id
        LEFT JOIN spaces sp ON sp.space_id = se.space_id
        JOIN agent_memberships mb ON mb.agent_id = se.agent_id
        WHERE se.session_id = :session_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN ('member', 'admin', 'owner')
          AND mb.revoked_at IS NULL
        LIMIT 1
        """,
        {"session_id": session_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Live session not found")
    return dict(rows[0])


def _live_session_event_row(row: dict[str, Any]) -> dict[str, Any]:
    payload = row.get("payload") or {}
    if isinstance(payload, str):
        try:
            payload = json.loads(payload)
        except Exception:
            payload = {}
    return {
        "event_id": str(row.get("event_id") or ""),
        "session_id": str(row.get("session_id") or ""),
        "agent_id": str(row.get("agent_id") or ""),
        "space_id": str(row.get("space_id") or "") if row.get("space_id") else None,
        "person_id": str(row.get("person_id") or "") if row.get("person_id") else None,
        "type": str(row.get("type") or ""),
        "payload": payload,
        "created_at": str(row.get("created_at") or ""),
    }


class GuiMemoryCandidateCreate(BaseModel):
    agent_id: str
    space_id: str
    content: str = Field(..., min_length=1, max_length=10000)
    tier: str = "semantic"
    session_id: str | None = None
    subject_person_id: str | None = None
    tags: list[str] = []
    scene_context: str | None = None
    modality: str = "text"
    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
    participants: list[str] = []
    related_memory_ids: list[str] = []


class MemoryCandidatePatch(BaseModel):
    content: str | None = Field(default=None, min_length=1, max_length=10000)
    tier: str | None = None
    subject_person_id: str | None = None
    participants: list[str] | None = None
    confidence: float | None = Field(default=None, ge=0.0, le=1.0)


class MemoryCandidateCommit(BaseModel):
    tags: list[str] = []
    scene_context: str | None = None
    modality: str = "text"
    related_memory_ids: list[str] = []


class MemoryCandidateReject(BaseModel):
    reason: str | None = None


class MemorySupersedeIn(BaseModel):
    superseded_by_memory_id: str | None = None
    reason: str | None = None


@app.post("/api/actions", name="api_create_action")
def api_create_action(request: Request, body: ActionCreate) -> dict:
    """Create a new action manually."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Check user has admin permission on the agent
    if not check_agent_permission(db, user_id=user.user_id, agent_id=body.agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")

    # If space_id provided, verify it belongs to the agent
    if body.space_id:
        space_rows = db.query(
            """
            SELECT space_id FROM spaces WHERE space_id = :space_id::uuid AND agent_id = :agent_id::uuid
        """,
            {"space_id": body.space_id, "agent_id": body.agent_id},
        )
        if not space_rows:
            raise HTTPException(status_code=400, detail="Space not found or does not belong to agent")

    try:
        created = create_action(
            db,
            agent_id=body.agent_id,
            space_id=body.space_id,
            kind=body.kind,
            payload=body.payload,
            required_scopes=[str(s) for s in (body.required_scopes or [])],
            requested_approval_mode="manual_immediate" if body.auto_approve else "policy_only",
            approved_by_user_id=str(user.user_id) if body.auto_approve else None,
            idempotency_key=body.idempotency_key,
            request_actor_type="user",
            request_actor_id=str(user.user_id),
            request_origin="gui:api_create_action",
            policy_mode=str(os.getenv("AUTO_APPROVE_POLICY_MODE", "enforce")).strip().lower(),
            audit_bucket=_cfg.audit_bucket,
            sqs_client=_get_sqs(),
            action_queue_url=_cfg.action_queue_url,
        )
    except ActionServiceError as exc:
        if exc.code in {"unknown_action_kind", "invalid_payload", "missing_action_kind"}:
            raise HTTPException(status_code=400, detail=str(exc)) from exc
        logger.error("Failed to create action: %s", exc)
        raise HTTPException(status_code=500, detail="Failed to create action") from exc

    return {
        "message": "Action created",
        "action_id": created["action_id"],
        "status": created["status"],
        "auto_approved": created["status"] == "approved",
        "approval_source": created.get("approval_source"),
    }


@app.get("/api/events/{event_id}", name="api_get_event")
def api_get_event(request: Request, event_id: str) -> dict:
    """Get event details."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    rows = db.query(
        """
        SELECT e.event_id::TEXT as event_id, e.agent_id::TEXT as agent_id,
               e.space_id::TEXT as space_id, e.device_id::TEXT as device_id,
               e.person_id::TEXT as person_id, e.type, e.payload::TEXT as payload,
               e.created_at::TEXT as created_at,
               a.name as agent_name, s.name as space_name,
               d.name as device_name, p.display_name as person_name
        FROM events e
        INNER JOIN agents a ON e.agent_id = a.agent_id
        LEFT JOIN spaces s ON e.space_id = s.space_id
        LEFT JOIN devices d ON e.device_id = d.device_id
        LEFT JOIN people p ON e.person_id = p.person_id
        INNER JOIN agent_memberships mb ON e.agent_id = mb.agent_id
        WHERE e.event_id = :event_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN ('member', 'admin', 'owner')
          AND mb.revoked_at IS NULL
    """,
        {"event_id": event_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Event not found or permission denied")

    row = rows[0]

    # Parse JSON payload
    try:
        payload = json.loads(row.get("payload") or "{}")
    except Exception:
        payload = {}

    return {
        "event_id": row["event_id"],
        "agent_id": row["agent_id"],
        "agent_name": row.get("agent_name", ""),
        "space_id": row.get("space_id"),
        "space_name": row.get("space_name"),
        "device_id": row.get("device_id"),
        "device_name": row.get("device_name"),
        "person_id": row.get("person_id"),
        "person_name": row.get("person_name"),
        "type": row["type"],
        "payload": payload,
        "created_at": row["created_at"],
    }


@app.get("/events", name="gui_events")
def gui_events(request: Request) -> Response:
    """Event stream viewer."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/events")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)
    spaces = list_spaces_for_user(db, user_id=user.user_id)

    # Get events for all agents the user has access to
    agent_ids = [a.agent_id for a in agents]
    events_data = []
    event_types_set: set = set()

    if agent_ids:
        import json

        placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
        params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
        rows = db.query(
            f"""SELECT e.event_id::TEXT as event_id, e.agent_id::TEXT as agent_id,
                       e.space_id::TEXT as space_id, e.device_id::TEXT as device_id,
                       e.person_id::TEXT as person_id, e.type, e.payload, e.created_at,
                       a.name as agent_name, s.name as space_name, p.display_name as person_name
                FROM events e
                JOIN agents a ON a.agent_id = e.agent_id
                LEFT JOIN spaces s ON s.space_id = e.space_id
                LEFT JOIN people p ON p.person_id = e.person_id
                WHERE e.agent_id::TEXT IN ({placeholders})
                ORDER BY e.created_at DESC
                LIMIT 200""",
            params,
        )

        for row in rows:
            event_type = row.get("type", "")
            event_types_set.add(event_type)

            # Categorize event type for badge styling
            type_lower = event_type.lower()
            if "audio" in type_lower or "sound" in type_lower:
                type_category = "audio"
            elif "video" in type_lower or "image" in type_lower:
                type_category = "video"
            elif "speech" in type_lower or "transcript" in type_lower or "voice" in type_lower:
                type_category = "speech"
            elif "action" in type_lower or "tool" in type_lower or "execute" in type_lower:
                type_category = "action"
            elif "system" in type_lower or "error" in type_lower or "connect" in type_lower:
                type_category = "system"
            else:
                type_category = "other"

            created_at = row.get("created_at")
            created_at_str = ""
            if created_at:
                try:
                    if hasattr(created_at, "strftime"):
                        created_at_str = created_at.strftime("%H:%M:%S")
                except Exception:
                    pass

            payload = row.get("payload") or {}
            if isinstance(payload, str):
                try:
                    payload = json.loads(payload)
                except Exception:
                    payload = {}
            payload_str = json.dumps(payload) if payload else "{}"
            payload_preview = payload_str[:100] + ("..." if len(payload_str) > 100 else "")

            events_data.append(
                {
                    "event_id": str(row.get("event_id", "")),
                    "agent_id": str(row.get("agent_id", "")),
                    "agent_name": row.get("agent_name", ""),
                    "space_id": str(row.get("space_id", "")) if row.get("space_id") else None,
                    "space_name": row.get("space_name"),
                    "person_id": str(row.get("person_id", "")) if row.get("person_id") else None,
                    "person_name": row.get("person_name"),
                    "type": event_type,
                    "type_category": type_category,
                    "payload_str": payload_str,
                    "payload_preview": payload_preview,
                    "created_at_str": created_at_str,
                }
            )

    agents_data = [{"agent_id": a.agent_id, "name": a.name, "role": a.role} for a in agents]
    spaces_data = [{"space_id": s.space_id, "name": s.name} for s in spaces]

    return templates.TemplateResponse(
        request,
        "events.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "events",
            "events": events_data,
            "event_types": sorted(event_types_set),
            "agents": agents_data,
            "spaces": spaces_data,
            **_get_ws_context(request),
        },
    )


@app.get("/memories", name="gui_memories")
def gui_memories(request: Request) -> Response:
    """Memories browser."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/memories")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)
    spaces = list_spaces_for_user(db, user_id=user.user_id)

    # Get memories for all agents the user has access to
    agent_ids = [a.agent_id for a in agents]
    memories_data = []
    tier_counts = {item["value"]: 0 for item in memory_kind_options()}

    if agent_ids:
        import json
        from datetime import datetime, timezone

        placeholders = ", ".join(f":id{i}" for i in range(len(agent_ids)))
        params = {f"id{i}": aid for i, aid in enumerate(agent_ids)}
        rows = db.query(
            f"""SELECT m.memory_id::TEXT as memory_id, m.agent_id::TEXT as agent_id,
                       m.space_id::TEXT as space_id, m.tier, m.content,
                       m.participants, m.provenance, m.created_at,
                       a.name as agent_name, s.name as space_name,
                       m.subject_person_id::TEXT as subject_person_id,
                       p.display_name as subject_person_name,
                       m.tags, m.scene_context, m.modality, m.confidence,
                       m.related_memory_ids::TEXT[] as related_memory_ids
                FROM memories m
                JOIN agents a ON a.agent_id = m.agent_id
                LEFT JOIN spaces s ON s.space_id = m.space_id
                LEFT JOIN people p ON p.person_id = m.subject_person_id
                WHERE m.agent_id::TEXT IN ({placeholders})
                ORDER BY m.created_at DESC
                LIMIT 100""",
            params,
        )

        for row in rows:
            tier = str(row.get("tier", "") or "").lower()
            if tier in tier_counts:
                tier_counts[tier] += 1

            created_at = row.get("created_at")
            created_at_relative = None
            if created_at:
                try:
                    if hasattr(created_at, "tzinfo"):
                        now = datetime.now(timezone.utc)
                        delta = now - created_at
                        if delta.days > 0:
                            created_at_relative = f"{delta.days}d ago"
                        elif delta.seconds >= 3600:
                            created_at_relative = f"{delta.seconds // 3600}h ago"
                        else:
                            created_at_relative = f"{delta.seconds // 60}m ago"
                except Exception:
                    pass

            participants = row.get("participants") or []
            if isinstance(participants, str):
                try:
                    participants = json.loads(participants)
                except Exception:
                    participants = []

            provenance = row.get("provenance") or {}
            if isinstance(provenance, str):
                try:
                    provenance = json.loads(provenance)
                except Exception:
                    provenance = {}

            # Parse tags (may come as list or None)
            tags = row.get("tags") or []

            memories_data.append(
                {
                    "memory_id": str(row.get("memory_id", "")),
                    "agent_id": str(row.get("agent_id", "")),
                    "agent_name": row.get("agent_name", ""),
                    "space_id": str(row.get("space_id", "")) if row.get("space_id") else None,
                    "space_name": row.get("space_name"),
                    "tier": tier,
                    "content": row.get("content", ""),
                    "participants": participants,
                    "provenance_source": provenance.get("source", ""),
                    "created_at_relative": created_at_relative,
                    "subject_person_id": row.get("subject_person_id"),
                    "subject_person_name": row.get("subject_person_name"),
                    "tags": tags,
                    "scene_context": row.get("scene_context"),
                    "modality": row.get("modality", "text"),
                    "confidence": row.get("confidence", 1.0),
                    "related_memory_ids": row.get("related_memory_ids") or [],
                }
            )

    agents_data = [{"agent_id": a.agent_id, "name": a.name, "role": a.role} for a in agents]
    spaces_data = [{"space_id": s.space_id, "name": s.name} for s in spaces]

    # Collect people for all user's agents (for filters and creation form)
    people_data: list[dict[str, str]] = []
    if agent_ids:
        people_placeholders = ", ".join(f":pid{i}" for i in range(len(agent_ids)))
        people_params = {f"pid{i}": aid for i, aid in enumerate(agent_ids)}
        people_rows = db.query(
            f"""SELECT person_id::TEXT as person_id, display_name
                FROM people WHERE agent_id::TEXT IN ({people_placeholders})
                ORDER BY display_name""",
            people_params,
        )
        people_data = [{"person_id": r["person_id"], "display_name": r["display_name"]} for r in people_rows]

    # Collect unique modalities and tags for filters
    all_modalities = sorted({m.get("modality", "text") for m in memories_data})
    all_tags = sorted({t for m in memories_data for t in m.get("tags", [])})

    return templates.TemplateResponse(
        request,
        "memories.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "memories",
            "memories": memories_data,
            "tier_counts": tier_counts,
            "memory_kinds": memory_kind_options(),
            "agents": agents_data,
            "spaces": spaces_data,
            "people": people_data,
            "all_modalities": all_modalities,
            "all_tags": all_tags,
            **_get_ws_context(request),
        },
    )


def _gui_agent_ids(user: AuthenticatedUser) -> tuple[list[Any], list[str], list[dict[str, Any]]]:
    agents = list_agents_for_user(_get_db(), user_id=user.user_id)
    ids = [a.agent_id for a in agents]
    id_strings = [str(a.agent_id) for a in agents]
    data = [{"agent_id": str(a.agent_id), "name": a.name, "role": a.role} for a in agents]
    return ids, id_strings, data


def _query_for_agent_ids(
    sql: str, agent_ids: list[str], *, extra: dict[str, Any] | None = None
) -> list[dict[str, Any]]:
    if not agent_ids:
        return []
    placeholders = ", ".join(f":agent_id_{i}" for i in range(len(agent_ids)))
    params: dict[str, Any] = {f"agent_id_{i}": agent_id for i, agent_id in enumerate(agent_ids)}
    if extra:
        params.update(extra)
    return _get_db().query(sql.replace("__AGENT_IDS__", placeholders), params)


def _json_or_empty(value: Any) -> Any:
    if value is None:
        return {}
    if isinstance(value, (dict, list)):
        return value
    try:
        return json.loads(str(value))
    except Exception:
        return {}


def _gui_error_text(exc: Exception) -> str:
    return f"{type(exc).__name__}: {exc}"


@app.get("/capabilities", name="gui_capabilities")
def gui_capabilities(request: Request) -> Response:
    """Capability exposure matrix for developed Marvain surfaces."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/capabilities")

    matrix = _capability_matrix()
    return templates.TemplateResponse(
        request,
        "capabilities.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "capabilities",
            "capabilities": matrix,
            "missing_count": sum(1 for item in matrix if item["exposure"] == "missing"),
            **_get_ws_context(request),
        },
    )


@app.get("/api/capabilities", name="api_capabilities")
def api_capabilities(request: Request) -> JSONResponse:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    return JSONResponse({"capabilities": _capability_matrix()})


def _capability_matrix() -> list[dict[str, str]]:
    from agent_hub.tools.registry import get_registry

    tool_names = ", ".join(sorted(t.name for t in get_registry().list_tools()))
    return [
        {
            "capability": "Authenticated dashboard and account/session",
            "backend": "Cognito Hosted UI, normalized browser principal, WS session token",
            "gui": "Dashboard, Profile, global WebSocket connection",
            "cli": "marvain gui, marvain cognito",
            "exposure": "gui",
        },
        {
            "capability": "Agent/member/person account management",
            "backend": "agents, users, agent_memberships, person_accounts",
            "gui": "Agents, Agent Detail, People, Personas",
            "cli": "marvain members",
            "exposure": "gui",
        },
        {
            "capability": "Persona and prompt hydration",
            "backend": "personas, sessions.persona_id, agent worker persona endpoint",
            "gui": "Personas, Sessions, Live Session",
            "cli": "marvain bootstrap seeds default persona",
            "exposure": "gui",
        },
        {
            "capability": "Location and space topology",
            "backend": "locations, spaces.location_id, devices.location_id/current_space_id",
            "gui": "Locations, Spaces, Devices",
            "cli": "marvain devices",
            "exposure": "gui",
        },
        {
            "capability": "Live media session",
            "backend": "LiveKit token minting, sessions, agent worker",
            "gui": "Live Session",
            "cli": "marvain agent, marvain smoke",
            "exposure": "gui",
        },
        {
            "capability": "Memory lifecycle and recall provenance",
            "backend": "events, memory_candidates, memories, memory_tombstones, recall_explanation",
            "gui": "Memories, Events, TapDB Lineage",
            "cli": "marvain smoke",
            "exposure": "gui",
        },
        {
            "capability": "Recognition, consent, unknown observations, presence",
            "backend": "recognition_observations, recognition_hypotheses, presence_assertions, consent_grants",
            "gui": "Recognition, People",
            "cli": "marvain smoke",
            "exposure": "gui",
        },
        {
            "capability": "Action proposal/approval/dispatch/result",
            "backend": "actions, action_policy_decisions, SQS tool runner, device callbacks",
            "gui": "Actions, Observability, TapDB Lineage",
            "cli": "marvain smoke",
            "exposure": "gui",
        },
        {
            "capability": "TapDB semantic graph and lineage",
            "backend": "daylily-tapdb boundary, template pack, semantic_sync_status",
            "gui": "TapDB Lineage",
            "cli": "marvain init tapdb",
            "exposure": "gui",
        },
        {
            "capability": "Tool registry",
            "backend": f"Registered tools: {tool_names}",
            "gui": "Tools, Actions",
            "cli": "marvain smoke",
            "exposure": "gui",
        },
        {
            "capability": "Audit and observability",
            "backend": "S3 audit chain, metrics, queues, worker/device heartbeat state",
            "gui": "Audit, Observability",
            "cli": "marvain status, marvain monitor",
            "exposure": "gui",
        },
    ]


@app.get("/personas", name="gui_personas")
def gui_personas(request: Request) -> Response:
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/personas")

    _agent_objs, agent_ids, agents_data = _gui_agent_ids(user)
    personas: list[dict[str, Any]] = []
    error: str | None = None
    try:
        personas = _query_for_agent_ids(
            """
            SELECT p.persona_id::TEXT AS persona_id, p.agent_id::TEXT AS agent_id,
                   p.name, p.instructions, p.is_default, p.lifecycle_state,
                   p.tapdb_euid, p.created_at::TEXT AS created_at, p.updated_at::TEXT AS updated_at,
                   a.name AS agent_name, COUNT(se.session_id) AS session_count
            FROM personas p
            JOIN agents a ON a.agent_id = p.agent_id
            LEFT JOIN sessions se ON se.persona_id = p.persona_id
            WHERE p.agent_id::TEXT IN (__AGENT_IDS__)
              AND p.disabled_at IS NULL
              AND p.lifecycle_state <> 'deleted'
            GROUP BY p.persona_id, p.agent_id, p.name, p.instructions, p.is_default,
                     p.lifecycle_state, p.tapdb_euid, p.created_at, p.updated_at, a.name
            ORDER BY a.name, p.is_default DESC, p.name
            """,
            agent_ids,
        )
    except Exception as exc:
        error = _gui_error_text(exc)

    return templates.TemplateResponse(
        request,
        "personas.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "personas",
            "agents": agents_data,
            "personas": personas,
            "error": error,
            **_get_ws_context(request),
        },
    )


@app.post("/api/personas", name="api_create_persona")
def api_create_persona(request: Request, body: PersonaCreate) -> dict[str, Any]:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    name = body.name.strip()
    instructions = body.instructions.strip()
    if not name:
        raise HTTPException(status_code=400, detail="name is required")
    if not instructions:
        raise HTTPException(status_code=400, detail="instructions are required")

    db = _get_db()
    if not check_agent_permission(db, user_id=user.user_id, agent_id=body.agent_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Requires admin permission on the agent")

    persona_id = str(uuid.uuid4())
    try:
        if body.is_default:
            db.execute(
                """
                UPDATE personas
                SET is_default = false, updated_at = now()
                WHERE agent_id = :agent_id::uuid
                  AND is_default
                  AND disabled_at IS NULL
                """,
                {"agent_id": body.agent_id},
            )
        db.execute(
            """
            INSERT INTO personas(persona_id, agent_id, name, instructions, is_default, lifecycle_state)
            VALUES (:persona_id::uuid, :agent_id::uuid, :name, :instructions, :is_default, 'active')
            """,
            {
                "persona_id": persona_id,
                "agent_id": body.agent_id,
                "name": name,
                "instructions": instructions,
                "is_default": bool(body.is_default),
            },
        )
    except Exception as exc:
        logger.error("Failed to create persona: %s", exc)
        raise HTTPException(status_code=500, detail="Failed to create persona") from exc

    return {"persona_id": persona_id, "agent_id": body.agent_id, "created": True, "is_default": bool(body.is_default)}


@app.post("/api/personas/{persona_id}/make-default", name="api_make_persona_default")
def api_make_persona_default(request: Request, persona_id: str) -> dict[str, Any]:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    db = _get_db()
    rows = db.query(
        """
        SELECT p.persona_id::TEXT AS persona_id, p.agent_id::TEXT AS agent_id
        FROM personas p
        JOIN agent_memberships mb ON mb.agent_id = p.agent_id
        WHERE p.persona_id = :persona_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN ('admin', 'owner')
          AND mb.revoked_at IS NULL
          AND p.disabled_at IS NULL
          AND p.lifecycle_state = 'active'
        LIMIT 1
        """,
        {"persona_id": persona_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Persona not found or permission denied")
    agent_id = rows[0]["agent_id"]
    try:
        db.execute(
            """
            UPDATE personas
            SET is_default = false, updated_at = now()
            WHERE agent_id = :agent_id::uuid
              AND is_default
              AND disabled_at IS NULL
            """,
            {"agent_id": agent_id},
        )
        db.execute(
            """
            UPDATE personas
            SET is_default = true, updated_at = now()
            WHERE persona_id = :persona_id::uuid
            """,
            {"persona_id": persona_id},
        )
    except Exception as exc:
        logger.error("Failed to set default persona %s: %s", persona_id, exc)
        raise HTTPException(status_code=500, detail="Failed to set default persona") from exc

    return {"persona_id": persona_id, "agent_id": agent_id, "is_default": True}


@app.get("/locations", name="gui_locations")
def gui_locations(request: Request) -> Response:
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/locations")

    _agent_objs, agent_ids, agents_data = _gui_agent_ids(user)
    locations: list[dict[str, Any]] = []
    error: str | None = None
    try:
        rows = _query_for_agent_ids(
            """
            SELECT l.location_id::TEXT AS location_id, l.agent_id::TEXT AS agent_id,
                   l.name, NULL::TEXT AS description, l.address_label AS address,
                   l.metadata::TEXT AS metadata, l.tapdb_euid,
                   a.name AS agent_name,
                   COUNT(DISTINCT s.space_id) AS space_count,
                   COUNT(DISTINCT d.device_id) AS device_count
            FROM locations l
            JOIN agents a ON a.agent_id = l.agent_id
            LEFT JOIN spaces s ON s.location_id = l.location_id
            LEFT JOIN devices d ON d.location_id = l.location_id AND d.revoked_at IS NULL
            WHERE l.agent_id::TEXT IN (__AGENT_IDS__)
            GROUP BY l.location_id, l.agent_id, l.name, l.address_label, l.metadata, l.tapdb_euid, a.name
            ORDER BY a.name, l.name
            """,
            agent_ids,
        )
        for row in rows:
            locations.append(
                {
                    "location_id": row.get("location_id"),
                    "agent_id": row.get("agent_id"),
                    "agent_name": row.get("agent_name"),
                    "name": row.get("name"),
                    "description": row.get("description"),
                    "address": row.get("address"),
                    "metadata": _json_or_empty(row.get("metadata")),
                    "tapdb_euid": row.get("tapdb_euid"),
                    "space_count": row.get("space_count") or 0,
                    "device_count": row.get("device_count") or 0,
                }
            )
    except Exception as exc:
        error = _gui_error_text(exc)

    return templates.TemplateResponse(
        request,
        "locations.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "locations",
            "agents": agents_data,
            "locations": locations,
            "error": error,
            **_get_ws_context(request),
        },
    )


@app.get("/sessions", name="gui_sessions")
def gui_sessions(request: Request) -> Response:
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/sessions")

    _agent_objs, agent_ids, agents_data = _gui_agent_ids(user)
    sessions: list[dict[str, Any]] = []
    error: str | None = None
    try:
        rows = _query_for_agent_ids(
            """
            SELECT se.session_id::TEXT AS session_id, se.agent_id::TEXT AS agent_id,
                   se.space_id::TEXT AS space_id, se.location_id::TEXT AS location_id,
                   se.persona_id::TEXT AS persona_id, se.livekit_room, se.status,
                   se.started_at::TEXT AS started_at, se.ended_at::TEXT AS ended_at,
                   se.metadata::TEXT AS metadata,
                   a.name AS agent_name, sp.name AS space_name, l.name AS location_name,
                   pe.name AS persona_name,
                   COUNT(DISTINCT e.event_id) AS event_count,
                   COUNT(DISTINCT m.memory_id) AS memory_count,
                   COUNT(DISTINCT ac.action_id) AS action_count
            FROM sessions se
            JOIN agents a ON a.agent_id = se.agent_id
            LEFT JOIN spaces sp ON sp.space_id = se.space_id
            LEFT JOIN locations l ON l.location_id = se.location_id
            LEFT JOIN personas pe ON pe.persona_id = se.persona_id
            LEFT JOIN events e ON e.session_id = se.session_id
            LEFT JOIN memories m ON m.session_id = se.session_id
            LEFT JOIN actions ac ON ac.session_id = se.session_id
            WHERE se.agent_id::TEXT IN (__AGENT_IDS__)
            GROUP BY se.session_id, se.agent_id, se.space_id, se.location_id, se.persona_id,
                     se.livekit_room, se.status, se.started_at, se.ended_at, se.metadata,
                     a.name, sp.name, l.name, pe.name
            ORDER BY se.started_at DESC
            LIMIT 200
            """,
            agent_ids,
        )
        sessions = [
            {
                "session_id": row.get("session_id"),
                "agent_id": row.get("agent_id"),
                "agent_name": row.get("agent_name"),
                "space_id": row.get("space_id"),
                "space_name": row.get("space_name"),
                "location_id": row.get("location_id"),
                "location_name": row.get("location_name"),
                "persona_id": row.get("persona_id"),
                "persona_name": row.get("persona_name"),
                "livekit_room": row.get("livekit_room"),
                "status": row.get("status"),
                "started_at": row.get("started_at"),
                "ended_at": row.get("ended_at"),
                "metadata": _json_or_empty(row.get("metadata")),
                "event_count": row.get("event_count") or 0,
                "memory_count": row.get("memory_count") or 0,
                "action_count": row.get("action_count") or 0,
            }
            for row in rows
        ]
    except Exception as exc:
        error = _gui_error_text(exc)

    return templates.TemplateResponse(
        request,
        "sessions.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "sessions",
            "agents": agents_data,
            "sessions": sessions,
            "error": error,
            **_get_ws_context(request),
        },
    )


@app.get("/recognition", name="gui_recognition")
def gui_recognition(request: Request) -> Response:
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/recognition")

    _agent_objs, agent_ids, agents_data = _gui_agent_ids(user)
    observations: list[dict[str, Any]] = []
    hypotheses: list[dict[str, Any]] = []
    unknown_observations: list[dict[str, Any]] = []
    no_match_hypotheses: list[dict[str, Any]] = []
    presence: list[dict[str, Any]] = []
    consent_grants: list[dict[str, Any]] = []
    artifact_references: list[dict[str, Any]] = []
    revocation_statuses: list[dict[str, Any]] = []
    readiness_statuses: list[dict[str, Any]] = []
    error: str | None = None
    try:
        observations = _query_for_agent_ids(
            """
            SELECT ro.recognition_observation_id::TEXT AS observation_id,
                   ro.agent_id::TEXT AS agent_id, ro.space_id::TEXT AS space_id,
                   ro.location_id::TEXT AS location_id, ro.device_id::TEXT AS device_id,
                   ro.session_id::TEXT AS session_id, ro.artifact_id::TEXT AS artifact_id,
                   ro.modality, ro.lifecycle_state, ro.model AS model_name, ro.created_at::TEXT AS created_at,
                   a.name AS agent_name, s.name AS space_name, l.name AS location_name, d.name AS device_name
            FROM recognition_observations ro
            JOIN agents a ON a.agent_id = ro.agent_id
            LEFT JOIN spaces s ON s.space_id = ro.space_id
            LEFT JOIN locations l ON l.location_id = ro.location_id
            LEFT JOIN devices d ON d.device_id = ro.device_id
            WHERE ro.agent_id::TEXT IN (__AGENT_IDS__)
            ORDER BY ro.created_at DESC
            LIMIT 100
            """,
            agent_ids,
        )
        hypotheses = _query_for_agent_ids(
            """
            SELECT rh.identity_hypothesis_id::TEXT AS hypothesis_id,
                   rh.recognition_observation_id::TEXT AS observation_id,
                   ro.agent_id::TEXT AS agent_id, rh.candidate_person_id::TEXT AS candidate_person_id,
                   p.display_name AS person_name, rh.confidence AS score, rh.decision, rh.consent_id::TEXT AS consent_id,
                   rh.created_at::TEXT AS created_at
            FROM recognition_hypotheses rh
            JOIN recognition_observations ro ON ro.recognition_observation_id = rh.recognition_observation_id
            LEFT JOIN people p ON p.person_id = rh.candidate_person_id
            WHERE ro.agent_id::TEXT IN (__AGENT_IDS__)
            ORDER BY rh.created_at DESC
            LIMIT 100
            """,
            agent_ids,
        )
        unknown_observations = _query_for_agent_ids(
            """
            SELECT ro.recognition_observation_id::TEXT AS observation_id,
                   ro.agent_id::TEXT AS agent_id, ro.modality, ro.lifecycle_state,
                   'No accepted person match' AS reason, ro.created_at::TEXT AS created_at
            FROM recognition_observations ro
            WHERE ro.agent_id::TEXT IN (__AGENT_IDS__)
              AND ro.lifecycle_state = 'no_match'
            ORDER BY ro.created_at DESC
            LIMIT 100
            """,
            agent_ids,
        )
        no_match_hypotheses = _query_for_agent_ids(
            """
            SELECT rh.identity_hypothesis_id::TEXT AS hypothesis_id,
                   rh.recognition_observation_id::TEXT AS observation_id,
                   ro.agent_id::TEXT AS agent_id, rh.decision, rh.confidence AS score, rh.reason
            FROM recognition_hypotheses rh
            JOIN recognition_observations ro ON ro.recognition_observation_id = rh.recognition_observation_id
            WHERE ro.agent_id::TEXT IN (__AGENT_IDS__)
              AND rh.decision = 'no_match'
            ORDER BY COALESCE(rh.decided_at, rh.created_at) DESC
            LIMIT 100
            """,
            agent_ids,
        )
        presence = _query_for_agent_ids(
            """
            SELECT pa.presence_assertion_id::TEXT AS presence_assertion_id,
                   pa.agent_id::TEXT AS agent_id, pa.person_id::TEXT AS person_id,
                   p.display_name AS person_name, pa.space_id::TEXT AS space_id,
                   s.name AS space_name, pa.location_id::TEXT AS location_id,
                   l.name AS location_name, pa.status, 'recognition' AS source, pa.asserted_at::TEXT AS asserted_at
            FROM presence_assertions pa
            LEFT JOIN people p ON p.person_id = pa.person_id
            LEFT JOIN spaces s ON s.space_id = pa.space_id
            LEFT JOIN locations l ON l.location_id = pa.location_id
            WHERE pa.agent_id::TEXT IN (__AGENT_IDS__)
            ORDER BY pa.asserted_at DESC
            LIMIT 100
            """,
            agent_ids,
        )
        consent_grants = _query_for_agent_ids(
            """
            SELECT cg.consent_id::TEXT AS consent_id, cg.agent_id::TEXT AS agent_id,
                   cg.person_id::TEXT AS person_id, p.display_name AS person_name,
                   cg.consent_type,
                   CASE
                     WHEN cg.revoked_at IS NOT NULL THEN 'revoked'
                     WHEN cg.expires_at IS NOT NULL AND cg.expires_at <= now() THEN 'expired'
                     ELSE 'active'
                   END AS status,
                   cg.expires_at::TEXT AS expires_at, cg.revoked_at::TEXT AS revoked_at
            FROM consent_grants cg
            JOIN people p ON p.person_id = cg.person_id
            WHERE cg.agent_id::TEXT IN (__AGENT_IDS__)
            ORDER BY cg.granted_at DESC
            LIMIT 100
            """,
            agent_ids,
        )
        artifact_references = _query_for_agent_ids(
            """
            SELECT ar.artifact_id::TEXT AS artifact_id, ar.agent_id::TEXT AS agent_id,
                   ro.recognition_observation_id::TEXT AS observation_id,
                   ar.media_type AS kind,
                   COALESCE(ar.uri, CASE WHEN ar.bucket IS NOT NULL AND ar.object_key IS NOT NULL
                                      THEN 's3://' || ar.bucket || '/' || ar.object_key
                                      ELSE NULL END) AS uri,
                   ar.lifecycle_state, ar.created_at::TEXT AS created_at
            FROM artifact_references ar
            LEFT JOIN recognition_observations ro ON ro.artifact_id = ar.artifact_id
            WHERE ar.agent_id::TEXT IN (__AGENT_IDS__)
              AND (ro.recognition_observation_id IS NOT NULL OR ar.media_type LIKE 'audio/%' OR ar.media_type LIKE 'image/%')
            ORDER BY ar.created_at DESC
            LIMIT 100
            """,
            agent_ids,
        )
        revocation_statuses = _query_for_agent_ids(
            """
            SELECT vp.agent_id::TEXT AS agent_id,
                   p.display_name || ' voice enrollment' AS subject,
                   CASE
                     WHEN vp.revoked_at IS NOT NULL THEN 'revoked'
                     WHEN NOT EXISTS (
                       SELECT 1 FROM consent_grants cg
                       WHERE cg.agent_id = vp.agent_id
                         AND cg.person_id = vp.person_id
                         AND cg.consent_type IN ('voice', 'global')
                         AND cg.revoked_at IS NULL
                         AND (cg.expires_at IS NULL OR cg.expires_at > now())
                     ) THEN 'stale'
                     ELSE 'not revoked'
                   END AS status,
                   COALESCE(vp.revoked_at::TEXT, vp.created_at::TEXT) AS updated_at,
                   vp.voiceprint_id::TEXT AS projection_id,
                   'voice' AS modality
            FROM voiceprints vp
            JOIN people p ON p.person_id = vp.person_id
            WHERE vp.agent_id::TEXT IN (__AGENT_IDS__)
            UNION ALL
            SELECT fp.agent_id::TEXT AS agent_id,
                   p.display_name || ' face enrollment' AS subject,
                   CASE
                     WHEN fp.revoked_at IS NOT NULL THEN 'revoked'
                     WHEN NOT EXISTS (
                       SELECT 1 FROM consent_grants cg
                       WHERE cg.agent_id = fp.agent_id
                         AND cg.person_id = fp.person_id
                         AND cg.consent_type IN ('face', 'global')
                         AND cg.revoked_at IS NULL
                         AND (cg.expires_at IS NULL OR cg.expires_at > now())
                     ) THEN 'stale'
                     ELSE 'not revoked'
                   END AS status,
                   COALESCE(fp.revoked_at::TEXT, fp.created_at::TEXT) AS updated_at,
                   fp.faceprint_id::TEXT AS projection_id,
                   'face' AS modality
            FROM faceprints fp
            JOIN people p ON p.person_id = fp.person_id
            WHERE fp.agent_id::TEXT IN (__AGENT_IDS__)
            ORDER BY updated_at DESC
            LIMIT 100
            """,
            agent_ids,
        )
        readiness_statuses = [
            {
                "name": "Consent-gated recognition controls",
                "agent_id": agent_ids[0] if agent_ids else "",
                "status": "ready",
                "detail": "Enrollment, hypothesis decisions, no-match, and projection revocation are available.",
            }
        ]
    except Exception as exc:
        error = _gui_error_text(exc)

    return templates.TemplateResponse(
        request,
        "recognition.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "recognition",
            "agents": agents_data,
            "observations": observations,
            "hypotheses": hypotheses,
            "unknown_observations": unknown_observations,
            "no_match_hypotheses": no_match_hypotheses,
            "presence": presence,
            "consent_grants": consent_grants,
            "artifact_references": artifact_references,
            "revocation_statuses": revocation_statuses,
            "readiness_statuses": readiness_statuses,
            "error": error,
            **_get_ws_context(request),
        },
    )


@app.get("/observability", name="gui_observability")
def gui_observability(request: Request) -> Response:
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/observability")

    _agent_objs, agent_ids, _agents_data = _gui_agent_ids(user)
    metrics: list[dict[str, Any]] = []
    error: str | None = None
    try:
        from marvain_cli.failure import failure_catalog

        failure_scenarios = failure_catalog()
    except Exception:
        failure_scenarios = []
    try:
        rows = _query_for_agent_ids(
            """
            SELECT
              (SELECT COUNT(*) FROM devices d WHERE d.agent_id::TEXT IN (__AGENT_IDS__) AND d.revoked_at IS NULL) AS devices_total,
              (SELECT COUNT(*) FROM devices d WHERE d.agent_id::TEXT IN (__AGENT_IDS__) AND d.revoked_at IS NULL AND d.last_heartbeat_at > now() - interval '60 seconds') AS devices_online,
              (SELECT COUNT(*) FROM actions a WHERE a.agent_id::TEXT IN (__AGENT_IDS__) AND a.status = 'proposed') AS actions_pending,
              (SELECT COUNT(*) FROM actions a WHERE a.agent_id::TEXT IN (__AGENT_IDS__) AND a.status IN ('awaiting_device_result','device_acknowledged')) AS actions_waiting,
              (SELECT COUNT(*) FROM memories m WHERE m.agent_id::TEXT IN (__AGENT_IDS__) AND COALESCE(m.lifecycle_state, 'committed') = 'committed') AS memories_committed,
              (SELECT COUNT(*) FROM recognition_observations ro WHERE ro.agent_id::TEXT IN (__AGENT_IDS__)) AS recognition_observations,
              (SELECT COUNT(*) FROM semantic_sync_status ss WHERE ss.agent_id::TEXT IN (__AGENT_IDS__) AND ss.status = 'failed') AS semantic_failures
            """,
            agent_ids,
        )
        row = rows[0] if rows else {}
        metrics = [
            {"name": "Devices total", "value": row.get("devices_total") or 0},
            {"name": "Devices online", "value": row.get("devices_online") or 0},
            {"name": "Pending actions", "value": row.get("actions_pending") or 0},
            {"name": "Actions awaiting device", "value": row.get("actions_waiting") or 0},
            {"name": "Committed memories", "value": row.get("memories_committed") or 0},
            {"name": "Recognition observations", "value": row.get("recognition_observations") or 0},
            {"name": "Semantic sync failures", "value": row.get("semantic_failures") or 0},
        ]
    except Exception as exc:
        error = _gui_error_text(exc)

    return templates.TemplateResponse(
        request,
        "observability.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "observability",
            "metrics": metrics,
            "worker": _agent_worker_status_dict(),
            "failure_scenarios": failure_scenarios,
            "error": error,
            **_get_ws_context(request),
        },
    )


@app.get("/api/observability/failure-scenarios", name="api_observability_failure_scenarios")
def api_observability_failure_scenarios(request: Request) -> JSONResponse:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    from marvain_cli.failure import failure_catalog

    return JSONResponse({"failure_scenarios": failure_catalog()})


@app.get("/live-session", name="gui_live_session")
def gui_live_session(request: Request, space_id: str | None = None) -> Response:
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/live-session")

    spaces = list_spaces_for_user(_get_db(), user_id=user.user_id)
    spaces_data = [
        {
            "space_id": sp.space_id,
            "agent_id": sp.agent_id,
            "name": sp.name,
            "agent_name": sp.agent_name,
            "livekit_room_mode": getattr(sp, "livekit_room_mode", "ephemeral"),
        }
        for sp in spaces
    ]
    return templates.TemplateResponse(
        request,
        "live_session.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "live_session",
            "spaces": spaces_data,
            "selected_space": str(space_id or "").strip(),
            "token_url": _gui_path(request, "/livekit/token"),
            "worker": _agent_worker_status_dict(),
            "config_error": _live_session_config_error(),
            **_get_ws_context(request),
        },
    )


@app.post("/api/live-session/{session_id}/chat", name="api_live_session_chat")
def api_live_session_chat(request: Request, session_id: str, body: LiveSessionChatIn) -> dict[str, Any]:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    _require_live_session_config()

    text = body.text.strip()
    if not text:
        raise HTTPException(status_code=400, detail="text is required")

    db = _get_db()
    session = _live_session_for_user(db, user=user, session_id=session_id)
    event_id = str(uuid.uuid4())
    payload = {
        "text": text,
        "author": {"type": "user", "user_id": str(user.user_id), "email": user.email},
        "source": "gui_live_session",
        "livekit_room": session.get("livekit_room"),
    }
    db.execute(
        """
        INSERT INTO events(event_id, agent_id, space_id, person_id, type, payload, session_id)
        VALUES (
            :event_id::uuid,
            :agent_id::uuid,
            :space_id::uuid,
            NULL,
            'chat.message',
            :payload::jsonb,
            :session_id::uuid
        )
        """,
        {
            "event_id": event_id,
            "agent_id": session["agent_id"],
            "space_id": session["space_id"],
            "payload": json.dumps(payload),
            "session_id": session["session_id"],
        },
    )
    memory_candidate_id = _create_live_session_memory_candidate(
        db,
        event_id=event_id,
        session=session,
        user=user,
        content=text,
    )
    try:
        broadcast_event(
            event_type="events.new",
            agent_id=session["agent_id"],
            space_id=session["space_id"],
            payload={
                "event": {
                    "event_id": event_id,
                    "agent_id": session["agent_id"],
                    "space_id": session["space_id"],
                    "session_id": session["session_id"],
                    "type": "chat.message",
                    "payload": payload,
                    "memory_candidate_id": memory_candidate_id,
                }
            },
        )
    except Exception as exc:
        logger.warning("Failed to broadcast live-session chat event %s: %s", event_id, exc)
    return {
        "event": {
            "event_id": event_id,
            "session_id": session["session_id"],
            "agent_id": session["agent_id"],
            "space_id": session["space_id"],
            "type": "chat.message",
            "payload": payload,
            "memory_candidate_id": memory_candidate_id,
        }
    }


@app.get("/api/live-session/{session_id}/events", name="api_live_session_events")
def api_live_session_events(request: Request, session_id: str) -> dict[str, Any]:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    db = _get_db()
    session = _live_session_for_user(db, user=user, session_id=session_id)
    rows = db.query(
        """
        SELECT event_id::TEXT AS event_id, session_id::TEXT AS session_id, agent_id::TEXT AS agent_id,
               space_id::TEXT AS space_id, person_id::TEXT AS person_id, type, payload::TEXT AS payload,
               created_at::TEXT AS created_at
        FROM events
        WHERE session_id = :session_id::uuid
        ORDER BY created_at ASC
        LIMIT 500
        """,
        {"session_id": session["session_id"]},
    )
    return {"session": session, "events": [_live_session_event_row(dict(row)) for row in rows]}


@app.post("/api/live-session/smoke", name="api_live_session_smoke")
def api_live_session_smoke(request: Request, body: LiveSessionSmokeIn) -> dict[str, Any]:
    """Run the deterministic local V1 loop for GUI Live Session smoke coverage."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    if _cfg.stage != "test" and os.getenv("MARVAIN_ENABLE_LIVE_SESSION_SMOKE") != "1":
        raise HTTPException(status_code=404, detail="Live session smoke is only available in explicit test mode")
    transcript_text = body.transcript_text.strip()
    if not transcript_text:
        raise HTTPException(status_code=400, detail="transcript_text is required")

    from marvain_cli.smoke import LocalSmokeScenario, run_local_smoke

    scenario = LocalSmokeScenario(
        seed=body.seed.strip() or "marvain-gui-live-session-smoke",
        agent_id=body.agent_id.strip() if body.agent_id else "agent-gui-smoke",
        space_id=body.space_id.strip() if body.space_id else "space-gui-smoke",
        device_id=body.device_id.strip() if body.device_id else "device-gui-satellite",
        person_id=str(user.user_id),
        transcript_text=transcript_text,
        recall_query=transcript_text,
        recognition_modality="voice",
        action_kind="device.notify",
    )
    return {
        "mode": "local_mocked_smoke",
        "report": run_local_smoke(scenario=scenario).as_dict(),
    }


@app.post("/api/memories", name="api_create_memory")
def api_create_memory(request: Request, body: GuiMemoryCandidateCreate) -> dict:
    """Create a memory candidate from GUI evidence."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    agent_id = body.agent_id
    if not agent_id:
        raise HTTPException(status_code=400, detail="agent_id required")

    content = body.content.strip()
    if not content:
        raise HTTPException(status_code=400, detail="content required")
    if not body.space_id:
        raise HTTPException(status_code=400, detail="space_id required for memory evidence")
    try:
        tier = normalize_memory_kind(body.tier, default="semantic")
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc

    # Verify user has access to this agent
    rows = db.query(
        """SELECT 1 FROM agent_memberships
           WHERE agent_id = :agent_id::uuid AND user_id = :user_id::uuid
             AND revoked_at IS NULL""",
        {"agent_id": agent_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Agent not found or no access")

    import uuid as _uuid

    event_id = str(_uuid.uuid4())
    candidate_id = str(_uuid.uuid4())
    metadata = {
        "source": "gui_memory_candidate_v1",
        "user_id": str(user.user_id),
        "content_preview": content[:500],
        "tags": body.tags,
        "scene_context": body.scene_context,
        "modality": body.modality,
        "related_memory_ids": body.related_memory_ids,
    }
    db.execute(
        """
        INSERT INTO events(event_id, agent_id, space_id, person_id, type, payload, session_id)
        VALUES (
            :event_id::uuid,
            :agent_id::uuid,
            :space_id::uuid,
            CASE WHEN :subject_person_id IS NULL THEN NULL ELSE :subject_person_id::uuid END,
            'memory.evidence',
            :payload::jsonb,
            CASE WHEN :session_id IS NULL THEN NULL ELSE :session_id::uuid END
        )
        """,
        {
            "event_id": event_id,
            "agent_id": agent_id,
            "space_id": body.space_id,
            "subject_person_id": body.subject_person_id,
            "payload": json.dumps(metadata),
            "session_id": body.session_id,
        },
    )
    db.execute(
        """
        INSERT INTO memory_candidates(memory_candidate_id, agent_id, source_event_id, space_id, session_id,
                                      subject_person_id, tier, content, participants, confidence, lifecycle_state)
        VALUES (
            :candidate_id::uuid,
            :agent_id::uuid,
            :event_id::uuid,
            :space_id::uuid,
            CASE WHEN :session_id IS NULL THEN NULL ELSE :session_id::uuid END,
            CASE WHEN :subject_person_id IS NULL THEN NULL ELSE :subject_person_id::uuid END,
            :tier,
            :content,
            :participants::jsonb,
            :confidence,
            'candidate'
        )
        """,
        {
            "candidate_id": candidate_id,
            "agent_id": agent_id,
            "event_id": event_id,
            "space_id": body.space_id,
            "session_id": body.session_id,
            "subject_person_id": body.subject_person_id,
            "tier": tier,
            "content": content,
            "participants": json.dumps(body.participants),
            "confidence": body.confidence,
        },
    )

    return {
        "memory_candidate_id": candidate_id,
        "source_event_id": event_id,
        "created": True,
        "status": "candidate",
    }


def _candidate_row_for_user(
    db: Any, *, candidate_id: str, user_id: str, require_admin: bool = False
) -> dict[str, Any] | None:
    roles = "('admin', 'owner')" if require_admin else "('member', 'admin', 'owner')"
    rows = db.query(
        f"""
        SELECT mc.memory_candidate_id::TEXT as memory_candidate_id,
               mc.agent_id::TEXT as agent_id,
               mc.source_event_id::TEXT as source_event_id,
               mc.source_action_id::TEXT as source_action_id,
               mc.space_id::TEXT as space_id,
               mc.session_id::TEXT as session_id,
               mc.subject_person_id::TEXT as subject_person_id,
               p.display_name as subject_person_name,
               mc.tier, mc.content, mc.participants::TEXT as participants,
               mc.model, mc.confidence, mc.lifecycle_state,
               mc.tapdb_euid, mc.created_at::TEXT as created_at,
               mc.reviewed_at::TEXT as reviewed_at,
               a.name as agent_name, s.name as space_name
        FROM memory_candidates mc
        JOIN agents a ON a.agent_id = mc.agent_id
        LEFT JOIN spaces s ON s.space_id = mc.space_id
        LEFT JOIN people p ON p.person_id = mc.subject_person_id
        JOIN agent_memberships mb ON mb.agent_id = mc.agent_id
        WHERE mc.memory_candidate_id = :candidate_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN {roles}
          AND mb.revoked_at IS NULL
        """,
        {"candidate_id": candidate_id, "user_id": user_id},
    )
    return rows[0] if rows else None


def _normalize_candidate_row(row: dict[str, Any]) -> dict[str, Any]:
    try:
        participants = json.loads(row.get("participants") or "[]")
    except Exception:
        participants = []
    return {
        "memory_candidate_id": row.get("memory_candidate_id"),
        "agent_id": row.get("agent_id"),
        "agent_name": row.get("agent_name"),
        "source_event_id": row.get("source_event_id"),
        "source_action_id": row.get("source_action_id"),
        "space_id": row.get("space_id"),
        "space_name": row.get("space_name"),
        "session_id": row.get("session_id"),
        "subject_person_id": row.get("subject_person_id"),
        "subject_person_name": row.get("subject_person_name"),
        "tier": row.get("tier"),
        "content": row.get("content"),
        "participants": participants,
        "model": row.get("model"),
        "confidence": row.get("confidence"),
        "lifecycle_state": row.get("lifecycle_state"),
        "tapdb_euid": row.get("tapdb_euid"),
        "created_at": row.get("created_at"),
        "reviewed_at": row.get("reviewed_at"),
    }


def _create_live_session_memory_candidate(
    db: Any,
    *,
    event_id: str,
    session: dict[str, Any],
    user: AuthenticatedUser,
    content: str,
) -> str:
    candidate_ids: list[str] = []
    for tier in classify_memory_kinds(content):
        candidate_id = str(uuid.uuid4())
        db.execute(
            """
            INSERT INTO memory_candidates(memory_candidate_id, agent_id, source_event_id, space_id, session_id,
                                          tier, content, participants, confidence, lifecycle_state)
            VALUES (
                :candidate_id::uuid,
                :agent_id::uuid,
                :event_id::uuid,
                :space_id::uuid,
                :session_id::uuid,
                :tier,
                :content,
                :participants::jsonb,
                1.0,
                'candidate'
            )
            """,
            {
                "candidate_id": candidate_id,
                "agent_id": session["agent_id"],
                "event_id": event_id,
                "space_id": session["space_id"],
                "session_id": session["session_id"],
                "tier": tier,
                "content": content,
                "participants": json.dumps([f"user:{user.user_id}"]),
            },
        )
        candidate_ids.append(candidate_id)
    return candidate_ids[0]


@app.get("/api/memory-candidates", name="api_list_memory_candidates")
def api_list_memory_candidates(request: Request, state: str | None = None, agent_id: str | None = None) -> dict:
    """List memory candidates visible to the current user."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    state_filter = (state or "candidate").strip()
    params: dict[str, Any] = {"user_id": str(user.user_id), "state": state_filter}
    agent_filter_sql = ""
    if agent_id:
        params["agent_id"] = agent_id
        agent_filter_sql = "AND mc.agent_id = :agent_id::uuid"
    try:
        rows = _get_db().query(
            f"""
            SELECT mc.memory_candidate_id::TEXT as memory_candidate_id,
                   mc.agent_id::TEXT as agent_id,
                   mc.source_event_id::TEXT as source_event_id,
                   mc.source_action_id::TEXT as source_action_id,
                   mc.space_id::TEXT as space_id,
                   mc.session_id::TEXT as session_id,
                   mc.subject_person_id::TEXT as subject_person_id,
                   p.display_name as subject_person_name,
                   mc.tier, mc.content, mc.participants::TEXT as participants,
                   mc.model, mc.confidence, mc.lifecycle_state,
                   mc.tapdb_euid, mc.created_at::TEXT as created_at,
                   mc.reviewed_at::TEXT as reviewed_at,
                   a.name as agent_name, s.name as space_name
            FROM memory_candidates mc
            JOIN agents a ON a.agent_id = mc.agent_id
            LEFT JOIN spaces s ON s.space_id = mc.space_id
            LEFT JOIN people p ON p.person_id = mc.subject_person_id
            JOIN agent_memberships mb ON mb.agent_id = mc.agent_id
            WHERE mb.user_id = :user_id::uuid
              AND mb.role IN ('member', 'admin', 'owner')
              AND mb.revoked_at IS NULL
              AND (:state = '' OR mc.lifecycle_state = :state)
              {agent_filter_sql}
            ORDER BY mc.created_at DESC
            LIMIT 100
            """,
            params,
        )
    except Exception as exc:
        logger.error("Failed to list memory candidates: %s", exc)
        raise HTTPException(status_code=500, detail="Failed to list memory candidates") from exc
    return {"candidates": [_normalize_candidate_row(row) for row in rows]}


@app.get("/api/memory-candidates/{candidate_id}", name="api_get_memory_candidate")
def api_get_memory_candidate(request: Request, candidate_id: str) -> dict:
    """Get a memory candidate detail record."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    row = _candidate_row_for_user(_get_db(), candidate_id=candidate_id, user_id=str(user.user_id))
    if not row:
        raise HTTPException(status_code=404, detail="Memory candidate not found or permission denied")
    return _normalize_candidate_row(row)


@app.patch("/api/memory-candidates/{candidate_id}", name="api_patch_memory_candidate")
def api_patch_memory_candidate(request: Request, candidate_id: str, body: MemoryCandidatePatch) -> dict:
    """Edit a reviewable memory candidate."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    db = _get_db()
    row = _candidate_row_for_user(db, candidate_id=candidate_id, user_id=str(user.user_id), require_admin=True)
    if not row:
        raise HTTPException(status_code=404, detail="Memory candidate not found or permission denied")
    if row.get("lifecycle_state") not in ("candidate", "scored"):
        raise HTTPException(status_code=409, detail="Only candidate or scored memory candidates can be edited")

    updates: list[str] = []
    params: dict[str, Any] = {"candidate_id": candidate_id}
    if body.content is not None:
        if not body.content.strip():
            raise HTTPException(status_code=400, detail="content required")
        updates.append("content = :content")
        params["content"] = body.content.strip()
    if body.tier is not None:
        try:
            normalize_memory_kind(body.tier)
        except ValueError as exc:
            raise HTTPException(status_code=400, detail=str(exc)) from exc
        updates.append("tier = :tier")
        params["tier"] = body.tier
    if body.subject_person_id is not None:
        updates.append(
            "subject_person_id = CASE WHEN :subject_person_id = '' THEN NULL ELSE :subject_person_id::uuid END"
        )
        params["subject_person_id"] = body.subject_person_id
    if body.participants is not None:
        updates.append("participants = :participants::jsonb")
        params["participants"] = json.dumps(body.participants)
    if body.confidence is not None:
        updates.append("confidence = :confidence")
        params["confidence"] = body.confidence

    if not updates:
        return {"memory_candidate_id": candidate_id, "updated": False}

    db.execute(
        f"""
        UPDATE memory_candidates
        SET {", ".join(updates)}
        WHERE memory_candidate_id = :candidate_id::uuid
        """,
        params,
    )
    return {"memory_candidate_id": candidate_id, "updated": True}


@app.post("/api/memory-candidates/{candidate_id}/reject", name="api_reject_memory_candidate")
def api_reject_memory_candidate(request: Request, candidate_id: str, body: MemoryCandidateReject | None = None) -> dict:
    """Reject a memory candidate."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    db = _get_db()
    row = _candidate_row_for_user(db, candidate_id=candidate_id, user_id=str(user.user_id), require_admin=True)
    if not row:
        raise HTTPException(status_code=404, detail="Memory candidate not found or permission denied")
    if row.get("lifecycle_state") == "committed":
        raise HTTPException(status_code=409, detail="Committed memory candidates cannot be rejected")
    db.execute(
        """
        UPDATE memory_candidates
        SET lifecycle_state = 'rejected',
            reviewed_at = now()
        WHERE memory_candidate_id = :candidate_id::uuid
        """,
        {"candidate_id": candidate_id},
    )
    return {"memory_candidate_id": candidate_id, "status": "rejected", "reason": body.reason if body else None}


@app.post("/api/memory-candidates/{candidate_id}/commit", name="api_commit_memory_candidate")
def api_commit_memory_candidate(request: Request, candidate_id: str, body: MemoryCandidateCommit | None = None) -> dict:
    """Commit an evidence-backed memory candidate into the memories projection."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    db = _get_db()
    row = _candidate_row_for_user(db, candidate_id=candidate_id, user_id=str(user.user_id), require_admin=True)
    if not row:
        raise HTTPException(status_code=404, detail="Memory candidate not found or permission denied")
    if row.get("lifecycle_state") not in ("candidate", "scored"):
        raise HTTPException(status_code=409, detail="Only candidate or scored memory candidates can be committed")
    if not row.get("source_event_id"):
        raise HTTPException(status_code=400, detail="Memory commit requires source evidence")

    import uuid as _uuid

    commit_body = body or MemoryCandidateCommit()
    memory_id = str(_uuid.uuid4())
    recall_explanation = {
        "source": "gui_candidate_commit",
        "user_id": str(user.user_id),
        "source_event_id": row.get("source_event_id"),
        "source_action_id": row.get("source_action_id"),
        "memory_candidate_id": candidate_id,
        "commit_policy": "manual_candidate_review_v1",
        "ranking_features": {
            "source_excerpt": str(row.get("content") or "")[:240],
            "keyword_match": [],
            "embedding_distance": None,
            "source_event_id": row.get("source_event_id"),
            "device_id": None,
            "space_id": row.get("space_id"),
            "session_id": row.get("session_id"),
            "person_id": row.get("subject_person_id"),
            "consent_filters": {"applied": True, "reason": "manual_candidate_review_v1"},
        },
    }
    db.execute(
        """
        INSERT INTO memories (memory_id, agent_id, space_id, tier, content, participants, provenance,
                              subject_person_id, tags, scene_context, modality, confidence, related_memory_ids,
                              memory_candidate_id, source_event_id, source_action_id, session_id,
                              lifecycle_state, recall_explanation)
        VALUES (
            :memory_id::uuid,
            :agent_id::uuid,
            CASE WHEN :space_id IS NULL THEN NULL ELSE :space_id::uuid END,
            :tier,
            :content,
            :participants::jsonb,
            :provenance::jsonb,
            CASE WHEN :subject_person_id IS NULL THEN NULL ELSE :subject_person_id::uuid END,
            :tags::text[],
            :scene_context,
            :modality,
            :confidence,
            :related_memory_ids::uuid[],
            :candidate_id::uuid,
            CASE WHEN :source_event_id IS NULL THEN NULL ELSE :source_event_id::uuid END,
            CASE WHEN :source_action_id IS NULL THEN NULL ELSE :source_action_id::uuid END,
            CASE WHEN :session_id IS NULL THEN NULL ELSE :session_id::uuid END,
            'committed',
            :recall_explanation::jsonb
        )
        """,
        {
            "memory_id": memory_id,
            "agent_id": row["agent_id"],
            "space_id": row.get("space_id"),
            "tier": row["tier"],
            "content": row["content"],
            "participants": row.get("participants") or "[]",
            "provenance": json.dumps({"source": "gui_candidate_commit", "user_id": str(user.user_id)}),
            "subject_person_id": row.get("subject_person_id"),
            "tags": "{" + ",".join(commit_body.tags) + "}" if commit_body.tags else "{}",
            "scene_context": commit_body.scene_context,
            "modality": commit_body.modality,
            "confidence": row.get("confidence", 1.0),
            "related_memory_ids": "{" + ",".join(commit_body.related_memory_ids) + "}"
            if commit_body.related_memory_ids
            else "{}",
            "candidate_id": candidate_id,
            "source_event_id": row.get("source_event_id"),
            "source_action_id": row.get("source_action_id"),
            "session_id": row.get("session_id"),
            "recall_explanation": json.dumps(recall_explanation),
        },
    )
    db.execute(
        """
        UPDATE memory_candidates
        SET lifecycle_state = 'committed',
            reviewed_at = now()
        WHERE memory_candidate_id = :candidate_id::uuid
        """,
        {"candidate_id": candidate_id},
    )
    return {"memory_id": memory_id, "memory_candidate_id": candidate_id, "status": "committed"}


@app.delete("/api/memories/{memory_id}", name="api_delete_memory")
def api_delete_memory(request: Request, memory_id: str) -> dict:
    """Delete a memory."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Get the memory and check permission
    rows = db.query(
        """
        SELECT m.memory_id, m.agent_id
        FROM memories m
        INNER JOIN agent_memberships mb ON m.agent_id = mb.agent_id
        WHERE m.memory_id = :memory_id::uuid AND mb.user_id = :user_id::uuid AND mb.role IN ('admin', 'owner') AND mb.revoked_at IS NULL
    """,
        {"memory_id": memory_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Memory not found or permission denied")

    try:
        db.execute(
            """
            WITH updated AS (
              UPDATE memories
              SET lifecycle_state = 'tombstoned',
                  tombstoned_at = COALESCE(tombstoned_at, now()),
                  recall_explanation = COALESCE(recall_explanation, '{}'::jsonb)
                    || jsonb_build_object('tombstone_reason', 'gui_delete')
              WHERE memory_id = :memory_id::uuid
                AND tombstoned_at IS NULL
              RETURNING memory_id, agent_id
            )
            INSERT INTO memory_tombstones(memory_id, agent_id, reason, actor_type, actor_id)
            SELECT memory_id, agent_id, 'gui_delete', 'user', :user_id
            FROM updated
            ON CONFLICT (memory_id) DO NOTHING
            """,
            {"memory_id": memory_id, "user_id": str(user.user_id)},
        )
    except Exception as e:
        logger.error(f"Failed to delete memory: {e}")
        raise HTTPException(status_code=500, detail="Failed to delete memory")

    return {"message": "Memory deleted", "memory_id": memory_id, "tombstoned": True}


@app.post("/api/memories/{memory_id}/supersede", name="api_supersede_memory")
def api_supersede_memory(request: Request, memory_id: str, body: MemorySupersedeIn) -> dict:
    """Mark a committed memory as superseded."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    rows = db.query(
        """
        SELECT m.memory_id::TEXT as memory_id, m.agent_id::TEXT as agent_id, m.lifecycle_state
        FROM memories m
        INNER JOIN agent_memberships mb ON m.agent_id = mb.agent_id
        WHERE m.memory_id = :memory_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN ('admin', 'owner')
          AND mb.revoked_at IS NULL
        """,
        {"memory_id": memory_id, "user_id": str(user.user_id)},
    )
    if not rows:
        raise HTTPException(status_code=404, detail="Memory not found or permission denied")
    if rows[0].get("lifecycle_state") == "tombstoned":
        raise HTTPException(status_code=409, detail="Tombstoned memories cannot be superseded")

    db.execute(
        """
        UPDATE memories
        SET lifecycle_state = 'superseded',
            recall_explanation = COALESCE(recall_explanation, '{}'::jsonb)
              || jsonb_build_object(
                   'superseded_by_memory_id', NULLIF(CAST(:superseded_by_memory_id AS text), ''),
                   'supersede_reason', NULLIF(CAST(:reason AS text), ''),
                   'superseded_by_user_id', CAST(:user_id AS text)
                 )
        WHERE memory_id = :memory_id::uuid
        """,
        {
            "memory_id": memory_id,
            "user_id": str(user.user_id),
            "superseded_by_memory_id": body.superseded_by_memory_id or "",
            "reason": body.reason or "",
        },
    )
    return {
        "memory_id": memory_id,
        "status": "superseded",
        "superseded_by_memory_id": body.superseded_by_memory_id,
    }


@app.get("/api/memories/{memory_id}", name="api_get_memory")
def api_get_memory(request: Request, memory_id: str) -> dict:
    """Get memory details."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Get the memory and check permission (member role sufficient for viewing)
    rows = db.query(
        """
        SELECT m.memory_id::TEXT as memory_id, m.agent_id::TEXT as agent_id,
               m.space_id::TEXT as space_id, m.tier, m.content,
               m.participants::TEXT as participants,
               m.provenance::TEXT as provenance,
               m.retention::TEXT as retention,
               m.memory_candidate_id::TEXT as memory_candidate_id,
               m.source_event_id::TEXT as source_event_id,
               m.source_action_id::TEXT as source_action_id,
               m.session_id::TEXT as session_id,
               m.location_id::TEXT as location_id,
               l.name as location_name,
               m.lifecycle_state,
               m.tapdb_euid,
               m.tombstoned_at::TEXT as tombstoned_at,
               m.recall_explanation::TEXT as recall_explanation,
               mt.memory_tombstone_id::TEXT as memory_tombstone_id,
               mt.reason as tombstone_reason,
               mt.actor_type as tombstone_actor_type,
               mt.actor_id as tombstone_actor_id,
               mt.tapdb_euid as tombstone_tapdb_euid,
               mt.created_at::TEXT as tombstone_created_at,
               m.created_at::TEXT as created_at,
               a.name as agent_name, s.name as space_name,
               m.subject_person_id::TEXT as subject_person_id,
               p.display_name as subject_person_name,
               m.tags, m.scene_context, m.modality, m.confidence,
               m.related_memory_ids::TEXT[] as related_memory_ids
        FROM memories m
        INNER JOIN agents a ON m.agent_id = a.agent_id
        LEFT JOIN spaces s ON m.space_id = s.space_id
        LEFT JOIN locations l ON l.location_id = m.location_id
        LEFT JOIN people p ON p.person_id = m.subject_person_id
        LEFT JOIN memory_tombstones mt ON mt.memory_id = m.memory_id
        INNER JOIN agent_memberships mb ON m.agent_id = mb.agent_id
        WHERE m.memory_id = :memory_id::uuid
          AND mb.user_id = :user_id::uuid
          AND mb.role IN ('member', 'admin', 'owner')
          AND mb.revoked_at IS NULL
    """,
        {"memory_id": memory_id, "user_id": str(user.user_id)},
    )

    if not rows:
        raise HTTPException(status_code=404, detail="Memory not found or permission denied")

    row = rows[0]

    # Parse JSON fields
    try:
        participants = json.loads(row.get("participants") or "[]")
    except Exception:
        participants = []
    try:
        provenance = json.loads(row.get("provenance") or "{}")
    except Exception:
        provenance = {}
    try:
        retention = json.loads(row.get("retention") or "{}")
    except Exception:
        retention = {}
    try:
        recall_explanation = json.loads(row.get("recall_explanation") or "{}")
    except Exception:
        recall_explanation = {}

    tombstone = {}
    if row.get("memory_tombstone_id") or row.get("tombstoned_at"):
        tombstone = {
            "memory_tombstone_id": row.get("memory_tombstone_id"),
            "reason": row.get("tombstone_reason"),
            "actor_type": row.get("tombstone_actor_type"),
            "actor_id": row.get("tombstone_actor_id"),
            "tapdb_euid": row.get("tombstone_tapdb_euid"),
            "created_at": row.get("tombstone_created_at"),
        }

    return {
        "memory_id": row["memory_id"],
        "agent_id": row["agent_id"],
        "agent_name": row.get("agent_name", ""),
        "space_id": row.get("space_id"),
        "space_name": row.get("space_name"),
        "memory_candidate_id": row.get("memory_candidate_id"),
        "source_event_id": row.get("source_event_id"),
        "source_action_id": row.get("source_action_id"),
        "session_id": row.get("session_id"),
        "location_id": row.get("location_id"),
        "location_name": row.get("location_name"),
        "lifecycle_state": row.get("lifecycle_state"),
        "tapdb_euid": row.get("tapdb_euid"),
        "tombstoned_at": row.get("tombstoned_at"),
        "tier": row["tier"],
        "content": row["content"],
        "participants": participants,
        "provenance": provenance,
        "retention": retention,
        "recall_explanation": recall_explanation,
        "tombstone": tombstone,
        "created_at": row["created_at"],
        "subject_person_id": row.get("subject_person_id"),
        "subject_person_name": row.get("subject_person_name"),
        "tags": row.get("tags") or [],
        "scene_context": row.get("scene_context"),
        "modality": row.get("modality", "text"),
        "confidence": row.get("confidence", 1.0),
        "related_memory_ids": row.get("related_memory_ids") or [],
    }


def _get_file_icon(filename: str) -> str:
    """Get Font Awesome icon class for a file type."""
    ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
    icon_map = {
        "pdf": "fa-file-pdf",
        "doc": "fa-file-word",
        "docx": "fa-file-word",
        "xls": "fa-file-excel",
        "xlsx": "fa-file-excel",
        "ppt": "fa-file-powerpoint",
        "pptx": "fa-file-powerpoint",
        "jpg": "fa-file-image",
        "jpeg": "fa-file-image",
        "png": "fa-file-image",
        "gif": "fa-file-image",
        "webp": "fa-file-image",
        "mp3": "fa-file-audio",
        "wav": "fa-file-audio",
        "ogg": "fa-file-audio",
        "flac": "fa-file-audio",
        "mp4": "fa-file-video",
        "webm": "fa-file-video",
        "mov": "fa-file-video",
        "avi": "fa-file-video",
        "zip": "fa-file-archive",
        "tar": "fa-file-archive",
        "gz": "fa-file-archive",
        "rar": "fa-file-archive",
        "txt": "fa-file-alt",
        "md": "fa-file-alt",
        "py": "fa-file-code",
        "js": "fa-file-code",
        "ts": "fa-file-code",
        "html": "fa-file-code",
        "css": "fa-file-code",
        "json": "fa-file-code",
    }
    return icon_map.get(ext, "fa-file")


def _format_file_size(size_bytes: int) -> str:
    """Format file size in human-readable format."""
    if size_bytes < 1024:
        return f"{size_bytes} B"
    elif size_bytes < 1024 * 1024:
        return f"{size_bytes / 1024:.1f} KB"
    elif size_bytes < 1024 * 1024 * 1024:
        return f"{size_bytes / (1024 * 1024):.1f} MB"
    else:
        return f"{size_bytes / (1024 * 1024 * 1024):.1f} GB"


@app.get("/artifacts", name="gui_artifacts")
def gui_artifacts(request: Request) -> Response:
    """Artifacts browser."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/artifacts")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)

    # List artifacts from S3 for each agent
    agent_ids = [a.agent_id for a in agents]
    artifacts_data = []
    total_size = 0

    if agent_ids and _cfg.artifact_bucket:
        from datetime import datetime, timezone

        s3 = _get_s3()
        agent_name_map = {a.agent_id: a.name for a in agents}

        for agent_id in agent_ids:
            prefix = f"artifacts/agent_id={agent_id}/"
            try:
                paginator = s3.get_paginator("list_objects_v2")
                for page in paginator.paginate(Bucket=_cfg.artifact_bucket, Prefix=prefix):
                    for obj in page.get("Contents", []):
                        key = obj.get("Key", "")
                        size = obj.get("Size", 0)
                        last_modified = obj.get("LastModified")
                        total_size += size

                        # Extract filename from key
                        filename = key.split("/")[-1]
                        # Remove UUID prefix if present
                        if "_" in filename and len(filename.split("_")[0]) == 36:
                            filename = "_".join(filename.split("_")[1:])

                        # Calculate relative time
                        created_at_relative = None
                        if last_modified:
                            now = datetime.now(timezone.utc)
                            delta = now - last_modified
                            if delta.days > 0:
                                created_at_relative = f"{delta.days}d ago"
                            elif delta.seconds >= 3600:
                                created_at_relative = f"{delta.seconds // 3600}h ago"
                            else:
                                created_at_relative = f"{delta.seconds // 60}m ago"

                        # Generate presigned download URL
                        download_url = s3.generate_presigned_url(
                            ClientMethod="get_object",
                            Params={"Bucket": _cfg.artifact_bucket, "Key": key},
                            ExpiresIn=3600,
                        )

                        artifacts_data.append(
                            {
                                "key": key,
                                "filename": filename,
                                "agent_id": agent_id,
                                "agent_name": agent_name_map.get(agent_id, "Unknown"),
                                "size": size,
                                "size_formatted": _format_file_size(size),
                                "created_at_relative": created_at_relative,
                                "icon": _get_file_icon(filename),
                                "download_url": download_url,
                            }
                        )
            except Exception as e:
                logger.warning(f"Failed to list artifacts for agent {agent_id}: {e}")

        # Sort by last modified (most recent first)
        artifacts_data.sort(key=lambda x: x.get("created_at_relative", ""), reverse=False)

    agents_data = [{"agent_id": a.agent_id, "name": a.name, "role": a.role} for a in agents]

    return templates.TemplateResponse(
        request,
        "artifacts.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "artifacts",
            "artifacts": artifacts_data,
            "total_size_formatted": _format_file_size(total_size),
            "agents": agents_data,
            **_get_ws_context(request),
        },
    )


class ArtifactPresign(BaseModel):
    agent_id: str
    filename: str
    content_type: str = "application/octet-stream"
    purpose: str | None = Field(default="general", description="general|recognition")


@app.post("/api/artifacts/presign", name="api_presign_upload")
def api_presign_upload(request: Request, body: ArtifactPresign) -> dict:
    """Get presigned URL for uploading an artifact."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()

    # Check admin/owner permission
    if not check_agent_permission(db, agent_id=body.agent_id, user_id=user.user_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Admin permission required")

    if not _cfg.artifact_bucket:
        raise HTTPException(status_code=500, detail="Artifact bucket not configured")

    import uuid as uuid_mod

    purpose = str(body.purpose or "general").strip().lower()
    if purpose not in {"general", "recognition", "visual"}:
        purpose = "general"
    prefix = purpose if purpose in {"recognition", "visual"} else "artifacts"
    key = f"{prefix}/agent_id={body.agent_id}/{uuid_mod.uuid4()}_{body.filename}"
    s3 = _get_s3()
    url = s3.generate_presigned_url(
        ClientMethod="put_object",
        Params={"Bucket": _cfg.artifact_bucket, "Key": key, "ContentType": body.content_type},
        ExpiresIn=900,
    )

    return {"upload_url": url, "key": key, "bucket": _cfg.artifact_bucket, "purpose": purpose}


@app.post("/api/artifacts/upload", name="api_upload_artifact")
async def api_upload_artifact(request: Request) -> dict:
    """Upload an artifact via server-side proxy (avoids CORS issues with S3)."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    form = await request.form()
    agent_id = form.get("agent_id")
    upload_file = form.get("file")

    if not agent_id or not upload_file:
        raise HTTPException(status_code=400, detail="agent_id and file are required")

    db = _get_db()
    if not check_agent_permission(db, agent_id=str(agent_id), user_id=user.user_id, required_role="admin"):
        raise HTTPException(status_code=403, detail="Admin permission required")

    if not _cfg.artifact_bucket:
        raise HTTPException(status_code=500, detail="Artifact bucket not configured")

    import uuid as uuid_mod

    purpose = str(form.get("purpose") or "general").strip().lower()
    if purpose not in {"general", "recognition", "visual"}:
        purpose = "general"
    prefix = purpose if purpose in {"recognition", "visual"} else "artifacts"
    filename = getattr(upload_file, "filename", "unknown")
    content_type = getattr(upload_file, "content_type", "application/octet-stream") or "application/octet-stream"
    key = f"{prefix}/agent_id={agent_id}/{uuid_mod.uuid4()}_{filename}"

    file_content = await upload_file.read()
    s3 = _get_s3()
    s3.put_object(
        Bucket=_cfg.artifact_bucket,
        Key=key,
        Body=file_content,
        ContentType=content_type,
    )

    return {
        "key": key,
        "bucket": _cfg.artifact_bucket,
        "filename": filename,
        "purpose": purpose,
        "uri": f"s3://{_cfg.artifact_bucket}/{key}",
    }


@app.get("/audit", name="gui_audit")
def gui_audit(request: Request) -> Response:
    """Audit log viewer."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(request=request, next_path="/audit")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)

    # List audit entries from S3 for each agent
    agent_ids = [a.agent_id for a in agents]
    entries_data = []
    entry_types = set()

    if agent_ids and _cfg.audit_bucket:
        from datetime import datetime, timezone

        s3 = _get_s3()
        agent_name_map = {a.agent_id: a.name for a in agents}

        for agent_id in agent_ids:
            prefix = f"audit/agent_id={agent_id}/"
            try:
                paginator = s3.get_paginator("list_objects_v2")
                for page in paginator.paginate(Bucket=_cfg.audit_bucket, Prefix=prefix, MaxKeys=100):
                    for obj in page.get("Contents", []):
                        key = obj.get("Key", "")
                        last_modified = obj.get("LastModified")

                        # Download and parse the audit entry
                        try:
                            resp = s3.get_object(Bucket=_cfg.audit_bucket, Key=key)
                            body = resp["Body"].read().decode("utf-8")
                            import json

                            entry = json.loads(body)

                            # Calculate relative time
                            ts_relative = None
                            if last_modified:
                                now = datetime.now(timezone.utc)
                                delta = now - last_modified
                                if delta.days > 0:
                                    ts_relative = f"{delta.days}d ago"
                                elif delta.seconds >= 3600:
                                    ts_relative = f"{delta.seconds // 3600}h ago"
                                else:
                                    ts_relative = f"{delta.seconds // 60}m ago"

                            # Data preview (truncate to 100 chars)
                            data_str = json.dumps(entry.get("data", {}))
                            data_preview = data_str[:100] + "..." if len(data_str) > 100 else data_str

                            entry_type = entry.get("type", "unknown")
                            entry_types.add(entry_type)

                            entries_data.append(
                                {
                                    "entry_id": entry.get("entry_id", ""),
                                    "agent_id": agent_id,
                                    "agent_name": agent_name_map.get(agent_id, "Unknown"),
                                    "type": entry_type,
                                    "ts": entry.get("ts", ""),
                                    "ts_relative": ts_relative,
                                    "hash": entry.get("hash", ""),
                                    "prev_hash": entry.get("prev_hash", "GENESIS"),
                                    "data": entry.get("data", {}),
                                    "data_preview": data_preview,
                                }
                            )
                        except Exception:
                            logger.warning("Failed to parse audit entry", exc_info=True)
            except Exception:
                logger.warning("Failed to list audit entries for an agent", exc_info=True)

        # Sort by timestamp (most recent first)
        entries_data.sort(key=lambda x: x.get("ts", ""), reverse=True)
        # Limit to 100 most recent
        entries_data = entries_data[:100]

    agents_data = [{"agent_id": a.agent_id, "name": a.name, "role": a.role} for a in agents]

    import json

    return templates.TemplateResponse(
        request,
        "audit.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "audit",
            "entries": entries_data,
            "entries_json": json.dumps(entries_data),
            "entry_types": sorted(entry_types),
            "agents": agents_data,
            **_get_ws_context(request),
        },
    )


@app.post("/api/audit/verify", name="api_audit_verify")
def api_audit_verify(request: Request) -> dict:
    """Verify the integrity of the audit chain."""
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)

    # Only admin/owner can verify
    admin_agents = [a for a in agents if a.role in ("admin", "owner")]
    if not admin_agents:
        raise HTTPException(status_code=403, detail="Admin permission required")

    if not _cfg.audit_bucket:
        return {"valid": False, "error": "Audit bucket not configured", "entries_checked": 0}

    import hashlib
    import json
    from typing import Any as _Any

    def _canon_json(obj: _Any) -> str:
        return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)

    def _sha256_hex(s: str) -> str:
        return hashlib.sha256(s.encode("utf-8")).hexdigest()

    s3 = _get_s3()
    entries_checked = 0
    errors = []

    for agent in admin_agents:
        agent_id = agent.agent_id
        prefix = f"audit/agent_id={agent_id}/"
        entries = []

        try:
            paginator = s3.get_paginator("list_objects_v2")
            for page in paginator.paginate(Bucket=_cfg.audit_bucket, Prefix=prefix):
                for obj in page.get("Contents", []):
                    key = obj.get("Key", "")
                    try:
                        resp = s3.get_object(Bucket=_cfg.audit_bucket, Key=key)
                        body = resp["Body"].read().decode("utf-8")
                        entry = json.loads(body)
                        entries.append(entry)
                    except Exception:
                        logger.warning("Failed to read audit entry during verification", exc_info=True)
                        errors.append("Failed to read an audit entry.")
        except Exception:
            logger.warning("Failed to list audit entries during verification", exc_info=True)
            errors.append("Failed to list audit entries for an agent.")
            continue

        # Sort by timestamp
        entries.sort(key=lambda x: x.get("ts", ""))

        # Verify chain
        expected_prev = "GENESIS"
        for entry in entries:
            prev_hash = entry.get("prev_hash", "")
            if prev_hash != expected_prev:
                errors.append(
                    f"Chain break at entry {entry.get('entry_id')}: expected prev_hash {expected_prev[:12]}..., got {prev_hash[:12]}..."
                )

            # Verify hash
            stored_hash = entry.get("hash", "")
            entry_copy = {k: v for k, v in entry.items() if k != "hash"}
            computed_hash = _sha256_hex(prev_hash + _canon_json(entry_copy))
            if computed_hash != stored_hash:
                errors.append(f"Hash mismatch at entry {entry.get('entry_id')}")

            expected_prev = stored_hash
            entries_checked += 1

    if errors:
        return {"valid": False, "error": "Audit verification failed.", "entries_checked": entries_checked}

    return {"valid": True, "entries_checked": entries_checked}


@app.get("/profile", name="profile")
def gui_profile(request: Request) -> Response:
    """User profile page - shows account info and agent memberships."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(
            request=request, next_path=str(request.scope.get("path") or "/"), clear_session=False
        )

    db = _get_db()
    agents = list_agents_for_user(db, user_id=user.user_id)
    agents_data = [
        {
            "agent_id": str(a.agent_id),
            "name": a.name,
            "role": a.role,
            "relationship_label": a.relationship_label,
        }
        for a in agents
    ]

    # --- Infrastructure / S3 bucket status ---
    def _check_bucket(name: str | None) -> dict:
        """Return bucket status dict: name, exists, region, error."""
        if not name:
            return {"name": None, "exists": False, "region": None, "error": "Not configured"}
        try:
            s3 = _get_s3()
            loc = s3.get_bucket_location(Bucket=name)
            region = loc.get("LocationConstraint") or "us-east-1"
            return {"name": name, "exists": True, "region": region, "error": None}
        except s3.exceptions.NoSuchBucket:
            return {"name": name, "exists": False, "region": None, "error": "Bucket does not exist"}
        except Exception as exc:
            return {"name": name, "exists": False, "region": None, "error": str(exc)}

    artifact_bucket = _check_bucket(_cfg.artifact_bucket)
    audit_bucket = _check_bucket(_cfg.audit_bucket)

    return templates.TemplateResponse(
        request,
        "profile.html",
        {
            "user": {
                "email": user.email,
                "user_id": str(user.user_id),
                "cognito_sub": getattr(user, "cognito_sub", None),
            },
            "stage": _cfg.stage,
            "active_page": "profile",
            "agents": agents_data,
            "artifact_bucket": artifact_bucket,
            "audit_bucket": audit_bucket,
            "aws_region": _cfg.cognito_region or os.getenv("AWS_REGION", "us-east-1"),
            **_get_ws_context(request),
        },
    )


@app.get("/livekit-test", name="gui_livekit_test")
def gui_livekit_test(request: Request, space_id: str | None = None) -> Response:
    """LiveKit test page - join a LiveKit room mapped from a Marvain space."""
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(
            request=request, next_path=str(request.scope.get("path") or "/"), clear_session=False
        )

    # Fetch spaces for dropdown
    spaces = list_spaces_for_user(_get_db(), user_id=user.user_id)
    spaces_data = [
        {
            "space_id": sp.space_id,
            "name": sp.name,
            "agent_id": str(getattr(sp, "agent_id", "") or ""),
            "agent_name": sp.agent_name,
            "livekit_room_mode": getattr(sp, "livekit_room_mode", "ephemeral"),
        }
        for sp in spaces
    ]

    selected_space = str(space_id or "").strip()
    token_url = _gui_path(request, "/livekit/token")

    return templates.TemplateResponse(
        request,
        "livekit_test.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "livekit",
            "spaces": spaces_data,
            "selected_space": selected_space,
            "token_url": token_url,
            **_get_ws_context(request),
        },
    )


@app.post("/livekit/token", response_model=LiveKitTokenOut)
async def gui_livekit_token(request: Request, body: LiveKitTokenIn) -> LiveKitTokenOut:
    user = _gui_get_user(request)
    if not user:
        raise HTTPException(status_code=401, detail="Not authenticated")
    return await _mint_livekit_token_for_user(user=user, space_id=body.space_id, room_mode=body.room_mode)


@app.get("/agents/{agent_id}", name="gui_agent_detail")
def gui_agent_detail(request: Request, agent_id: str) -> Response:
    user = _gui_get_user(request)
    if not user:
        return _gui_redirect_to_login(
            request=request, next_path=str(request.scope.get("path") or "/"), clear_session=False
        )

    db = _get_db()
    # Ensure the user can see this agent by filtering their memberships.
    agents = list_agents_for_user(db, user_id=user.user_id)
    match = next((a for a in agents if a.agent_id == agent_id), None)
    if not match:
        return PlainTextResponse("not found", status_code=404)

    # Fetch members for this agent
    members_rows = db.query(
        "SELECT m.user_id, m.role, m.relationship_label, m.created_at, u.email "
        "FROM agent_memberships m LEFT JOIN users u ON m.user_id = u.user_id "
        "WHERE m.agent_id = :agent_id::uuid AND m.revoked_at IS NULL ORDER BY m.created_at",
        {"agent_id": agent_id},
    )
    members = [
        {
            "user_id": str(row.get("user_id", "")),
            "role": row.get("role", "member"),
            "relationship_label": row.get("relationship_label"),
            "email": row.get("email"),
            "created_at": str(row.get("created_at", ""))[:10] if row.get("created_at") else None,
        }
        for row in members_rows
    ]

    agent_data = {
        "agent_id": str(match.agent_id),
        "name": match.name,
        "role": match.role,
        "relationship_label": match.relationship_label,
        "disabled": match.disabled,
    }

    # Fetch summary counts for this agent
    summary_rows = db.query(
        """
        SELECT
          (SELECT count(*) FROM devices WHERE agent_id = :aid::uuid AND revoked_at IS NULL) AS device_count,
          (SELECT count(*) FROM spaces WHERE agent_id = :aid::uuid) AS space_count,
          (SELECT count(*) FROM memories WHERE agent_id = :aid::uuid) AS memory_count,
          (SELECT count(*) FROM events WHERE agent_id = :aid::uuid) AS event_count
    """,
        {"aid": agent_id},
    )
    sr = summary_rows[0] if summary_rows else {}
    worker = _agent_worker_status_dict()
    summary = {
        "device_count": sr.get("device_count", 0),
        "space_count": sr.get("space_count", 0),
        "memory_count": sr.get("memory_count", 0),
        "event_count": sr.get("event_count", 0),
        "worker_status": worker["status"],
        "worker_pid": worker["pid"],
    }

    return templates.TemplateResponse(
        request,
        "agent_detail.html",
        {
            "user": {"email": user.email, "user_id": str(user.user_id)},
            "stage": _cfg.stage,
            "active_page": "agents",
            "agent": agent_data,
            "members": members,
            "summary": summary,
            **_get_ws_context(request),
        },
    )