google-cloud-support-mcp 0.1.0__py3-none-any.whl

google_cloud_support_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""MCP server for Google Cloud Support."""
+
+from __future__ import annotations
+
+__all__ = ["main"]
+
+
+def main() -> None:
+    from .server import create_server
+
+    create_server().run()

google_cloud_support_mcp/__main__.py

@@ -0,0 +1,4 @@
+from google_cloud_support_mcp import main
+
+if __name__ == "__main__":
+    main()

google_cloud_support_mcp/auth.py

@@ -0,0 +1,61 @@
+"""Credentials, used exactly as the user already configured them.
+
+The server stores nothing (FR-020): ADC covers `gcloud auth
+application-default login`, service account keys, Workload Identity, and the
+metadata server without any of them being handled here.
+
+Two consumers share one credential object, and they refresh independently — the
+gRPC channel manages its own lifecycle while the media REST path needs a bearer
+token minted on demand. That split is the second-order consequence of the SDK
+not generating the media endpoints.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import google.auth
+from google.auth.transport.requests import Request as AuthRequest
+
+__all__ = ["SCOPES", "CredentialProvider"]
+
+SCOPES = ("https://www.googleapis.com/auth/cloud-platform",)
+
+
+class CredentialProvider:
+    """Resolves ADC once and mints bearer tokens for the media REST calls."""
+
+    def __init__(self, quota_project: str | None = None) -> None:
+        self._quota_project = quota_project
+        self._credentials = None
+        self._lock = asyncio.Lock()
+
+    @property
+    def quota_project(self) -> str | None:
+        return self._quota_project
+
+    def resolve(self):
+        """Return the ADC credentials, resolving them on first use."""
+        if self._credentials is None:
+            credentials, _ = google.auth.default(scopes=list(SCOPES))
+            if self._quota_project and hasattr(credentials, "with_quota_project"):
+                credentials = credentials.with_quota_project(self._quota_project)
+            self._credentials = credentials
+        return self._credentials
+
+    async def bearer_headers(self) -> dict[str, str]:
+        """Headers for the media endpoints, refreshing the token when stale.
+
+        google-auth's refresh is blocking, so it runs off the event loop. The lock
+        keeps concurrent uploads from refreshing the same credential at once.
+        """
+        async with self._lock:
+            credentials = self.resolve()
+            if not credentials.valid:
+                await asyncio.to_thread(credentials.refresh, AuthRequest())
+            token = credentials.token
+
+        headers = {"Authorization": f"Bearer {token}"}
+        if self._quota_project:
+            headers["x-goog-user-project"] = self._quota_project
+        return headers

google_cloud_support_mcp/clients.py

