scitrera-aether-client 0.2.0__tar.gz → 0.2.2__tar.gz

{scitrera_aether_client-0.2.0 → scitrera_aether_client-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitrera-aether-client
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python client SDK for Scitrera Aether distributed control plane
 Author-email: "scitrera.ai" <open-source-team@scitrera.com>
 License-Expression: Apache-2.0
@@ -22,12 +22,14 @@ Classifier: Typing :: Typed
 Classifier: Framework :: AsyncIO
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: grpcio==1.80.0
-Requires-Dist: protobuf>6
+Requires-Dist: grpcio==1.81.1
+Requires-Dist: protobuf>=6.33.5
 Provides-Extra: dev
-Requires-Dist: grpcio==1.80.0; extra == "dev"
-Requires-Dist: pytest==9.0.3; extra == "dev"
+Requires-Dist: grpcio==1.81.1; extra == "dev"
 Requires-Dist: pytest==9.0.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: requests>=2.32; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
 Requires-Dist: mypy>=1.8.0; extra == "dev"
 Requires-Dist: types-protobuf>=4.24.0; extra == "dev"
 Requires-Dist: grpc-stubs>=1.53.0; extra == "dev"
@@ -259,7 +261,7 @@ Aether defines the following principal types. Each maps to a dedicated client cl
 | **WorkflowEngine** | `WorkflowEngineClient` / `AsyncWorkflowEngineClient` | `wfe::shard0` | Singleton invariant; `Implementation` reserved for future multi-shard. Processes `EVENT`-type messages and triggers downstream automation. Has the broadest send permissions — can target any principal type. |
 | **MetricsBridge** | `MetricsBridgeClient` / `AsyncMetricsBridgeClient` | `metrics::shard0` | Singleton invariant matching WFE sharding model; `Implementation` reserved for future multi-shard. Receive-only telemetry sink. Collects `METRIC`-type messages from agents and tasks; cannot send messages. |
 | **Service** | `ServiceClient` / `AsyncServiceClient` | `sv::{impl}::{spec}` | Trusted backend intermediary. Workspace-less; authenticates as itself and performs privileged operations on behalf of users via `AuthorizationContext`. Use for app/WebSocket backends proxying user actions. |
-| **Bridge** | *(not yet in Python SDK)* | `br::{impl}::{spec}` | Cross-workspace messaging integration (e.g., Discord, Teams, Email). Has no workspace component and can send to any workspace. Implemented as a standalone server (`cmd/msgbridge`). |
+| **Bridge** | *(not yet in Python SDK)* | `br::{impl}::{spec}` | Cross-workspace messaging integration (e.g., Discord, Teams, Email). Has no workspace component and can send to any workspace. |
 
 ---
 

{scitrera_aether_client-0.2.0 → scitrera_aether_client-0.2.2}/README.md

@@ -224,7 +224,7 @@ Aether defines the following principal types. Each maps to a dedicated client cl
 | **WorkflowEngine** | `WorkflowEngineClient` / `AsyncWorkflowEngineClient` | `wfe::shard0` | Singleton invariant; `Implementation` reserved for future multi-shard. Processes `EVENT`-type messages and triggers downstream automation. Has the broadest send permissions — can target any principal type. |
 | **MetricsBridge** | `MetricsBridgeClient` / `AsyncMetricsBridgeClient` | `metrics::shard0` | Singleton invariant matching WFE sharding model; `Implementation` reserved for future multi-shard. Receive-only telemetry sink. Collects `METRIC`-type messages from agents and tasks; cannot send messages. |
 | **Service** | `ServiceClient` / `AsyncServiceClient` | `sv::{impl}::{spec}` | Trusted backend intermediary. Workspace-less; authenticates as itself and performs privileged operations on behalf of users via `AuthorizationContext`. Use for app/WebSocket backends proxying user actions. |
-| **Bridge** | *(not yet in Python SDK)* | `br::{impl}::{spec}` | Cross-workspace messaging integration (e.g., Discord, Teams, Email). Has no workspace component and can send to any workspace. Implemented as a standalone server (`cmd/msgbridge`). |
+| **Bridge** | *(not yet in Python SDK)* | `br::{impl}::{spec}` | Cross-workspace messaging integration (e.g., Discord, Teams, Email). Has no workspace component and can send to any workspace. |
 
 ---
 

{scitrera_aether_client-0.2.0 → scitrera_aether_client-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scitrera-aether-client"
-version = "0.2.0"
+version = "0.2.2"
 description = "Python client SDK for Scitrera Aether distributed control plane"
 readme = "README.md"
 license = "Apache-2.0"
@@ -36,15 +36,23 @@ classifiers = [
     "Framework :: AsyncIO",
 ]
 dependencies = [
-    "grpcio==1.80.0",
-    "protobuf>6",
+    "grpcio==1.81.1",
+    "protobuf>=6.33.5",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "grpcio==1.80.0",
-    "pytest==9.0.3",
+    "grpcio==1.81.1",
     "pytest==9.0.3",
+    # Required, not optional: asyncio_mode = "auto" below plus ~170 async tests.
+    "pytest-asyncio>=0.23.0",
+    # requests and httpx are optional at runtime — requests_adapter.py and
+    # httpx_transport.py both guard the import and raise a clear install hint —
+    # but their test modules import them unconditionally, so the suite cannot run
+    # without them. Absent from the extra, these passed locally only because a
+    # shared virtualenv happened to have both installed.
+    "requests>=2.32",
+    "httpx>=0.27",
     "mypy>=1.8.0",
     "types-protobuf>=4.24.0",
     "grpc-stubs>=1.53.0",

{scitrera_aether_client-0.2.0 → scitrera_aether_client-0.2.2}/scitrera_aether_client/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 # Import the proxy module for its side effect: installs the
 # ``ProxyHttpResponse`` / ``ProxyHttpBodyChunk`` dispatcher hook on
@@ -41,9 +41,15 @@ from ._common import (
     KV_SCOPE_USER_SHARED,
     KV_SCOPE_USER_WORKSPACE_SHARED,
 
+    # Canonical principal-type strings (mirror server models.PrincipalType)
+    PrincipalType,
+
     # Auth credentials builder
     Credentials,
 
+    # Service-addressing wildcard sentinel
+    SERVICE_WILDCARD,
+
     # internal
     _logging_lite_hook,
 )
@@ -394,6 +400,9 @@ __all__ = (
     # Types - Other
     'Credentials',
 
+    # Service-addressing wildcard sentinel
+    'SERVICE_WILDCARD',
+
     # Metric builder
     'MetricBuilder',
     'new_metric',

{scitrera_aether_client-0.2.0 → scitrera_aether_client-0.2.2}/scitrera_aether_client/_common.py

@@ -197,6 +197,7 @@ def create_service_init(implementation: str, specifier: str,
                         credentials: Optional[Dict[str, str]] = None,
                         resume_session_id: str = "",
                         extensions: Optional[List["aether_pb2.ExtensionDeclaration"]] = None,
+                        no_pool_consumer: bool = False,
                         ) -> aether_pb2.InitConnection:
     """Create an InitConnection message for a Service principal (workspace-less).
 
@@ -205,11 +206,17 @@ def create_service_init(implementation: str, specifier: str,
     privileged work on behalf of users via ``AuthorizationContext``.
 
     Canonical identity string: ``sv::{implementation}::{specifier}``.
+
+    ``no_pool_consumer`` opts this connection OUT of pool-task routing — the
+    gateway will not add it to the implementation worker index, so it is never
+    targeted for POOL-mode task assignments. Set it for serve-only instances
+    that register no task handlers (default False = consumer, back-compat).
     """
     return _apply_client_version_meta(aether_pb2.InitConnection(
         service=aether_pb2.ServiceIdentity(
             implementation=implementation,
             specifier=specifier,
+            no_pool_consumer=no_pool_consumer,
         ),
         credentials=credentials or {},
         resume_session_id=resume_session_id,
@@ -230,18 +237,57 @@ def create_service_init(implementation: str, specifier: str,
 IDENTITY_SEP = "::"
 
 
+class _ServiceWildcard:
+    """Sentinel type for the service-addressing wildcard specifier.
+
+    A single module-level instance (:data:`SERVICE_WILDCARD`) is the only
+    value that should ever exist; identity comparison (``is``) is the
+    intended check. ``repr`` is descriptive so it reads clearly in logs
+    and assertion failures.
+    """
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return "SERVICE_WILDCARD"
+
+
+# Explicit, opt-in wildcard for service addressing. Pass this as the
+# ``specifier`` to :func:`create_topic_service` (or to a client's
+# ``send_message_to_service``) to emit the bare ``sv::{impl}`` wildcard
+# target. The gateway (``models.topics.ParseSendTarget``) resolves a bare
+# 2-segment ``sv::{impl}`` to any registered ``sv::{impl}::{spec}`` instance.
+#
+# This MUST be opted into deliberately: a normal non-empty specifier emits
+# the canonical 3-segment ``sv::{impl}::{spec}`` and an empty string ``""``
+# STAYS 3-segment (``sv::{impl}::``) — only this sentinel produces the
+# 2-segment wildcard, so "" can never silently become a wildcard.
+SERVICE_WILDCARD = _ServiceWildcard()
+
+
 def create_topic_agent(workspace: str, implementation: str, specifier: str) -> str:
     """Create a topic string for a specific agent."""
     return f"ag{IDENTITY_SEP}{workspace}{IDENTITY_SEP}{implementation}{IDENTITY_SEP}{specifier}"
 
 
-def create_topic_service(implementation: str, specifier: str) -> str:
-    """Create a topic string for a specific service principal.
+def create_topic_service(implementation, specifier) -> str:
+    """Create a topic string for a service principal.
+
+    Two shapes, selected by ``specifier``:
 
-    Service principals are workspace-less (canonical identity is
-    ``sv::{implementation}::{specifier}``); the topic mirrors that shape.
-    Mirrors :func:`models.topics.ServiceTopic` on the gateway side.
+    * A concrete ``specifier`` (any ``str``, including the empty string)
+      emits the canonical 3-segment ``sv::{implementation}::{specifier}``.
+      An empty string therefore yields ``sv::{implementation}::`` (a
+      concrete, trailing-``::`` target) — it is NOT treated as a wildcard.
+    * The :data:`SERVICE_WILDCARD` sentinel emits the bare 2-segment
+      ``sv::{implementation}`` wildcard, which the gateway resolves to any
+      registered ``sv::{implementation}::{spec}`` instance.
+
+    Mirrors :func:`models.topics.ServiceTopic` (concrete) and
+    :func:`models.topics.ParseSendTarget` (wildcard) on the gateway side.
     """
+    if specifier is SERVICE_WILDCARD:
+        return f"sv{IDENTITY_SEP}{implementation}"
     return f"sv{IDENTITY_SEP}{implementation}{IDENTITY_SEP}{specifier}"
 
 
@@ -267,6 +313,18 @@ def create_topic_user_workspace(user_id: str, workspace: str) -> str:
     return f"uw{IDENTITY_SEP}{user_id}{IDENTITY_SEP}{workspace}"
 
 
+def create_topic_user_broadcast(user_id: str) -> str:
+    """Create a per-user broadcast topic (uu::{user_id}).
+
+    Reaches every one of a user's open windows regardless of which workspace
+    each window is currently viewing -- the workspace-agnostic, non-progress
+    complement to the per-user progress topic. Only platform principals
+    (service / workflow-engine / bridge) may publish; the gateway rejects
+    sends from workspace-scoped principals.
+    """
+    return f"uu{IDENTITY_SEP}{user_id}"
+
+
 def create_topic_global_agents(workspace: str) -> str:
     """Create a global broadcast topic for all agents in a workspace."""
     return f"ga{IDENTITY_SEP}{workspace}"
@@ -311,6 +369,26 @@ KV_SCOPE_WORKSPACE_EXCLUSIVE = "workspace-exclusive"
 KV_SCOPE_USER_SHARED = "user-shared"
 KV_SCOPE_USER_WORKSPACE_SHARED = "user-workspace-shared"
 
+
+class PrincipalType:
+    """Canonical Aether principal-type strings.
+
+    These MUST match the server's ``models.PrincipalType`` constants verbatim
+    (server/pkg/models/identity.go) — the gateway compares them exactly (e.g.
+    api-key ``parsePrincipalType``), so a case/spelling mismatch like ``"user"``
+    vs ``"User"`` is rejected. Always reference these constants instead of
+    hardcoding the string when minting tokens / asserting an identity type.
+    """
+
+    AGENT = "Agent"
+    TASK = "Task"
+    USER = "User"
+    SERVICE = "Service"
+    WORKFLOW_ENGINE = "WorkflowEngine"
+    METRICS_BRIDGE = "MetricsBridge"
+    ORCHESTRATOR = "Orchestrator"
+    BRIDGE = "Bridge"
+
 _SCOPE_MAP = {
     "global": aether_pb2.KVOperation.GLOBAL,
     "workspace": aether_pb2.KVOperation.WORKSPACE,

{scitrera_aether_client-0.2.0 → scitrera_aether_client-0.2.2}/scitrera_aether_client/admin.py

@@ -141,12 +141,17 @@ class AdminClient:
                         granted_by: str = "",
                         reason: str = "",
                         expires_at: int = 0,
+                        authorization: Optional[aether_pb2.AuthorizationContext] = None,
                         timeout: float = 10.0):
         """Create an ACL rule granting access.
 
         ``access_level`` uses the numeric tiers from ``internal/acl/types.go``:
         ``0=NONE, 10=READ, 20=READWRITE, 30=MANAGE, 40=ADMIN, 50=SUPERADMIN``.
 
+        ``authorization`` is an optional on-behalf-of authority context. When
+        set, the gateway runs the admin ACL check against the subject (the
+        user) rather than the actor (the platform-server).
+
         Note:
             The TS surface uses a string ``permission`` and a ``metadata``
             map. The Python proto uses ``access_level`` (int) and ``granted_by``
@@ -165,14 +170,55 @@ class AdminClient:
                 reason=reason,
                 expires_at=expires_at,
             ),
+            authorization=authorization,
         )
         return self._client.acl_op(op, timeout=timeout)
 
-    def delete_acl_rule(self, rule_id: str, timeout: float = 10.0):
-        """Delete (revoke) an ACL rule by ID."""
+    def delete_acl_rule(self, rule_id: str,
+                        authorization: Optional[aether_pb2.AuthorizationContext] = None,
+                        timeout: float = 10.0):
+        """Delete (revoke) an ACL rule by its UUID rule_id.
+
+        The gateway resolves the rule's principal+resource from the UUID and
+        then deletes by composite key. Returns an error if the rule_id is not
+        found.
+
+        ``authorization`` is an optional on-behalf-of authority context (see
+        :meth:`create_acl_rule`).
+        """
         op = aether_pb2.ACLOperation(
             op=aether_pb2.ACLOperation.REVOKE,
             rule_id=rule_id,
+            authorization=authorization,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def revoke_acl_rule(self,
+                        principal_type: str,
+                        principal_id: str,
+                        resource_type: str,
+                        resource_id: str,
+                        authorization: Optional[aether_pb2.AuthorizationContext] = None,
+                        timeout: float = 10.0):
+        """Revoke an ACL rule by its composite (principal + resource) key.
+
+        This is the direct revoke path: it sends ``ACLOperation(op=REVOKE,
+        rule_filter=ACLRuleFilter(...))`` which the gateway maps to a delete
+        by composite key without any UUID lookup. Prefer this method when you
+        already have the principal and resource identifiers.
+
+        ``authorization`` is an optional on-behalf-of authority context (see
+        :meth:`create_acl_rule`).
+        """
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.REVOKE,
+            rule_filter=aether_pb2.ACLRuleFilter(
+                principal_type=principal_type,
+                principal_id=principal_id,
+                resource_type=resource_type,
+                resource_id=resource_id,
+            ),
+            authorization=authorization,
         )
         return self._client.acl_op(op, timeout=timeout)
 
@@ -183,8 +229,13 @@ class AdminClient:
                        resource_id: str = "",
                        limit: int = 0,
                        offset: int = 0,
+                       authorization: Optional[aether_pb2.AuthorizationContext] = None,
                        timeout: float = 10.0):
-        """List ACL rules with optional filters."""
+        """List ACL rules with optional filters.
+
+        ``authorization`` is an optional on-behalf-of authority context (see
+        :meth:`create_acl_rule`).
+        """
         op = aether_pb2.ACLOperation(
             op=aether_pb2.ACLOperation.LIST_RULES,
             rule_filter=aether_pb2.ACLRuleFilter(
@@ -195,6 +246,7 @@ class AdminClient:
                 limit=limit,
                 offset=offset,
             ),
+            authorization=authorization,
         )
         return self._client.acl_op(op, timeout=timeout)
 
@@ -229,6 +281,269 @@ class AdminClient:
         )
         return self._client.acl_op(op, timeout=timeout)
 
+    # ------------------------------------------------------------------
+    # Role / Group Operations
+    # ------------------------------------------------------------------
+    #
+    # A group is a named collection of principals; a role is a named
+    # permission bundle (its permissions are granted with
+    # :meth:`create_acl_rule` using ``principal_type="role"``,
+    # ``principal_id=<role name>``). Membership/assignment edges are resolved
+    # transitively and combined additively at evaluation time. These mirror
+    # the Go SDK helpers in ``sdk/go/aether/admin_roles.go``.
+
+    def create_role(self,
+                    name: str,
+                    description: str = "",
+                    created_by: str = "",
+                    metadata: Optional[Dict[str, str]] = None,
+                    timeout: float = 10.0):
+        """Create a named role.
+
+        Grant its permissions with :meth:`create_acl_rule` using
+        ``principal_type="role"``, ``principal_id=<role name>``.
+
+        Note:
+            Creating a role that already exists returns a response with
+            ``success=False`` and an ``error`` like ``ErrRoleExists`` rather
+            than raising; callers decide how to treat that.
+        """
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.CREATE_ROLE,
+            role_request=aether_pb2.ACLRoleRequest(
+                name=name,
+                description=description,
+                created_by=created_by,
+                metadata=metadata or {},
+            ),
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def delete_role(self, name: str, timeout: float = 10.0):
+        """Delete a role (and its permission rules) by name."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.DELETE_ROLE,
+            name=name,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def get_role(self, name: str, timeout: float = 10.0):
+        """Fetch a role by name."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.GET_ROLE,
+            name=name,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def list_roles(self, timeout: float = 10.0):
+        """List all roles."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.LIST_ROLES,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def assign_role(self,
+                    name: str,
+                    assignee_type: str,
+                    assignee_id: str,
+                    granted_by: str = "",
+                    expires_at: int = 0,
+                    timeout: float = 10.0):
+        """Assign (or refresh) a role to a principal or group.
+
+        ``assignee_type`` is a principal type or ``"group"``. ``expires_at``
+        is Unix seconds; ``0`` means no expiry.
+        """
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.ASSIGN_ROLE,
+            name=name,
+            assignment_request=aether_pb2.ACLRoleAssignmentRequest(
+                assignee_type=assignee_type,
+                assignee_id=assignee_id,
+                granted_by=granted_by,
+                expires_at=expires_at,
+            ),
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def unassign_role(self,
+                      name: str,
+                      assignee_type: str,
+                      assignee_id: str,
+                      timeout: float = 10.0):
+        """Remove a role assignment from a principal or group."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.UNASSIGN_ROLE,
+            name=name,
+            principal=aether_pb2.PrincipalRef(
+                principal_type=assignee_type,
+                principal_id=assignee_id,
+            ),
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def list_role_assignments(self, name: str, timeout: float = 10.0):
+        """List the direct assignees of a role."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.LIST_ROLE_ASSIGNMENTS,
+            name=name,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def list_principal_roles(self,
+                             principal_type: str,
+                             principal_id: str,
+                             timeout: float = 10.0):
+        """List the roles directly assigned to a principal."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.LIST_PRINCIPAL_ROLES,
+            principal=aether_pb2.PrincipalRef(
+                principal_type=principal_type,
+                principal_id=principal_id,
+            ),
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def create_group(self,
+                     name: str,
+                     description: str = "",
+                     created_by: str = "",
+                     metadata: Optional[Dict[str, str]] = None,
+                     timeout: float = 10.0):
+        """Create a named group.
+
+        Note:
+            Creating a group that already exists returns a response with
+            ``success=False`` and an ``error`` rather than raising; callers
+            decide how to treat that.
+        """
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.CREATE_GROUP,
+            group_request=aether_pb2.ACLGroupRequest(
+                name=name,
+                description=description,
+                created_by=created_by,
+                metadata=metadata or {},
+            ),
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def delete_group(self, name: str, timeout: float = 10.0):
+        """Delete a group by name."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.DELETE_GROUP,
+            name=name,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def get_group(self, name: str, timeout: float = 10.0):
+        """Fetch a group by name."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.GET_GROUP,
+            name=name,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def list_groups(self, timeout: float = 10.0):
+        """List all groups."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.LIST_GROUPS,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def add_group_member(self,
+                         name: str,
+                         member_type: str,
+                         member_id: str,
+                         granted_by: str = "",
+                         expires_at: int = 0,
+                         timeout: float = 10.0):
+        """Add (or refresh) a member of a group.
+
+        ``member_type`` is a principal type or ``"group"`` (for nesting).
+        ``expires_at`` is Unix seconds; ``0`` means no expiry.
+        """
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.ADD_GROUP_MEMBER,
+            name=name,
+            member_request=aether_pb2.ACLGroupMemberRequest(
+                member_type=member_type,
+                member_id=member_id,
+                granted_by=granted_by,
+                expires_at=expires_at,
+            ),
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def remove_group_member(self,
+                            name: str,
+                            member_type: str,
+                            member_id: str,
+                            timeout: float = 10.0):
+        """Remove a member from a group."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.REMOVE_GROUP_MEMBER,
+            name=name,
+            principal=aether_pb2.PrincipalRef(
+                principal_type=member_type,
+                principal_id=member_id,
+            ),
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def list_group_members(self, name: str, timeout: float = 10.0):
+        """List the direct members of a group."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.LIST_GROUP_MEMBERS,
+            name=name,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def list_principal_groups(self,
+                              principal_type: str,
+                              principal_id: str,
+                              timeout: float = 10.0):
+        """List the groups a principal is a direct member of."""
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.LIST_PRINCIPAL_GROUPS,
+            principal=aether_pb2.PrincipalRef(
+                principal_type=principal_type,
+                principal_id=principal_id,
+            ),
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
+    def explain_access(self,
+                       principal_type: str,
+                       principal_id: str,
+                       resource_type: str,
+                       resource_id: str,
+                       required_level: int = 0,
+                       timeout: float = 10.0):
+        """Explain how a principal's effective access to a resource is decided.
+
+        Resolves the subject set (self + transitive groups/roles), every rule
+        that matched, and the resulting decision. This does not gate access,
+        but the gateway records an ``explain_access`` audit event attributing
+        the call to the connected principal. ``required_level`` is the
+        threshold the decision is compared against (``0`` = NONE).
+
+        Read the result from the response's ``explanation`` field
+        (:class:`~aether_pb2.ACLAccessExplanationInfo`), whose ``allowed`` and
+        ``effective_access_level`` fields carry the resolved decision.
+        """
+        op = aether_pb2.ACLOperation(
+            op=aether_pb2.ACLOperation.EXPLAIN_ACCESS,
+            principal=aether_pb2.PrincipalRef(
+                principal_type=principal_type,
+                principal_id=principal_id,
+            ),
+            resource_type=resource_type,
+            resource_id=resource_id,
+            required_level=required_level,
+        )
+        return self._client.acl_op(op, timeout=timeout)
+
     # ------------------------------------------------------------------
     # Workspace Operations
     # ------------------------------------------------------------------