agentevo-cloud 0.1.0__py3-none-any.whl

agentevo_cloud/app.py

@@ -0,0 +1,2091 @@
+"""Cloud Control API: FastAPI factory, error model, and routes.
+
+Every route authenticates via Bearer tokens except /healthz and the auth
+flows themselves. The effective tenant always derives from the verified
+principal; request-body tenant IDs are consistency assertions only (400 on
+mismatch, never authorization). Quota headers ride every authenticated
+response; metering increments in the request transaction.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Awaitable, Callable, Iterator
+from contextlib import suppress
+from dataclasses import replace
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from uuid import uuid4
+
+from fastapi import Depends, FastAPI, Header, Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from agentevo_cloud.analytics import summarize
+from agentevo_cloud.config import Settings
+from agentevo_cloud.db import Database
+from agentevo_cloud.devices import (
+    DEVICE_POLL_INTERVAL,
+    DeviceRecord,
+    approve_device_code,
+    deny_device_code,
+    exchange_ci_token,
+    link_repo,
+    list_device_keys,
+    list_devices,
+    list_repos,
+    poll_device_flow,
+    register_device,
+    revoke_device,
+    start_device_flow,
+    unlink_repo,
+)
+from agentevo_cloud.events import ingest_batch
+from agentevo_cloud.jobs import (
+    JobState,
+    JobType,
+    cancel_job,
+    create_job,
+    get_job,
+    list_jobs,
+)
+from agentevo_cloud.managed import ManagedObject, get_managed, index_accepted
+from agentevo_cloud.metering import (
+    RETRY_AFTER_HEADER,
+    Usage,
+    check_rate_limit,
+    current_cycle,
+    is_billable,
+    quota_headers,
+    quota_warning,
+    record_checked,
+    retry_after_for,
+    unrecord_billable,
+    usage_for,
+)
+from agentevo_cloud.oidc import JwksFetcher, fetch_jwks
+from agentevo_cloud.promote import promote_managed
+from agentevo_cloud.recall import parse_environment, parse_query, recall
+from agentevo_cloud.records import (
+    audit,
+    idempotency_lookup,
+    idempotency_store,
+    list_audit,
+)
+from agentevo_cloud.revoke import revoke_object
+from agentevo_cloud.sync import pull_page, push_batch
+from agentevo_cloud.tenants import (
+    ADMIN_ROLE,
+    OWNER_ROLE,
+    add_membership,
+    create_tenant,
+    create_workspace,
+    delete_workspace_data,
+    entitlements_for,
+    export_workspace_data,
+    get_sync_mode,
+    get_tenant,
+    require_searchable,
+    set_sync_mode,
+)
+from agentevo_cloud.tokens import (
+    REFRESH_KIND,
+    Principal,
+    hash_token,
+    issue_pat,
+    list_tokens,
+    revoke_token,
+    rotate_refresh,
+    verify_token,
+)
+from agentevo_cloud.webhooks import (
+    Delivery,
+    Sender as WebhookSender,
+    WebhookConfig,
+    build_event,
+    create_config,
+    deliver_to_config,
+    dispatch,
+    get_config,
+    list_configs,
+    list_deliveries,
+    replay_delivery,
+    revoke_config,
+    rotate_config,
+    urllib_sender,
+)
+from agentevo_cloud.workers import (
+    DEFAULT_COMPILE_PROJECT,
+    ensure_workspace,
+    parse_bindings,
+    parse_canary_steps,
+    parse_fallbacks,
+    parse_required_str,
+    parse_rollback,
+    parse_skill_refs,
+)
+from agentevo_core.errors import HTTP_STATUS, AgentevoError, ErrorCode
+from agentevo_core.objects import LearnedObjectType
+from agentevo_core.trust import TrustState
+from agentevo_local.revoke import RevocationReason
+
+REQUEST_ID_HEADER = "X-Request-ID"
+
+#: 2xx bounds: _commit_middleware commits successes, rolls back the rest.
+_SUCCESS_MIN = 200
+_SUCCESS_MAX = 300
+
+
+def create_app(db: Database, settings: Settings) -> FastAPI:
+    """Build the Control API application over one database + settings."""
+    app = FastAPI(title="Agentevo Control API", version="v1")
+    app.state.db = db
+    app.state.settings = settings
+    app.exception_handler(AgentevoError)(_agentevo_handler)
+    app.exception_handler(RequestValidationError)(_validation_handler)
+    app.exception_handler(StarletteHTTPException)(_http_handler)
+    app.middleware("http")(_metering_middleware)
+    app.middleware("http")(_commit_middleware)
+    app.middleware("http")(_maintenance_middleware)
+    app.get("/healthz")(_healthz)
+    app.post("/v1/auth/tokens", status_code=201)(_issue_token)
+    app.get("/v1/auth/tokens")(_list_tokens)
+    app.delete("/v1/auth/tokens/{token_id}", status_code=204)(_revoke_token)
+    app.post("/v1/auth/token/refresh")(_refresh_token)
+    app.post("/v1/auth/device/code", status_code=201)(_device_code)
+    app.post("/v1/auth/device/token")(_device_token)
+    app.post("/v1/auth/device/approve")(_device_approve)
+    app.post("/v1/auth/device/deny")(_device_deny)
+    app.get("/v1/auth/oidc/config")(_oidc_config)
+    app.post("/v1/auth/ci/exchange", status_code=201)(_ci_exchange)
+    app.post("/v1/devices", status_code=201)(_register_device)
+    app.get("/v1/devices")(_list_devices)
+    app.delete("/v1/devices/{device_id}", status_code=204)(_revoke_device)
+    _register_workspace_routes(app)
+    app.get("/v1/analytics/summary")(_analytics_summary)
+    app.post("/v1/webhooks", status_code=201)(_create_webhook)
+    app.get("/v1/webhooks")(_list_webhooks)
+    app.delete("/v1/webhooks/{config_id}", status_code=204)(_revoke_webhook)
+    app.post("/v1/webhooks/{config_id}/rotate")(_rotate_webhook)
+    app.post("/v1/webhooks/test")(_test_webhook)
+    app.get("/v1/webhooks/{config_id}/deliveries")(_webhook_deliveries)
+    app.post("/v1/webhooks/deliveries/{delivery_id}/replay")(_replay_webhook)
+    app.post("/v1/sync/push")(_sync_push)
+    app.post("/v1/sync/pull")(_sync_pull)
+    app.post("/v1/events/batch", status_code=201)(_events_batch)
+    app.post("/v1/recall")(_recall)
+    _register_object_routes(app)
+    _register_job_routes(app)
+    _register_compile_routes(app)
+    app.get("/v1/revocations")(_revocations)
+    app.get("/v1/entitlements")(_entitlements)
+    app.get("/v1/usage")(_usage)
+    app.get("/v1/audit")(_audit)
+    # Re-exported for the provision CLI and tests.
+    app.state.create_tenant = create_tenant
+    app.state.add_membership = add_membership
+    app.state.create_workspace = create_workspace
+    return app
+
+
+def _register_workspace_routes(app: FastAPI) -> None:
+    """Workspace repos, BR-011 export/delete, and sync-mode consent."""
+    app.post("/v1/workspaces/{slug}/repos", status_code=201)(_link_repo)
+    app.get("/v1/workspaces/{slug}/repos")(_list_repos)
+    app.delete("/v1/workspaces/{slug}/repos/{repo:path}", status_code=204)(_unlink_repo)
+    app.get("/v1/workspaces/{slug}/export")(_export_workspace)
+    app.delete("/v1/workspaces/{slug}/cloud-data")(_delete_workspace_data)
+    app.get("/v1/workspaces/{slug}/sync-mode")(_get_sync_mode)
+    app.post("/v1/workspaces/{slug}/sync-mode")(_set_sync_mode)
+
+
+def _register_object_routes(app: FastAPI) -> None:
+    """Managed object lifecycle: verify, revalidate, promote, fetch versions."""
+    app.post("/v1/objects/{object_id}/verify", status_code=202)(_verify_object)
+    app.post("/v1/objects/{object_id}/revalidate", status_code=202)(_revalidate_object)
+    app.post("/v1/objects/{object_id}/promote")(_promote_object)
+    app.post("/v1/objects/{object_id}/revoke")(_revoke_object)
+    app.get("/v1/objects/{object_id}/versions/{version}")(_get_object_version)
+
+
+def _register_job_routes(app: FastAPI) -> None:
+    """Async job polling, listing, and best-effort cancellation."""
+    app.get("/v1/jobs/{job_id}")(_get_job)
+    app.get("/v1/jobs")(_list_jobs)
+    app.post("/v1/jobs/{job_id}/cancel")(_cancel_job)
+
+
+def _register_compile_routes(app: FastAPI) -> None:
+    """Async compile submissions (experiences and workflows)."""
+    app.post("/v1/experiences/compile", status_code=202)(_compile_experiences)
+    app.post("/v1/workflows/compile", status_code=202)(_compile_workflows)
+
+
+async def _agentevo_handler(request: Request, exc: AgentevoError) -> JSONResponse:
+    _ = request
+    return _error_response(exc.code, exc.message, exc.details, exc)
+
+
+async def _validation_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    _ = request
+    details = {"errors": exc.errors()}
+    return _error_response(ErrorCode.INVALID_ARGUMENT, "request validation failed", details, None)
+
+
+async def _http_handler(request: Request, exc: StarletteHTTPException) -> JSONResponse:
+    _ = request
+    if exc.status_code == HTTP_STATUS[ErrorCode.NOT_FOUND]:
+        return _error_response(ErrorCode.NOT_FOUND, "unknown route", {}, None)
+    return _error_response(ErrorCode.INVALID_ARGUMENT, str(exc.detail), {}, None)
+
+
+#: Methods that keep serving while the control plane is in maintenance.
+_MAINTENANCE_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+async def _maintenance_middleware(
+    request: Request, call_next: Callable[[Request], Awaitable[Response]]
+) -> Response:
+    """Global kill switch: read-only mode when maintenance is set.
+
+    Registered last so it runs outermost: mutations 503 before metering
+    or the database are touched (clients back off; the SDK maps 503 to
+    retryable), while status reads, job polls, and revocation reads keep
+    serving. The local runtime is unaffected by design.
+    """
+    settings: Settings = request.app.state.settings
+    if settings.maintenance_mode and request.method not in _MAINTENANCE_SAFE_METHODS:
+        exc = AgentevoError(
+            ErrorCode.TEMPORARILY_UNAVAILABLE,
+            "control plane in maintenance",
+            {"maintenance": True},
+        )
+        response = _error_response(exc.code, exc.message, exc.details, exc)
+        response.headers[RETRY_AFTER_HEADER] = "60"
+        return response
+    return await call_next(request)
+
+
+async def _metering_middleware(
+    request: Request, call_next: Callable[[Request], Awaitable[Response]]
+) -> Response:
+    # Header-only by design: metering writes happen in the request
+    # transaction, and only _commit_middleware settles it.
+    response = await call_next(request)
+    usage = getattr(request.state, "usage", None)
+    if usage is None:
+        return response
+    headers = quota_headers(usage)
+    for key, value in headers.items():
+        response.headers[key] = value
+    return response
+
+
+async def _commit_middleware(
+    request: Request, call_next: Callable[[Request], Awaitable[Response]]
+) -> Response:
+    """Settle the request transaction before the response hits the wire.
+
+    Dependency teardown (where ``Database.connect`` commits) runs after
+    response bytes are sent, so without this a client that POSTs then
+    immediately reads can observe its own write as missing. Success (2xx)
+    commits here; errors roll back (failed attempts never bill); an
+    escaping exception rolls back and propagates. Teardown's own commit
+    stays as a no-op safety net (and the commit path for non-HTTP use).
+    """
+    try:
+        response = await call_next(request)
+    except BaseException:
+        conn = getattr(request.state, "conn", None)
+        if conn is not None:
+            conn.rollback()
+        raise
+    conn = getattr(request.state, "conn", None)
+    if conn is not None:
+        if _SUCCESS_MIN <= response.status_code < _SUCCESS_MAX:
+            conn.commit()
+        else:
+            conn.rollback()
+    return response
+
+
+def get_conn(request: Request) -> Iterator[sqlite3.Connection]:
+    """Request-scoped database connection."""
+    db: Database = request.app.state.db
+    with db.connect() as conn:
+        request.state.conn = conn
+        try:
+            yield conn
+        finally:
+            # Teardown runs before error responses reach middleware (but
+            # after success bytes are sent); clearing the handle tells
+            # _commit_middleware there is nothing left to settle. The
+            # context exit already rolled back on this path.
+            request.state.conn = None
+
+
+def current_principal(
+    request: Request,
+    authorization: str | None = Header(default=None),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> Principal:
+    """Verified bearer principal (tenant derives from here)."""
+    secret = _bearer_secret(authorization)
+    principal = verify_token(conn, secret)
+    _reject_refresh(principal)
+    if get_tenant(conn, principal.tenant_id) is None:
+        raise AgentevoError(ErrorCode.UNAUTHENTICATED, "tenant is gone", {})
+    request.state.principal = principal
+    return principal
+
+
+def optional_principal(
+    request: Request,
+    authorization: str | None = Header(default=None),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> Principal | None:
+    """Bearer principal when presented (401 on a bad credential, else None)."""
+    if authorization is None:
+        return None
+    principal = verify_token(conn, _bearer_secret(authorization))
+    _reject_refresh(principal)
+    if get_tenant(conn, principal.tenant_id) is None:
+        raise AgentevoError(ErrorCode.UNAUTHENTICATED, "tenant is gone", {})
+    request.state.principal = principal
+    request.state.usage = usage_for(conn, principal.tenant_id)
+    return principal
+
+
+def metered(
+    request: Request,
+    principal: Principal = Depends(current_principal),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> Principal:
+    """Rate guard + attempt metering (AWS-style; replays un-count later)."""
+    settings: Settings = request.app.state.settings
+    check_rate_limit(conn, f"token:{principal.token_id}", settings.rate_limit_per_minute)
+    if not is_billable(request.method, request.url.path):
+        request.state.usage = usage_for(conn, principal.tenant_id)
+        return principal
+    request.state.usage = _record_and_notify(request, conn, principal.tenant_id)
+    request.state.billable = True
+    return principal
+
+
+def _record_and_notify(request: Request, conn: sqlite3.Connection, tenant_id: str) -> Usage:
+    """Quota-checked metering plus 80%/exhausted webhook notification."""
+    try:
+        usage = record_checked(conn, tenant_id)
+    except AgentevoError as exc:
+        if exc.code is ErrorCode.QUOTA_EXCEEDED:
+            cycle = current_cycle()
+            if not _quota_event_sent(conn, tenant_id, "quota.exhausted", cycle):
+                _emit_quota_event(
+                    request,
+                    conn,
+                    tenant_id,
+                    "quota.exhausted",
+                    cycle=cycle,
+                    used=exc.details.get("used", 0),
+                    quota=exc.details.get("quota"),
+                    reset_at=str(exc.details.get("reset_at", "")),
+                )
+                # The 429 below rolls the request transaction back; persist
+                # the notification (and the restored counter) first.
+                conn.commit()
+        raise
+    before = replace(usage, used=usage.used - 1)
+    if quota_warning(usage) and not quota_warning(before):
+        _emit_quota_event(
+            request,
+            conn,
+            tenant_id,
+            "quota.warning",
+            cycle=usage.cycle,
+            used=usage.used,
+            quota=usage.quota,
+            reset_at=usage.reset_at,
+        )
+    return usage
+
+
+def _quota_event_sent(
+    conn: sqlite3.Connection, tenant_id: str, event_type: str, cycle: str
+) -> bool:
+    """True when this cycle already recorded the quota event (dedupes 429 storms)."""
+    bound = f"{cycle}-01T00:00:00+00:00"
+    row = conn.execute(
+        "SELECT 1 FROM webhook_deliveries"
+        " WHERE tenant_id = ? AND event_type = ? AND created_at >= ? LIMIT 1",
+        (tenant_id, event_type, bound),
+    ).fetchone()
+    return row is not None
+
+
+def _emit_quota_event(  # noqa: PLR0913 - notification carries quota context
+    request: Request,
+    conn: sqlite3.Connection,
+    tenant_id: str,
+    event_type: str,
+    *,
+    cycle: str,
+    used: int,
+    quota: int | None,
+    reset_at: str,
+) -> None:
+    """Best-effort quota fan-out (notification never fails the request)."""
+    payload = {"used": used, "quota": quota, "cycle": cycle, "reset_at": reset_at}
+    with suppress(Exception):
+        settings: Settings = request.app.state.settings
+        event = build_event(event_type, tenant_id, f"quota/{cycle}", payload=payload)
+        dispatch(
+            conn,
+            settings,
+            tenant_id,
+            event,
+            sender=_webhook_sender(request),
+            timeout_seconds=settings.webhook_timeout_seconds,
+        )
+
+
+def require_scope(scope: str) -> Any:
+    """Dependency factory enforcing one token scope (403 when missing)."""
+
+    def scoped(principal: Principal = Depends(metered)) -> Principal:
+        if not principal.allows(scope):
+            raise AgentevoError(
+                ErrorCode.FORBIDDEN,
+                f"token lacks required scope: {scope}",
+                {"scope": scope},
+            )
+        return principal
+
+    return scoped
+
+
+CONTROL_READ = require_scope("control:read")
+AUDIT_READ = require_scope("audit:read")
+SYNC_WRITE = require_scope("sync:write")
+SYNC_READ = require_scope("sync:read")
+RECALL_READ = require_scope("recall:read")
+VERIFY_RUN = require_scope("verify:run")
+OBJECT_PROMOTE = require_scope("object:promote")
+OBJECT_REVOKE = require_scope("object:revoke")
+
+
+def _reject_refresh(principal: Principal) -> None:
+    """Refresh tokens rotate; they never authenticate API calls."""
+    if principal.kind == REFRESH_KIND:
+        raise AgentevoError(ErrorCode.UNAUTHENTICATED, "refresh tokens cannot call this API", {})
+
+
+def _client_ip(request: Request) -> str:
+    client = request.client
+    return client.host if client is not None and client.host else "unknown"
+
+
+def _auth_rate_limit(request: Request, conn: sqlite3.Connection, name: str) -> None:
+    """IP-keyed burst guard for the unauthenticated auth flows."""
+    settings: Settings = request.app.state.settings
+    check_rate_limit(conn, f"auth:{name}:{_client_ip(request)}", settings.rate_limit_per_minute)
+
+
+def _idempotent(  # noqa: PLR0913, PLR0917 - idempotency carries request context
+    request: Request,
+    conn: sqlite3.Connection,
+    tenant_id: str,
+    key: str | None,
+    body: dict[str, Any],
+    compute: Callable[[], tuple[int, dict[str, Any]]],
+) -> JSONResponse:
+    """Honor Idempotency-Key: replay stored responses, un-counting quota.
+
+    Anonymous bootstrap flows (device start, CI exchange) share the empty
+    tenant namespace; their responses carry no tenant data before approval.
+    """
+    route = f"{request.method} {request.url.path}"
+    if key is not None:
+        replay = idempotency_lookup(conn, tenant_id, route, key, body)
+        if replay is not None:
+            if getattr(request.state, "billable", False):
+                request.state.usage = unrecord_billable(conn, tenant_id)
+            return JSONResponse(status_code=replay.status_code, content=replay.body)
+    status, payload = compute()
+    if key is not None:
+        settings: Settings = request.app.state.settings
+        raced = idempotency_store(
+            conn,
+            tenant_id,
+            route,
+            key,
+            body=body,
+            status_code=status,
+            response=payload,
+            ttl=timedelta(seconds=settings.idempotency_ttl_seconds),
+        )
+        if raced is not None:
+            # A concurrent twin stored first; serve the winner and un-count
+            # this attempt exactly like an idempotent replay.
+            if getattr(request.state, "billable", False):
+                request.state.usage = unrecord_billable(conn, tenant_id)
+            return JSONResponse(status_code=raced.status_code, content=raced.body)
+    return JSONResponse(status_code=status, content=payload)
+
+
+def _jwks_fetcher(request: Request) -> JwksFetcher:
+    fetcher: JwksFetcher | None = getattr(request.app.state, "jwks_fetcher", None)
+    return fetcher or fetch_jwks
+
+
+def _webhook_sender(request: Request) -> WebhookSender:
+    sender: WebhookSender | None = getattr(request.app.state, "webhook_sender", None)
+    return sender or urllib_sender
+
+
+def _healthz() -> dict[str, str]:
+    return {"status": "ok", "version": "v1"}
+
+
+def _issue_token(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    name, scopes, workspaces, ttl = _token_body(body)
+    if principal.user_id is None:
+        raise AgentevoError(ErrorCode.FORBIDDEN, "service tokens cannot issue PATs", {})
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        issued = issue_pat(
+            conn,
+            principal.tenant_id,
+            name,
+            scopes,
+            user_id=principal.user_id or "",
+            workspaces=workspaces,
+            ttl=ttl,
+        )
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "token_issued",
+            issued.record.id,
+            details={"scopes": scopes, "name": name},
+        )
+        return 201, {
+            "id": issued.record.id,
+            "secret": issued.secret,
+            "scopes": list(issued.record.scopes),
+            "workspaces": list(issued.record.workspaces),
+            "expires_at": issued.record.expires_at,
+        }
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _list_tokens(
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    return {
+        "tokens": [
+            {
+                "id": record.id,
+                "kind": record.kind,
+                "name": record.name,
+                "scopes": list(record.scopes),
+                "workspaces": list(record.workspaces),
+                "user_id": record.user_id,
+                "expires_at": record.expires_at,
+                "revoked_at": record.revoked_at,
+                "created_at": record.created_at,
+                "last_used_at": record.last_used_at,
+            }
+            for record in list_tokens(conn, principal.tenant_id)
+        ]
+    }
+
+
+def _revoke_token(
+    token_id: str,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> Response:
+    revoke_token(conn, principal.tenant_id, token_id)
+    audit(conn, principal.tenant_id, principal.token_id, "token_revoked", token_id, details={})
+    return Response(status_code=204)
+
+
+def _refresh_token(
+    body: dict[str, Any],
+    request: Request,
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    settings: Settings = request.app.state.settings
+    _auth_rate_limit(request, conn, "refresh")
+    secret = body.get("refresh_token")
+    if not isinstance(secret, str) or not secret:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, "refresh_token must be a non-empty string", {}
+        )
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        access, refresh = rotate_refresh(
+            conn,
+            secret,
+            access_ttl=timedelta(seconds=settings.access_token_ttl_seconds),
+            refresh_ttl=timedelta(seconds=settings.refresh_token_ttl_seconds),
+        )
+        return 200, {
+            "access_token": access.secret,
+            "refresh_token": refresh.secret,
+            "expires_in": settings.access_token_ttl_seconds,
+            "scopes": list(access.record.scopes),
+        }
+
+    tenant_id = _refresh_owner(conn, secret)
+    return _idempotent(request, conn, tenant_id, idempotency_key, body, compute)
+
+
+def _refresh_owner(conn: sqlite3.Connection, secret: str) -> str:
+    """Tenant owning a refresh secret ("" when unknown; rotation decides)."""
+    row = conn.execute(
+        "SELECT tenant_id FROM tokens WHERE token_hash = ? AND kind = ?",
+        (hash_token(secret), REFRESH_KIND),
+    ).fetchone()
+    return row["tenant_id"] if row is not None else ""
+
+
+def _entitlements(
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    entitlements = entitlements_for(conn, principal.tenant_id)
+    return {
+        "tenant_id": entitlements.tenant_id,
+        "plan": entitlements.plan,
+        "quota_monthly": entitlements.quota_monthly,
+        "overage_enabled": entitlements.overage_enabled,
+        "scopes_grantable": list(entitlements.scopes_grantable),
+        "retention_note": entitlements.retention_note,
+    }
+
+
+def _usage(
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    usage = usage_for(conn, principal.tenant_id)
+    return {
+        "tenant_id": usage.tenant_id,
+        "plan": usage.plan,
+        "cycle": usage.cycle,
+        "used": usage.used,
+        "quota": usage.quota,
+        "remaining": usage.remaining,
+        "quota_warning": quota_warning(usage),
+        "overage_enabled": usage.overage_enabled,
+        "reset_at": usage.reset_at,
+    }
+
+
+def _device_code(
+    body: dict[str, Any],
+    request: Request,
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    settings: Settings = request.app.state.settings
+    _auth_rate_limit(request, conn, "device-code")
+    scopes, workspace = _device_code_body(body)
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        grant = start_device_flow(conn, settings, scopes=scopes, workspace_slug=workspace)
+        return 201, {
+            "device_code": grant.device_code,
+            "user_code": grant.user_code,
+            "verification_uri": grant.verification_uri,
+            "verification_uri_complete": grant.verification_uri_complete,
+            "expires_in": grant.expires_in,
+            "interval": grant.interval,
+        }
+
+    return _idempotent(request, conn, "", idempotency_key, body, compute)
+
+
+def _device_token(
+    body: dict[str, Any],
+    request: Request,
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    settings: Settings = request.app.state.settings
+    _auth_rate_limit(request, conn, "device-token")
+    code = body.get("device_code")
+    if not isinstance(code, str) or not code:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, "device_code must be a non-empty string", {}
+        )
+    poll = poll_device_flow(conn, settings, device_code=code)
+    if poll.status == "approved" and poll.access is not None and poll.refresh is not None:
+        return {
+            "status": "approved",
+            "access_token": poll.access.secret,
+            "refresh_token": poll.refresh.secret,
+            "expires_in": settings.access_token_ttl_seconds,
+            "scopes": list(poll.access.record.scopes),
+        }
+    if poll.status == "expired":
+        return {"status": "expired"}
+    return {"status": "pending", "interval": DEVICE_POLL_INTERVAL}
+
+
+def _device_approve(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal | None = Depends(optional_principal),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    settings: Settings = request.app.state.settings
+    _auth_rate_limit(request, conn, "device-approve")
+    user_code, id_token = _decision_body(body)
+    if principal is not None and id_token is not None:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT,
+            "approve with exactly one credential: Bearer [REDACTED] or id_token",
+            {},
+        )
+    if principal is not None:
+
+        def compute() -> tuple[int, dict[str, Any]]:
+            flow, identity = approve_device_code(
+                conn, settings, user_code=user_code, approver=principal
+            )
+            audit(
+                conn,
+                identity.tenant_id,
+                identity.user_id,
+                "device_approved",
+                flow.device_code_hash,
+                details={"via": "session", "scopes": list(flow.scopes)},
+            )
+            return 200, {
+                "status": "approved",
+                "scopes": list(flow.scopes),
+                "workspace": flow.workspace_slug,
+            }
+
+        return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+    flow, identity = approve_device_code(
+        conn,
+        settings,
+        user_code=user_code,
+        id_token=id_token,
+        jwks_fetcher=_jwks_fetcher(request),
+    )
+    audit(
+        conn,
+        identity.tenant_id,
+        identity.user_id,
+        "device_approved",
+        flow.device_code_hash,
+        details={"via": "oidc", "scopes": list(flow.scopes)},
+    )
+    return JSONResponse(
+        status_code=200,
+        content={
+            "status": "approved",
+            "scopes": list(flow.scopes),
+            "workspace": flow.workspace_slug,
+        },
+    )
+
+
+def _device_deny(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal | None = Depends(optional_principal),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    settings: Settings = request.app.state.settings
+    _auth_rate_limit(request, conn, "device-deny")
+    user_code, id_token = _decision_body(body)
+    if principal is not None and id_token is not None:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT,
+            "deny with exactly one credential: Bearer [REDACTED] or id_token",
+            {},
+        )
+    if principal is not None:
+
+        def compute() -> tuple[int, dict[str, Any]]:
+            flow, identity = deny_device_code(
+                conn, settings, user_code=user_code, approver=principal
+            )
+            audit(
+                conn,
+                identity.tenant_id,
+                identity.user_id,
+                "device_denied",
+                flow.device_code_hash,
+                details={"via": "session"},
+            )
+            return 200, {"status": "denied"}
+
+        return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+    flow, identity = deny_device_code(
+        conn,
+        settings,
+        user_code=user_code,
+        id_token=id_token,
+        jwks_fetcher=_jwks_fetcher(request),
+    )
+    audit(
+        conn,
+        identity.tenant_id,
+        identity.user_id,
+        "device_denied",
+        flow.device_code_hash,
+        details={"via": "oidc"},
+    )
+    return JSONResponse(status_code=200, content={"status": "denied"})
+
+
+def _oidc_config(request: Request, conn: sqlite3.Connection = Depends(get_conn)) -> dict[str, Any]:
+    settings: Settings = request.app.state.settings
+    _auth_rate_limit(request, conn, "oidc-config")
+    return {
+        "configured": bool(settings.oidc_issuer),
+        "issuer": settings.oidc_issuer,
+        "client_id": settings.oidc_client_id,
+        "audience": settings.oidc_client_id,
+        "verification_uri": f"{settings.base_url.rstrip('/')}/device",
+    }
+
+
+def _ci_exchange(
+    body: dict[str, Any],
+    request: Request,
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    settings: Settings = request.app.state.settings
+    _auth_rate_limit(request, conn, "ci-exchange")
+    credential = body.get("credential")
+    if not isinstance(credential, str) or not credential:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "credential must be a non-empty string", {})
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        issued, link = exchange_ci_token(
+            conn, settings, credential=credential, jwks_fetcher=_jwks_fetcher(request)
+        )
+        audit(
+            conn,
+            link.tenant_id,
+            issued.record.id,
+            "ci_token_issued",
+            link.repo,
+            details={"workspace": link.workspace_slug},
+        )
+        return 201, {
+            "token": issued.secret,
+            "token_id": issued.record.id,
+            "workspace": link.workspace_slug,
+            "repository": link.repo,
+            "scopes": list(issued.record.scopes),
+            "expires_at": issued.record.expires_at,
+        }
+
+    return _idempotent(request, conn, "", idempotency_key, body, compute)
+
+
+def _register_device(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    device_id, name, workspace, public_key, key_id = _device_body(body)
+    _require_workspace(principal, workspace)
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        record = register_device(
+            conn,
+            principal.tenant_id,
+            device_id=device_id,
+            name=name,
+            workspace_slug=workspace,
+            public_key=public_key,
+            key_id=key_id,
+        )
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "device_registered",
+            device_id,
+            details={"workspace": workspace},
+        )
+        return 201, _device_json(record)
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _list_devices(
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    records = list_devices(conn, principal.tenant_id)
+    visible = [
+        record
+        for record in records
+        if not principal.workspaces or record.workspace_slug in principal.workspaces
+    ]
+    return {"devices": [_device_json(record) for record in visible]}
+
+
+def _revoke_device(
+    device_id: str,
+    compromised: bool = False,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> Response:
+    rows = list_device_keys(conn, principal.tenant_id, device_id)
+    if not rows:
+        raise AgentevoError(
+            ErrorCode.NOT_FOUND, f"unknown device: {device_id}", {"device_id": device_id}
+        )
+    for row in rows:
+        _require_workspace(principal, row.workspace_slug)
+    revoked = revoke_device(conn, principal.tenant_id, device_id, compromised=compromised)
+    audit(
+        conn,
+        principal.tenant_id,
+        principal.token_id,
+        "device_revoked",
+        device_id,
+        details={"compromised": compromised, "keys": len(revoked)},
+    )
+    return Response(status_code=204)
+
+
+def _link_repo(  # noqa: PLR0913, PLR0917 - FastAPI handler signature
+    slug: str,
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    _require_workspace(principal, slug)
+    repository = body.get("repository")
+    if not isinstance(repository, str) or not repository:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "repository must be a non-empty string", {})
+    # Moving a link between workspaces needs visibility into both ends;
+    # a token scoped to the target alone cannot steal or strand the source.
+    for link in list_repos(conn, principal.tenant_id):
+        if link.repo == repository and link.workspace_slug != slug:
+            _require_workspace(principal, link.workspace_slug)
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        link = link_repo(conn, principal.tenant_id, repository, slug)
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "repo_linked",
+            repository,
+            details={"workspace": slug},
+        )
+        return 201, {"repository": link.repo, "workspace": link.workspace_slug}
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _list_repos(
+    slug: str,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    _require_workspace(principal, slug)
+    links = [link for link in list_repos(conn, principal.tenant_id) if link.workspace_slug == slug]
+    return {
+        "repos": [{"repository": link.repo, "workspace": link.workspace_slug} for link in links]
+    }
+
+
+def _unlink_repo(
+    slug: str,
+    repo: str,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> Response:
+    _require_workspace(principal, slug)
+    links = list_repos(conn, principal.tenant_id)
+    current = next((link.workspace_slug for link in links if link.repo == repo), None)
+    if current is not None and current != slug:
+        # Wrong-workspace path: 404 without revealing the true workspace.
+        raise AgentevoError(ErrorCode.NOT_FOUND, f"unknown repository link: {repo}", {})
+    unlink_repo(conn, principal.tenant_id, repo)
+    audit(
+        conn,
+        principal.tenant_id,
+        principal.token_id,
+        "repo_unlinked",
+        repo,
+        details={"workspace": slug},
+    )
+    return Response(status_code=204)
+
+
+def _create_webhook(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    settings: Settings = request.app.state.settings
+    url, events = _webhook_body(body)
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        issued = create_config(conn, settings, principal.tenant_id, url, events)
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "webhook_created",
+            issued.config.id,
+            details={"events": list(issued.config.events)},
+        )
+        payload = _webhook_json(issued.config)
+        payload["secret"] = issued.secret
+        return 201, payload
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _list_webhooks(
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    return {"webhooks": [_webhook_json(item) for item in list_configs(conn, principal.tenant_id)]}
+
+
+def _revoke_webhook(
+    config_id: str,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> Response:
+    revoke_config(conn, principal.tenant_id, config_id)
+    audit(
+        conn,
+        principal.tenant_id,
+        principal.token_id,
+        "webhook_revoked",
+        config_id,
+        details={},
+    )
+    return Response(status_code=204)
+
+
+def _rotate_webhook(  # noqa: PLR0913, PLR0917 - FastAPI handler signature
+    config_id: str,
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    settings: Settings = request.app.state.settings
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        issued = rotate_config(conn, settings, principal.tenant_id, config_id)
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "webhook_rotated",
+            config_id,
+            details={"key_id": issued.config.key_id},
+        )
+        return 200, {
+            "id": issued.config.id,
+            "key_id": issued.config.key_id,
+            "secret": issued.secret,
+        }
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _test_webhook(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    settings: Settings = request.app.state.settings
+    config_id = body.get("config_id")
+    if not isinstance(config_id, str) or not config_id:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "config_id must be a non-empty string", {})
+    config = get_config(conn, principal.tenant_id, config_id)
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        event = build_event(
+            "webhook.test",
+            principal.tenant_id,
+            config.id,
+            payload={"config_id": config.id, "key_id": config.key_id},
+        )
+        delivery = deliver_to_config(
+            conn,
+            settings,
+            principal.tenant_id,
+            config.id,
+            event,
+            sender=_webhook_sender(request),
+            timeout_seconds=settings.webhook_timeout_seconds,
+        )
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "webhook_tested",
+            config.id,
+            details={"status": delivery.status, "delivery_id": delivery.id},
+        )
+        return 200, {"status": delivery.status, "delivery": _delivery_json(delivery)}
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _webhook_deliveries(
+    config_id: str,
+    limit: int = 50,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    deliveries = list_deliveries(conn, principal.tenant_id, config_id, limit=limit)
+    return {"deliveries": [_delivery_json(item) for item in deliveries]}
+
+
+def _replay_webhook(  # noqa: PLR0913, PLR0917 - FastAPI handler signature
+    delivery_id: str,
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    settings: Settings = request.app.state.settings
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        delivery = replay_delivery(
+            conn,
+            settings,
+            principal.tenant_id,
+            delivery_id,
+            sender=_webhook_sender(request),
+            timeout_seconds=settings.webhook_timeout_seconds,
+        )
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "webhook_replayed",
+            delivery.id,
+            details={"event_id": delivery.event_id, "status": delivery.status},
+        )
+        return 200, {"delivery": _delivery_json(delivery)}
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _audit(
+    since_seq: int = 0,
+    limit: int = 100,
+    principal: Principal = Depends(AUDIT_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    entries = list_audit(conn, principal.tenant_id, since_seq=since_seq, limit=limit)
+    cursor = entries[-1].seq if entries else since_seq
+    return {
+        "entries": [
+            {
+                "seq": entry.seq,
+                "actor": entry.actor,
+                "action": entry.action,
+                "resource": entry.resource,
+                "details": entry.details,
+                "created_at": entry.created_at,
+            }
+            for entry in entries
+        ],
+        "next_cursor": cursor,
+    }
+
+
+def _require_workspace(principal: Principal, slug: str) -> None:
+    """Scoped tokens see only their workspaces (404, non-enumerating)."""
+    if principal.workspaces and slug not in principal.workspaces:
+        raise AgentevoError(ErrorCode.NOT_FOUND, f"unknown workspace: {slug}", {})
+
+
+def _require_admin(principal: Principal) -> None:
+    """BR-011: export/delete need an owner/admin membership (403 otherwise)."""
+    if principal.role not in (OWNER_ROLE, ADMIN_ROLE):
+        raise AgentevoError(
+            ErrorCode.FORBIDDEN,
+            "workspace export/delete requires an owner/admin role",
+            {},
+        )
+
+
+def _export_workspace(
+    slug: str,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    _require_workspace(principal, slug)
+    _require_admin(principal)
+    export = export_workspace_data(conn, principal.tenant_id, slug)
+    audit(
+        conn,
+        principal.tenant_id,
+        principal.token_id,
+        "workspace_data_exported",
+        slug,
+        details={
+            "deltas": len(export.deltas),
+            "devices": len(export.devices),
+            "repos": len(export.repos),
+        },
+    )
+    return {
+        "workspace": export.workspace,
+        "exported_at": export.exported_at,
+        "deltas": list(export.deltas),
+        "devices": list(export.devices),
+        "repos": list(export.repos),
+        "sync_mode": export.sync_mode.to_dict(),
+    }
+
+
+def _delete_workspace_data(
+    slug: str,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    _require_workspace(principal, slug)
+    _require_admin(principal)
+    deletion = delete_workspace_data(conn, principal.tenant_id, slug)
+    audit(
+        conn,
+        principal.tenant_id,
+        principal.token_id,
+        "workspace_data_deleted",
+        slug,
+        details={
+            "deltas": deletion.deltas,
+            "managed_objects": deletion.managed_objects,
+            "devices": deletion.devices,
+            "repos": deletion.repos,
+            "backup_expires_at": deletion.backup_expires_at,
+        },
+    )
+    return {
+        "workspace": deletion.workspace,
+        "deleted_at": deletion.deleted_at,
+        "backup_expires_at": deletion.backup_expires_at,
+        "deleted": {
+            "sync_deltas": deletion.deltas,
+            "managed_objects": deletion.managed_objects,
+            "devices": deletion.devices,
+            "repo_links": deletion.repos,
+        },
+    }
+
+
+def _get_sync_mode(
+    slug: str,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    _require_workspace(principal, slug)
+    return get_sync_mode(conn, principal.tenant_id, slug).to_dict()
+
+
+def _set_sync_mode(
+    slug: str,
+    body: dict[str, Any],
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    _require_workspace(principal, slug)
+    _require_admin(principal)
+    mode = _body_mode(body)
+    terms = _body_optional_str(body, "terms_version")
+    expected = _body_optional_str(body, "expected_mode")
+    previous = get_sync_mode(conn, principal.tenant_id, slug)
+    consent = set_sync_mode(
+        conn,
+        principal.tenant_id,
+        slug,
+        mode=mode,
+        actor=principal.user_id or principal.token_id,
+        terms_version=terms,
+        expected_mode=expected,
+    )
+    audit(
+        conn,
+        principal.tenant_id,
+        principal.user_id or principal.token_id,
+        "sync_mode_changed",
+        f"workspaces/{slug}/sync-mode",
+        details={
+            "from": previous.sync_mode,
+            "to": consent.sync_mode,
+            "terms_version": consent.terms_version,
+        },
+    )
+    return consent.to_dict()
+
+
+def _analytics_summary(
+    workspace: str | None = None,
+    principal: Principal = Depends(CONTROL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    if workspace is not None:
+        _require_workspace(principal, workspace)
+    return summarize(
+        conn, principal.tenant_id, workspace=workspace, workspaces=principal.workspaces
+    ).to_dict()
+
+
+def _body_mode(body: dict[str, Any]) -> str:
+    """Required sync mode from a mode-change body (400 on anything else)."""
+    raw: Any = body.get("sync_mode", "")
+    if not isinstance(raw, str) or not raw:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "sync_mode must be a non-empty string", {})
+    return raw
+
+
+def _body_optional_str(body: dict[str, Any], field: str) -> str | None:
+    """Optional string field from a route body (400 when mistyped)."""
+    raw: Any = body.get(field)
+    if raw is None:
+        return None
+    if not isinstance(raw, str):
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, f"{field} must be a string", {})
+    return raw
+
+
+def _sync_push(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(SYNC_WRITE),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    envelopes: Any = body.get("envelopes")
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        receipt = push_batch(conn, principal, envelopes, now=datetime.now(UTC))
+        indexed = index_accepted(conn, principal.tenant_id, receipt.accepted)
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "sync_push",
+            "sync/push",
+            details={
+                "accepted": [f"{item.object_id}:v{item.version}" for item in receipt.accepted],
+                "duplicates": list(receipt.duplicates),
+                "indexed": indexed,
+            },
+        )
+        return 200, receipt.to_dict()
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _sync_pull(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(SYNC_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    cursor = body.get("cursor", "")
+    limit = body.get("limit", 100)
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        page = pull_page(conn, principal, cursor, limit, tombstones_only=False)
+        return 200, page.to_dict()
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _revocations(
+    after: str = "",
+    limit: int = 100,
+    principal: Principal = Depends(SYNC_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    page = pull_page(conn, principal, after, limit, tombstones_only=True)
+    return page.to_dict()
+
+
+def _events_batch(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(SYNC_WRITE),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    events: Any = body.get("events")
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        receipt = ingest_batch(conn, principal.tenant_id, events)
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "events_ingested",
+            "events/batch",
+            details={
+                "accepted": len(receipt.accepted),
+                "duplicates": len(receipt.duplicates),
+            },
+        )
+        return 201, {
+            "accepted": list(receipt.accepted),
+            "duplicates": list(receipt.duplicates),
+        }
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _recall(
+    body: dict[str, Any],
+    principal: Principal = Depends(RECALL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    query = parse_query(body)
+    result = recall(conn, principal.tenant_id, query, workspaces=principal.workspaces)
+    return {
+        "objects": [
+            {
+                "object_id": hit.object_id,
+                "version": hit.version,
+                "object_type": hit.object_type,
+                "state": hit.state,
+                "advisory": hit.advisory,
+                "score": hit.score,
+                "reason": hit.reason,
+                "confidence": hit.confidence,
+                "risk_class": hit.risk_class,
+                "environment_match": hit.environment_match,
+                "freshness": hit.freshness,
+                "body": hit.body,
+            }
+            for hit in result.objects
+        ],
+        "budgets": {
+            "returned": len(result.objects),
+            "max_objects": result.max_objects,
+            "tokens_used": result.tokens_used,
+            "max_tokens": result.max_tokens,
+        },
+    }
+
+
+#: Submit/poll/cancel scope per job kind (one scope owns a job's lifecycle).
+#: Compile is producer work (derived C2 objects), so the sync:write scope
+#: that pushes source evidence also submits and polls compile jobs.
+_JOB_TYPE_SCOPES = {
+    JobType.VERIFY.value: "verify:run",
+    JobType.COMPILE_EXPERIENCES.value: "sync:write",
+    JobType.COMPILE_WORKFLOW.value: "sync:write",
+}
+
+#: Any scope that participates in async work (listing spans job kinds).
+_JOB_SCOPES = frozenset(_JOB_TYPE_SCOPES.values())
+
+#: List filter vocabulary (unknown states 400 instead of silently matching nothing).
+_JOB_STATES = frozenset(state.value for state in JobState)
+
+
+def _require_job_scope(principal: Principal, job_type: str) -> None:
+    """Enforce the lifecycle scope of one job kind (400 on unknown kinds)."""
+    scope = _JOB_TYPE_SCOPES.get(job_type)
+    if scope is None:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, f"unknown job type: {job_type}", {"job_type": job_type}
+        )
+    if not principal.allows(scope):
+        raise AgentevoError(
+            ErrorCode.FORBIDDEN,
+            f"token lacks required scope: {scope}",
+            {"scope": scope},
+        )
+
+
+#: States carrying prior standing (revalidation re-confirms; it never validates fresh work).
+_REVALIDATABLE_STATES = frozenset(
+    {
+        TrustState.VERIFIED.value,
+        TrustState.TRUSTED.value,
+        TrustState.STALE.value,
+        TrustState.COMPILED.value,
+    }
+)
+
+
+def _body_version(body: dict[str, Any], field: str = "version") -> int:
+    """Required exact version from an object-route body (400 on anything else)."""
+    version: Any = body.get(field)
+    if isinstance(version, bool) or not isinstance(version, int):
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, f"{field} must be an integer", {})
+    return version
+
+
+def _body_target(body: dict[str, Any]) -> TrustState:
+    """Required promotion target from a promote body (400 on anything else)."""
+    raw: Any = body.get("target", "")
+    if not isinstance(raw, str):
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "target must be a string", {})
+    try:
+        return TrustState(raw)
+    except ValueError as exc:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, f"unknown promotion target: {raw}", {"target": raw}
+        ) from exc
+
+
+def _managed_or_404(
+    conn: sqlite3.Connection, tenant_id: str, object_id: str, version: int
+) -> ManagedObject:
+    """One indexed version, tenant-scoped (404 reveals nothing across tenants)."""
+    target = get_managed(conn, tenant_id, object_id, version)
+    if target is None:
+        raise AgentevoError(
+            ErrorCode.NOT_FOUND,
+            "unknown object version",
+            {"object_id": object_id, "version": version},
+        )
+    return target
+
+
+def _verify_object(  # noqa: PLR0913, PLR0917 - handler carries route context
+    object_id: str,
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(VERIFY_RUN),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    version = _body_version(body)
+    environment = body.get("environment")
+    parse_environment(environment)
+    _managed_or_404(conn, principal.tenant_id, object_id, version)
+    params = {} if environment is None else {"environment": environment}
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        job = create_job(
+            conn,
+            principal.tenant_id,
+            JobType.VERIFY.value,
+            object_id=object_id,
+            version=version,
+            params=params,
+        )
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "job_submitted",
+            f"jobs/{job.job_id}",
+            details={"job_type": JobType.VERIFY.value},
+        )
+        return 202, job.to_dict()
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _revalidate_object(  # noqa: PLR0913, PLR0917 - handler carries route context
+    object_id: str,
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(VERIFY_RUN),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    version = _body_version(body)
+    environment = body.get("environment")
+    parse_environment(environment)
+    target = _managed_or_404(conn, principal.tenant_id, object_id, version)
+    if target.state not in _REVALIDATABLE_STATES:
+        raise AgentevoError(
+            ErrorCode.CONFLICT,
+            f"object has no standing to revalidate: {target.state}",
+            {"object_id": object_id, "version": version, "state": target.state},
+        )
+    params: dict[str, Any] = {"revalidation": True}
+    if environment is not None:
+        params["environment"] = environment
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        job = create_job(
+            conn,
+            principal.tenant_id,
+            JobType.VERIFY.value,
+            object_id=object_id,
+            version=version,
+            params=params,
+        )
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "revalidation_scheduled",
+            f"jobs/{job.job_id}",
+            details={"object_id": object_id, "version": version},
+        )
+        return 202, job.to_dict()
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _get_object_version(
+    object_id: str,
+    version: int,
+    principal: Principal = Depends(RECALL_READ),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    return _managed_or_404(conn, principal.tenant_id, object_id, version).to_dict()
+
+
+def _body_reason(body: dict[str, Any]) -> RevocationReason:
+    """Closed C1 reason code (400 on anything else; admin-revoke by default)."""
+    raw: Any = body.get("reason", RevocationReason.ADMIN_REVOKE.value)
+    if not isinstance(raw, str):
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "reason must be a string", {})
+    try:
+        return RevocationReason(raw)
+    except ValueError as exc:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, f"unknown revocation reason: {raw}", {"reason": raw}
+        ) from exc
+
+
+def _revoke_object(  # noqa: PLR0913, PLR0917 - handler carries route context
+    object_id: str,
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(OBJECT_REVOKE),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    reason = _body_reason(body)
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        result = revoke_object(conn, principal, object_id, reason=reason)
+        return 200, result.to_dict()
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _compile_experiences(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(SYNC_WRITE),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    session_id = parse_required_str(body.get("session_id"), "session_id")
+    workspace_id = parse_required_str(body.get("workspace_id"), "workspace_id")
+    project_id = parse_required_str(body.get("project_id", DEFAULT_COMPILE_PROJECT), "project_id")
+    ensure_workspace(conn, principal.tenant_id, workspace_id)
+    require_searchable(conn, principal.tenant_id, workspace_id, "compile managed experiences")
+    params = {"session_id": session_id, "workspace_id": workspace_id, "project_id": project_id}
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        job = create_job(
+            conn, principal.tenant_id, JobType.COMPILE_EXPERIENCES.value, params=params
+        )
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "job_submitted",
+            f"jobs/{job.job_id}",
+            details={"job_type": JobType.COMPILE_EXPERIENCES.value},
+        )
+        return 202, job.to_dict()
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _compile_workflows(
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(SYNC_WRITE),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    refs = parse_skill_refs(body.get("skills"))
+    parse_bindings(body.get("bindings"))
+    parse_rollback(body.get("rollback", []))
+    parse_fallbacks(body.get("fallbacks", {}))
+    canary = parse_canary_steps(body.get("canary_steps", 1))
+    rows = [
+        _compile_skill_row(conn, principal.tenant_id, object_id, version)
+        for object_id, version in refs
+    ]
+    if len({row.workspace_id for row in rows}) > 1:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT,
+            "cross-workspace compile rejected",
+            {"workspaces": sorted({row.workspace_id for row in rows})},
+        )
+    require_searchable(conn, principal.tenant_id, rows[0].workspace_id, "compile managed workflows")
+    params: dict[str, Any] = {
+        "skills": [{"object_id": row.object_id, "version": row.version} for row in rows],
+        "bindings": body.get("bindings"),
+        "rollback": body.get("rollback", []),
+        "fallbacks": body.get("fallbacks", {}),
+        "canary_steps": canary,
+    }
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        job = create_job(conn, principal.tenant_id, JobType.COMPILE_WORKFLOW.value, params=params)
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "job_submitted",
+            f"jobs/{job.job_id}",
+            details={"job_type": JobType.COMPILE_WORKFLOW.value},
+        )
+        return 202, job.to_dict()
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _compile_skill_row(
+    conn: sqlite3.Connection, tenant_id: str, object_id: str, version: int
+) -> ManagedObject:
+    """One referenced skill (404 unknown; 409 unless SKILL plus Trusted)."""
+    row = get_managed(conn, tenant_id, object_id, version)
+    if row is None:
+        raise AgentevoError(
+            ErrorCode.NOT_FOUND,
+            "unknown object version",
+            {"object_id": object_id, "version": version},
+        )
+    if row.object_type != LearnedObjectType.SKILL.value:
+        raise AgentevoError(
+            ErrorCode.CONFLICT,
+            f"only skills compile: {object_id}",
+            {"object_id": object_id, "object_type": row.object_type},
+        )
+    if row.state != TrustState.TRUSTED.value:
+        raise AgentevoError(
+            ErrorCode.CONFLICT,
+            f"only Trusted skills compile: {row.state}",
+            {"object_id": object_id, "state": row.state},
+        )
+    return row
+
+
+def _promote_object(  # noqa: PLR0913, PLR0917 - handler carries route context
+    object_id: str,
+    body: dict[str, Any],
+    request: Request,
+    principal: Principal = Depends(OBJECT_PROMOTE),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    version = _body_version(body, "expected_version")
+    target = _body_target(body)
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        try:
+            promoted = promote_managed(conn, principal, object_id, version, target)
+        except AgentevoError as exc:
+            if exc.code is ErrorCode.FORBIDDEN:
+                # Denials roll the request transaction back (failed attempts
+                # never bill), so release it now and commit the denial audit
+                # out-of-band on a fresh connection.
+                conn.rollback()
+                database: Database = request.app.state.db
+                with database.connect() as audit_conn:
+                    audit(
+                        audit_conn,
+                        principal.tenant_id,
+                        principal.user_id or principal.token_id,
+                        "promotion_denied",
+                        f"objects/{object_id}/versions/{version}",
+                        details={
+                            "target": target.value,
+                            "reason": exc.details.get("reason", ""),
+                        },
+                    )
+            raise
+        return 200, promoted.to_dict()
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, body, compute)
+
+
+def _get_job(
+    job_id: str,
+    principal: Principal = Depends(metered),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    job = get_job(conn, principal.tenant_id, job_id)
+    if job is None:
+        raise AgentevoError(ErrorCode.NOT_FOUND, "unknown job", {"job_id": job_id})
+    _require_job_scope(principal, job.job_type)
+    return job.to_dict()
+
+
+def _list_jobs(
+    state: str | None = None,
+    limit: int = 50,
+    principal: Principal = Depends(metered),
+    conn: sqlite3.Connection = Depends(get_conn),
+) -> dict[str, Any]:
+    if not (principal.scopes & _JOB_SCOPES):
+        raise AgentevoError(
+            ErrorCode.FORBIDDEN,
+            "token lacks a job scope",
+            {"scopes": sorted(_JOB_SCOPES)},
+        )
+    if state is not None and state not in _JOB_STATES:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, f"unknown job state: {state}", {"state": state}
+        )
+    jobs = list_jobs(conn, principal.tenant_id, state=state, limit=limit)
+    return {"jobs": [job.to_dict() for job in jobs]}
+
+
+def _cancel_job(
+    job_id: str,
+    request: Request,
+    principal: Principal = Depends(metered),
+    conn: sqlite3.Connection = Depends(get_conn),
+    idempotency_key: str | None = Header(default=None),
+) -> JSONResponse:
+    job = get_job(conn, principal.tenant_id, job_id)
+    if job is None:
+        raise AgentevoError(ErrorCode.NOT_FOUND, "unknown job", {"job_id": job_id})
+    _require_job_scope(principal, job.job_type)
+
+    def compute() -> tuple[int, dict[str, Any]]:
+        canceled = cancel_job(conn, principal.tenant_id, job_id)
+        if canceled is None:  # pragma: no cover - rows are never deleted; pre-checked above
+            raise AgentevoError(ErrorCode.NOT_FOUND, "unknown job", {"job_id": job_id})
+        audit(
+            conn,
+            principal.tenant_id,
+            principal.token_id,
+            "job_canceled",
+            f"jobs/{job_id}",
+            details={"state": canceled.state},
+        )
+        return 200, canceled.to_dict()
+
+    return _idempotent(request, conn, principal.tenant_id, idempotency_key, {}, compute)
+
+
+#: Error-detail strings are truncated here so a hostile input is never echoed
+#: back unbounded (and a non-serializable input never 500s the handler).
+_ERROR_DETAIL_CHARS = 1024
+
+
+def _truncate_detail(text: str) -> str:
+    """Cap one detail string (no-op for short text)."""
+    if len(text) > _ERROR_DETAIL_CHARS:
+        return text[:_ERROR_DETAIL_CHARS] + "…(truncated)"
+    return text
+
+
+def _jsonable_detail(value: Any) -> Any:
+    """Render one error-detail value JSON-safe (validation inputs are hostile)."""
+    if isinstance(value, dict):
+        rendered: Any = {str(key): _jsonable_detail(item) for key, item in value.items()}
+    elif isinstance(value, (list, tuple)):
+        rendered = [_jsonable_detail(item) for item in value]
+    elif isinstance(value, bytes):
+        try:
+            rendered = _truncate_detail(value.decode("utf-8"))
+        except UnicodeDecodeError:
+            rendered = _truncate_detail(repr(value))
+    elif isinstance(value, str):
+        rendered = _truncate_detail(value)
+    elif value is None or isinstance(value, (bool, int, float)):
+        rendered = value
+    else:
+        rendered = _truncate_detail(str(value))
+    return rendered
+
+
+def _error_response(
+    code: ErrorCode, message: str, details: dict[str, Any], exc: AgentevoError | None
+) -> JSONResponse:
+    request_id = uuid4().hex[:16]
+    headers = {REQUEST_ID_HEADER: request_id}
+    if exc is not None:
+        retry_after = retry_after_for(exc)
+        if retry_after is not None:
+            headers[RETRY_AFTER_HEADER] = str(retry_after)
+    safe = {key: _jsonable_detail(value) for key, value in details.items()}
+    return JSONResponse(
+        status_code=HTTP_STATUS[code],
+        content={"code": code.value, "message": message, "details": safe},
+        headers=headers,
+    )
+
+
+def _bearer_secret(authorization: str | None) -> str:
+    if authorization is None:
+        raise AgentevoError(ErrorCode.UNAUTHENTICATED, "missing credentials", {})
+    scheme, _, secret = authorization.partition(" ")
+    if scheme.lower() != "bearer" or not secret:
+        raise AgentevoError(ErrorCode.UNAUTHENTICATED, "malformed credentials", {})
+    return secret
+
+
+def _token_body(body: dict[str, Any]) -> tuple[str, list[str], list[str], timedelta]:
+    name = body.get("name")
+    scopes = body.get("scopes")
+    workspaces = body.get("workspaces", [])
+    ttl_seconds = body.get("ttl_seconds", 90 * 24 * 3600)
+    if not isinstance(name, str) or not name:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "name must be non-empty", {})
+    if (
+        not isinstance(scopes, list)
+        or not scopes
+        or any(not isinstance(item, str) for item in scopes)
+    ):
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, "scopes must be a non-empty string list", {}
+        )
+    if not isinstance(workspaces, list) or any(not isinstance(item, str) for item in workspaces):
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "workspaces must be a string list", {})
+    if isinstance(ttl_seconds, bool) or not isinstance(ttl_seconds, int) or ttl_seconds <= 0:
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, "ttl_seconds must be a positive integer", {}
+        )
+    return name, scopes, workspaces, timedelta(seconds=ttl_seconds)
+
+
+def _device_code_body(body: dict[str, Any]) -> tuple[list[str], str | None]:
+    scopes = body.get("scopes")
+    workspace = body.get("workspace")
+    if (
+        not isinstance(scopes, list)
+        or not scopes
+        or any(not isinstance(item, str) for item in scopes)
+    ):
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, "scopes must be a non-empty string list", {}
+        )
+    if workspace is not None and (not isinstance(workspace, str) or not workspace):
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "workspace must be a non-empty string", {})
+    return scopes, workspace
+
+
+def _decision_body(body: dict[str, Any]) -> tuple[str, str | None]:
+    user_code = body.get("user_code")
+    id_token = body.get("id_token")
+    if not isinstance(user_code, str) or not user_code:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "user_code must be a non-empty string", {})
+    if id_token is not None and (not isinstance(id_token, str) or not id_token):
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "id_token must be a non-empty string", {})
+    return user_code, id_token
+
+
+def _device_body(body: dict[str, Any]) -> tuple[str, str, str, str, str | None]:
+    device_id = body.get("device_id")
+    name = body.get("name")
+    workspace = body.get("workspace")
+    public_key = body.get("public_key")
+    key_id = body.get("key_id")
+    if not isinstance(device_id, str) or not device_id:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "device_id must be a non-empty string", {})
+    if not isinstance(name, str) or not name:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "name must be a non-empty string", {})
+    if not isinstance(workspace, str) or not workspace:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "workspace must be a non-empty string", {})
+    if not isinstance(public_key, str) or not public_key:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "public_key must be a non-empty string", {})
+    if key_id is not None and (not isinstance(key_id, str) or not key_id):
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "key_id must be a non-empty string", {})
+    return device_id, name, workspace, public_key, key_id
+
+
+def _webhook_body(body: dict[str, Any]) -> tuple[str, list[str]]:
+    url = body.get("url")
+    events = body.get("events")
+    if not isinstance(url, str) or not url:
+        raise AgentevoError(ErrorCode.INVALID_ARGUMENT, "url must be a non-empty string", {})
+    if (
+        not isinstance(events, list)
+        or not events
+        or any(not isinstance(item, str) for item in events)
+    ):
+        raise AgentevoError(
+            ErrorCode.INVALID_ARGUMENT, "events must be a non-empty string list", {}
+        )
+    return url, events
+
+
+def _device_json(record: DeviceRecord) -> dict[str, Any]:
+    return {
+        "key_id": record.key_id,
+        "device_id": record.device_id,
+        "name": record.name,
+        "workspace": record.workspace_slug,
+        "public_key": record.public_key,
+        "key_format": record.key_format,
+        "first_seen": record.first_seen,
+        "revoked_at": record.revoked_at,
+        "compromised": record.compromised,
+    }
+
+
+def _webhook_json(config: WebhookConfig) -> dict[str, Any]:
+    return {
+        "id": config.id,
+        "url": config.url,
+        "key_id": config.key_id,
+        "events": list(config.events),
+        "created_at": config.created_at,
+        "revoked_at": config.revoked_at,
+    }
+
+
+def _delivery_json(delivery: Delivery) -> dict[str, Any]:
+    return {
+        "id": delivery.id,
+        "config_id": delivery.config_id,
+        "event_id": delivery.event_id,
+        "event_type": delivery.event_type,
+        "event": delivery.event,
+        "status": delivery.status,
+        "attempts": delivery.attempts,
+        "http_status": delivery.http_status,
+        "last_error": delivery.last_error,
+        "created_at": delivery.created_at,
+    }