@@ -0,0 +1,48 @@
+"""The three GAPIC async clients plus one HTTP client, owned by the server lifespan.
+
+Three, not four: SupportEventSubscriptionService is out of scope. And an HTTP
+client alongside them because attachment upload and download are HTTP media
+endpoints that the GAPIC generator does not cover (research.md R-002).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+from google.cloud.support_v2.services.case_attachment_service import (
+    CaseAttachmentServiceAsyncClient,
+)
+from google.cloud.support_v2.services.case_service import CaseServiceAsyncClient
+from google.cloud.support_v2.services.comment_service import CommentServiceAsyncClient
+
+from .auth import CredentialProvider
+
+__all__ = ["SupportClients", "build_clients"]
+
+SUPPORT_API_ROOT = "https://cloudsupport.googleapis.com"
+
+
+@dataclass(slots=True)
+class SupportClients:
+    """One bundle constructed per server process, never per call."""
+
+    cases: CaseServiceAsyncClient
+    comments: CommentServiceAsyncClient
+    attachments: CaseAttachmentServiceAsyncClient
+    http: httpx.AsyncClient
+    credentials: CredentialProvider
+
+    async def aclose(self) -> None:
+        await self.http.aclose()
+
+
+def build_clients(credentials: CredentialProvider) -> SupportClients:
+    creds = credentials.resolve()
+    return SupportClients(
+        cases=CaseServiceAsyncClient(credentials=creds),
+        comments=CommentServiceAsyncClient(credentials=creds),
+        attachments=CaseAttachmentServiceAsyncClient(credentials=creds),
+        http=httpx.AsyncClient(base_url=SUPPORT_API_ROOT, timeout=60.0),
+        credentials=credentials,
+    )

google_cloud_support_mcp/confirm.py

@@ -0,0 +1,158 @@
+"""User confirmation for anything that leaves this machine (FR-016, FR-017).
+
+FastMCP 4 removed `ctx.elicit()` on modern connections and rejects
+`InputRequiredResult` on handshake-era ones, so branching on the negotiated
+protocol version is required, not optional.
+
+The design point worth keeping: round one seals the *entire outgoing payload*
+into `request_state`, and round two executes that payload verbatim instead of
+rebuilding it. The framework signs and verifies that token, so "what the user
+approved is what gets sent" is enforced by the framework rather than by
+convention. A `confirm: bool` parameter cannot do this — the model fills that in,
+not the user.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from fastmcp import Context
+from fastmcp.exceptions import ToolError
+from fastmcp.server.context import MODERN_PROTOCOL_VERSIONS
+from mcp.types import ElicitRequest, ElicitRequestFormParams, InputRequiredResult
+
+__all__ = ["NO_ELICITATION_MESSAGE", "ConfirmationOutcome", "request_confirmation"]
+
+_KEY = "confirm"
+_FIELD = "approve"
+
+NO_ELICITATION_MESSAGE = (
+    "This action needs your explicit confirmation before anything is sent to Google "
+    "Support, but this client cannot prompt you (no elicitation support). Nothing was "
+    "changed. Use a client that supports elicitation, or perform this action in the "
+    "Cloud Console."
+)
+
+DECLINED_MESSAGE = "Cancelled — nothing was sent to Google Support and no change was made."
+
+
+@dataclass(slots=True)
+class ConfirmationOutcome:
+    """Either 'ask the user' (return `input_required`) or 'go ahead' (use `payload`)."""
+
+    input_required: InputRequiredResult | None = None
+    payload: dict[str, Any] | None = None
+
+    @property
+    def needs_input(self) -> bool:
+        return self.input_required is not None
+
+
+def _seal(tool: str, preview: str, payload: dict[str, Any]) -> str:
+    return json.dumps(
+        {
+            "tool": tool,
+            "payload": payload,
+            "preview": preview,
+            "issued_at": datetime.now(UTC).isoformat(),
+        },
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def _unseal(tool: str, raw: str | None) -> dict[str, Any]:
+    if not raw:
+        raise ToolError(
+            "The confirmation token was lost between rounds. Nothing was sent. Retry the action."
+        )
+    try:
+        state = json.loads(raw)
+    except ValueError as exc:
+        raise ToolError("The confirmation token is unreadable. Nothing was sent.") from exc
+
+    # A token issued for one tool must not be redeemable by another.
+    if state.get("tool") != tool:
+        raise ToolError(
+            f"The confirmation token was issued for '{state.get('tool')}', not '{tool}'. "
+            "Nothing was sent."
+        )
+    payload = state.get("payload")
+    if not isinstance(payload, dict):
+        raise ToolError("The confirmation token carries no payload. Nothing was sent.")
+    return payload
+
+
+def _ask(preview: str, request_state: str) -> InputRequiredResult:
+    params = ElicitRequestFormParams(
+        message=preview,
+        requested_schema={
+            "type": "object",
+            "properties": {
+                _FIELD: {
+                    "type": "boolean",
+                    "description": "Send this to Google Support?",
+                }
+            },
+            "required": [_FIELD],
+        },
+    )
+    return InputRequiredResult(
+        result_type="input_required",
+        input_requests={_KEY: ElicitRequest(method="elicitation/create", params=params)},
+        request_state=request_state,
+    )
+
+
+def _is_modern(ctx: Context) -> bool:
+    request_context = ctx.request_context
+    if request_context is None:
+        return False
+    return getattr(request_context, "protocol_version", None) in MODERN_PROTOCOL_VERSIONS
+
+
+async def request_confirmation(
+    ctx: Context,
+    *,
+    tool: str,
+    preview: str,
+    payload: dict[str, Any],
+) -> ConfirmationOutcome:
+    """Obtain the user's own approval before an outward-facing action.
+
+    `preview` is what the user reads; `payload` is exactly what will be sent.
+    Returning an outcome with `needs_input` means the caller should return
+    `outcome.input_required` unchanged and wait for the next round.
+    """
+    if _is_modern(ctx):
+        responses = ctx.input_responses
+        if not responses or _KEY not in responses:
+            # Round one: ask, and carry the payload forward sealed.
+            return ConfirmationOutcome(input_required=_ask(preview, _seal(tool, preview, payload)))
+
+        answer = responses[_KEY]
+        # Check the action before touching content — a client may decline or cancel.
+        if getattr(answer, "action", None) != "accept":
+            raise ToolError(DECLINED_MESSAGE)
+        content = getattr(answer, "content", None) or {}
+        if content.get(_FIELD) is not True:
+            raise ToolError(DECLINED_MESSAGE)
+
+        return ConfirmationOutcome(payload=_unseal(tool, ctx.request_state))
+
+    # Handshake era (<= 2025-11-25): the blocking back-channel still exists.
+    try:
+        result = await ctx.elicit(preview, response_type=bool)
+    except ToolError:
+        raise
+    except Exception as exc:
+        # No elicitation capability on this client. That is FR-019's shape exactly:
+        # change nothing, and say why it could not run.
+        raise ToolError(NO_ELICITATION_MESSAGE) from exc
+
+    if getattr(result, "action", None) != "accept" or getattr(result, "data", None) is not True:
+        raise ToolError(DECLINED_MESSAGE)
+    return ConfirmationOutcome(payload=payload)

google_cloud_support_mcp/errors.py

@@ -0,0 +1,233 @@
+"""Normalise failures from both transports into one vocabulary.
+
+The server talks to the same Google service over two protocols — gRPC for the
+thirteen GAPIC RPCs and HTTP for the two media endpoints that the SDK does not
+generate. That means two exception families, and a user must not receive a
+different shape of guidance depending on which one they happened to hit.
+
+Every mapping goes through `_info`, so the guidance text for a given kind is
+identical on both paths by construction rather than by convention.
+"""
+
+from __future__ import annotations
+
+import httpx
+from fastmcp.exceptions import ToolError
+from google.api_core import exceptions as gexc
+from pydantic import BaseModel
+
+from .models import ErrorKind
+
+__all__ = ["ErrorInfo", "ErrorKind", "custom", "from_grpc", "from_http", "to_tool_error"]
+
+
+class ErrorInfo(BaseModel):
+    kind: ErrorKind
+    detail: str
+    retryable: bool
+
+
+# Guidance is written as the user's *next step*, never as a restatement of the
+# failure. `UNKNOWN` carries real guidance too: FR-021 and SC-006 are all-inclusive,
+# so an empty or passthrough message there is a miss, not a default.
+_GUIDANCE: dict[ErrorKind, tuple[str, bool]] = {
+    ErrorKind.PERMISSION_DENIED: (
+        "Access denied. Grant roles/cloudsupport.techSupportViewer (read) or "
+        "techSupportEditor (write) on this project, folder, or organization. "
+        "Organization-level scopes additionally need resourcemanager.organizations.get. "
+        "If the roles are already granted, verify the resource is covered by a paid support plan.",
+        False,
+    ),
+    ErrorKind.API_NOT_ENABLED: (
+        "The Cloud Support API is not enabled on this project. Run "
+        "'gcloud services enable cloudsupport.googleapis.com --project=PROJECT_ID' "
+        "(use the quota project when the target is an organization), then wait a "
+        "minute for it to propagate and retry. This is not a permissions problem.",
+        False,
+    ),
+    ErrorKind.SUPPORT_PLAN_REQUIRED: (
+        "This resource is not eligible to use the Cloud Support API — it has no paid "
+        "support plan. Standard, Enhanced, or Premium Support is required. Attach a "
+        "support plan to this project or organization (or use a project that already "
+        "has one), then retry. Reading may work where creating does not, so this can "
+        "appear only when you try to open a case.",
+        False,
+    ),
+    ErrorKind.UNAUTHENTICATED: (
+        "No usable credentials. Run 'gcloud auth application-default login', or set "
+        "GOOGLE_APPLICATION_CREDENTIALS to a service account key. If you already did, "
+        "the credentials may have expired — re-run the login.",
+        False,
+    ),
+    ErrorKind.NOT_FOUND: (
+        "No such resource. Check the name format: cases are "
+        "'projects/{project}/cases/{id}' or 'organizations/{org}/cases/{id}'. "
+        "Also confirm the case lives under a parent you configured in "
+        "GOOGLE_CLOUD_SUPPORT_MCP_PARENTS.",
+        False,
+    ),
+    ErrorKind.INVALID_ARGUMENT: (
+        "The request was rejected as malformed. Check required fields and value "
+        "formats — classification ids come from search_case_classifications, and "
+        "timestamps must be ISO-8601.",
+        False,
+    ),
+    ErrorKind.FAILED_PRECONDITION: (
+        "The resource is not in a state that allows this operation — for example, "
+        "closing or escalating a case that is already closed. Fetch the case with "
+        "get_case to see its current state.",
+        False,
+    ),
+    ErrorKind.RATE_LIMITED: (
+        "Google is rate limiting these requests. Wait a few seconds and retry. If it "
+        "persists, lower GOOGLE_CLOUD_SUPPORT_MCP_FANOUT_CONCURRENCY so fewer scopes are "
+        "queried at once.",
+        True,
+    ),
+    ErrorKind.UNAVAILABLE: (
+        "The Cloud Support API is temporarily unreachable or the request timed out. "
+        "This is retryable — try again shortly.",
+        True,
+    ),
+    ErrorKind.UNKNOWN: (
+        "The request failed for a reason this server does not recognise. Retry once; "
+        "if it repeats, verify credentials with 'gcloud auth application-default login' "
+        "and confirm the Cloud Support API is enabled on the quota project "
+        "('gcloud services enable cloudsupport.googleapis.com').",
+        False,
+    ),
+}
+
+# Substrings that mean the blocker is the support contract rather than IAM or state.
+#
+# "not eligible ... with this channel" was observed verbatim from a live 400 on
+# 2026-09-01 when creating a case on a project without a paid plan. Note the
+# status: the plan blocker arrives as FailedPrecondition(400), *not* the 403 the
+# design assumed. Without this branch the user is told their case is "already
+# closed", which is nonsense for a create.
+_PLAN_SIGNATURES = (
+    "support plan",
+    "support account",
+    "not entitled",
+    "no entitlement",
+    "not eligible",
+    "with this channel",
+)
+
+# ...and when the API itself was never turned on. Observed verbatim from a live
+# 403: "Google Cloud Support API has not been used in project X before or it is
+# disabled." That reads as a permissions failure and is not one, so it is checked
+# first — the fix is `gcloud services enable`, not an IAM grant.
+_DISABLED_SIGNATURES = (
+    "has not been used in project",
+    "it is disabled",
+    "api is not enabled",
+    "serviceusage",
+)
+
+
+def _info(kind: ErrorKind) -> ErrorInfo:
+    detail, retryable = _GUIDANCE[kind]
+    return ErrorInfo(kind=kind, detail=detail, retryable=retryable)
+
+
+def _is_plan_blocked(message: str) -> bool:
+    lowered = message.lower()
+    return any(sig in lowered for sig in _PLAN_SIGNATURES)
+
+
+def _classify_403(message: str) -> ErrorKind:
+    lowered = message.lower()
+    if any(sig in lowered for sig in _DISABLED_SIGNATURES):
+        return ErrorKind.API_NOT_ENABLED
+    if _is_plan_blocked(lowered):
+        return ErrorKind.SUPPORT_PLAN_REQUIRED
+    # Fall back to the permission reading, whose guidance also tells the user to
+    # check the support plan — so an unrecognised 403 still points more than one way.
+    return ErrorKind.PERMISSION_DENIED
+
+
+_GRPC_MAP: tuple[tuple[type[BaseException], ErrorKind], ...] = (
+    (gexc.Unauthenticated, ErrorKind.UNAUTHENTICATED),
+    (gexc.NotFound, ErrorKind.NOT_FOUND),
+    (gexc.InvalidArgument, ErrorKind.INVALID_ARGUMENT),
+    (gexc.FailedPrecondition, ErrorKind.FAILED_PRECONDITION),
+    (gexc.ResourceExhausted, ErrorKind.RATE_LIMITED),
+    (gexc.ServiceUnavailable, ErrorKind.UNAVAILABLE),
+    (gexc.DeadlineExceeded, ErrorKind.UNAVAILABLE),
+    # Google returns a bare 500 for some malformed scopes (observed live for a
+    # project that does not exist). The HTTP path already maps 500 to UNAVAILABLE,
+    # so the gRPC path must too or the two transports disagree.
+    (gexc.InternalServerError, ErrorKind.UNAVAILABLE),
+    (gexc.GatewayTimeout, ErrorKind.UNAVAILABLE),
+)
+
+_HTTP_MAP: dict[int, ErrorKind] = {
+    400: ErrorKind.INVALID_ARGUMENT,
+    401: ErrorKind.UNAUTHENTICATED,
+    404: ErrorKind.NOT_FOUND,
+    409: ErrorKind.FAILED_PRECONDITION,
+    412: ErrorKind.FAILED_PRECONDITION,
+    429: ErrorKind.RATE_LIMITED,
+    500: ErrorKind.UNAVAILABLE,
+    502: ErrorKind.UNAVAILABLE,
+    503: ErrorKind.UNAVAILABLE,
+    504: ErrorKind.UNAVAILABLE,
+}
+
+
+def from_grpc(exc: BaseException) -> ErrorInfo:
+    """Classify an exception raised by the GAPIC async clients."""
+    if isinstance(exc, gexc.PermissionDenied):
+        return _info(_classify_403(str(exc)))
+    # The support-plan blocker does not always arrive as 403: creating a case on a
+    # project without a plan returns FailedPrecondition. Checked before the generic
+    # state-conflict reading, which would otherwise give badly wrong guidance.
+    if isinstance(exc, gexc.FailedPrecondition) and _is_plan_blocked(str(exc)):
+        return _info(ErrorKind.SUPPORT_PLAN_REQUIRED)
+    for exc_type, kind in _GRPC_MAP:
+        if isinstance(exc, exc_type):
+            return _info(kind)
+    return _info(ErrorKind.UNKNOWN)
+
+
+def from_http(exc: BaseException) -> ErrorInfo:
+    """Classify an exception raised by the media REST path.
+
+    Returns the same ErrorInfo a gRPC failure with the equivalent status would.
+    """
+    if isinstance(exc, httpx.HTTPStatusError):
+        status = exc.response.status_code
+        body = exc.response.text or ""
+        if status == 403:
+            return _info(_classify_403(body))
+        if status == 400 and _is_plan_blocked(body):
+            return _info(ErrorKind.SUPPORT_PLAN_REQUIRED)
+        kind = _HTTP_MAP.get(status)
+        if kind is not None:
+            return _info(kind)
+        return _info(ErrorKind.UNKNOWN)
+    if isinstance(exc, httpx.TimeoutException):
+        return _info(ErrorKind.UNAVAILABLE)
+    if isinstance(exc, httpx.TransportError):
+        return _info(ErrorKind.UNAVAILABLE)
+    return _info(ErrorKind.UNKNOWN)
+
+
+def custom(kind: ErrorKind, detail: str, *, retryable: bool = False) -> ErrorInfo:
+    """Classify a failure this server detected itself, before any upstream call.
+
+    Used where the guidance is more specific than the table's generic text — an
+    unusable cursor, or no scopes configured.
+    """
+    return ErrorInfo(kind=kind, detail=detail, retryable=retryable)
+
+
+def to_tool_error(info: ErrorInfo) -> ToolError:
+    """Wrap classified information for the client.
+
+    `mask_error_details=True` on the server means only ToolError text reaches a
+    client, so anything that skips this function leaks nothing.
+    """
+    suffix = " (retryable)" if info.retryable else ""
+    return ToolError(f"[{info.kind.value}]{suffix} {info.detail}")

google_cloud_support_mcp/fanout.py

@@ -0,0 +1,145 @@
+"""Cross-org fan-out: query every configured scope in parallel and merge.
+
+Neither v2 nor v2beta can search more than one parent per call — the query
+grammar's OR only combines values within a single field, never scope identifiers
+(research.md R-004). So cross-org lives here, on the client, and three
+consequences follow from that:
+
+  * Google's page tokens are per-parent, so a merged result needs a composite
+    cursor rather than a passthrough token.
+  * Partial failure is the normal case, not an exception: with N parents one may
+    lack permission and another may lack a support plan. A single 403 must not
+    hide the parents that succeeded.
+  * Concurrency multiplies rate-limit exposure, so it is bounded.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import json
+from collections.abc import Awaitable, Callable, Iterable, Sequence
+from typing import Any
+
+from .errors import from_grpc
+from .models import ListEnvelope, ScopeFailure
+
+__all__ = ["CursorError", "decode_cursor", "encode_cursor", "fanout_list"]
+
+_CURSOR_VERSION = 1
+
+# One page fetch for a single parent: (items, next_page_token or None).
+FetchPage = Callable[[str, str | None, int], Awaitable[tuple[list[Any], str | None]]]
+
+
+class CursorError(ValueError):
+    """Raised for a cursor this server did not issue, or that no longer fits the request."""
+
+
+def encode_cursor(cursors: dict[str, str | None]) -> str | None:
+    """Pack per-parent page tokens into one opaque string.
+
+    Returns None when every parent is exhausted — there is nothing left to page.
+    """
+    if all(token is None for token in cursors.values()):
+        return None
+    payload = json.dumps(
+        {"v": _CURSOR_VERSION, "cursors": cursors}, separators=(",", ":"), sort_keys=True
+    )
+    return base64.urlsafe_b64encode(payload.encode()).decode()
+
+
+def decode_cursor(cursor: str, expected_parents: Iterable[str]) -> dict[str, str | None]:
+    """Unpack a cursor, rejecting anything that would silently skew results."""
+    try:
+        raw = base64.urlsafe_b64decode(cursor.encode())
+        payload = json.loads(raw)
+    except (binascii.Error, ValueError, UnicodeDecodeError) as exc:
+        raise CursorError(
+            "The cursor is not one this server issued. Drop it and start from the first page."
+        ) from exc
+
+    if not isinstance(payload, dict) or payload.get("v") != _CURSOR_VERSION:
+        raise CursorError(
+            "The cursor uses an unsupported format version. Start from the first page."
+        )
+
+    cursors = payload.get("cursors")
+    if not isinstance(cursors, dict):
+        raise CursorError("The cursor is malformed. Start from the first page.")
+
+    # A cursor is only meaningful for the scope set it was issued against. If the
+    # caller changed `parents` mid-pagination, continuing would quietly drop or
+    # duplicate results, so refuse instead.
+    if set(cursors) != set(expected_parents):
+        raise CursorError(
+            "The cursor was issued for a different set of parents than this request uses. "
+            "Either repeat the original parents, or omit the cursor to start over."
+        )
+    return cursors
+
+
+async def fanout_list(
+    parents: Sequence[str],
+    *,
+    page_size: int,
+    cursor: str | None,
+    fetch: FetchPage,
+    concurrency: int = 5,
+) -> ListEnvelope[Any]:
+    """Fetch one page from each live parent concurrently and merge the results.
+
+    A parent that fails contributes a ScopeFailure rather than aborting the call.
+    """
+    parent_list = list(parents)
+    tokens: dict[str, str | None] = (
+        decode_cursor(cursor, parent_list) if cursor else dict.fromkeys(parent_list)
+    )
+
+    # Parents whose token is None *and* that we have paged before are exhausted.
+    # On the first page every token is None, so everything is live.
+    live = parent_list if cursor is None else [p for p in parent_list if tokens[p] is not None]
+
+    semaphore = asyncio.Semaphore(max(1, concurrency))
+
+    async def run(parent: str) -> tuple[str, list[Any], str | None, Exception | None]:
+        async with semaphore:
+            try:
+                items, next_token = await fetch(parent, tokens[parent], page_size)
+            except Exception as exc:
+                # Deliberately Exception, not BaseException: asyncio.CancelledError
+                # must propagate so a cancelled request stops instead of being
+                # recorded as a per-parent failure.
+                return parent, [], None, exc
+            return parent, items, next_token, None
+
+    results = await asyncio.gather(*(run(p) for p in live))
+
+    items: list[Any] = []
+    failures: list[ScopeFailure] = []
+    next_tokens: dict[str, str | None] = dict.fromkeys(parent_list)
+
+    for parent, page_items, next_token, exc in results:
+        if exc is not None:
+            info = from_grpc(exc)
+            failures.append(
+                ScopeFailure(
+                    parent=parent,
+                    reason=info.kind,
+                    detail=info.detail,
+                    retryable=info.retryable,
+                )
+            )
+            continue
+        items.extend(page_items)
+        next_tokens[parent] = next_token
+
+    next_cursor = encode_cursor(next_tokens)
+    return ListEnvelope[Any](
+        items=items,
+        scopes_queried=parent_list,
+        scopes_failed=failures,
+        next_cursor=next_cursor,
+        truncated=next_cursor is not None,
+    )