computer-agent-py 0.1.0__py3-none-any.whl

computeragent/_proxy/query.py

@@ -0,0 +1,165 @@
+"""``query`` — drop-in for :func:`claude_agent_sdk.query` with a telemetry tap.
+
+Every message yielded by the upstream stream is also reported into the active
+telemetry pipeline. The user-visible stream is preserved verbatim — the proxy
+never modifies or reorders yielded messages.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+import claude_agent_sdk
+from claude_agent_sdk.types import AssistantMessage, ResultMessage, TextBlock
+
+from ..telemetry import TelemetryEvent, get_pipeline, new_session_id
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterable, AsyncIterator
+
+logger = logging.getLogger("computeragent")
+
+
+async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
+    *,
+    prompt: str | AsyncIterable[dict[str, Any]],
+    options: Any = None,
+    transport: Any = None,
+) -> AsyncIterator[Any]:
+    """Drop-in for ``claude_agent_sdk.query`` — see upstream docs for the
+    parameter semantics. The wrapper additionally pushes a
+    :class:`~computeragent.telemetry.TelemetryEvent` per message into the
+    active pipeline.
+
+    The pipeline is always the module-level default unless the caller
+    pre-configured one via :func:`computeragent.telemetry.configure`.
+    """
+    pipeline = get_pipeline()
+    session_id = new_session_id()
+    agent_name = _derive_agent_name(options)
+    started_at = time.monotonic()
+    last_assistant_text = ""
+
+    try:
+        await pipeline.emit(
+            TelemetryEvent.session_started(
+                session_id=session_id,
+                agent_name=agent_name,
+                options=options,
+                prompt=prompt,
+            )
+        )
+
+        last_result: ResultMessage | None = None
+        upstream_kwargs: dict[str, Any] = {"prompt": prompt}
+        if options is not None:
+            upstream_kwargs["options"] = options
+        if transport is not None:
+            upstream_kwargs["transport"] = transport
+
+        upstream_session_id: str | None = None
+        async for msg in claude_agent_sdk.query(**upstream_kwargs):
+            # Capture upstream's session id once for join-by-id later, but
+            # do NOT rebind our `session_id` mid-stream — the sinks already
+            # opened bookkeeping under the placeholder on session_started,
+            # so swapping the key here would orphan that state and produce
+            # empty agent_logs.query / missing sessions.entries[].
+            real_sid = getattr(msg, "session_id", None)
+            if (
+                isinstance(real_sid, str)
+                and real_sid
+                and real_sid != session_id
+                and upstream_session_id is None
+            ):
+                upstream_session_id = real_sid
+
+            for ev in TelemetryEvent.from_message(
+                msg, session_id=session_id, agent_name=agent_name
+            ):
+                await pipeline.emit(ev)
+
+            if isinstance(msg, AssistantMessage):
+                # Track latest assistant text as a fallback when ResultMessage.result is empty.
+                for block in getattr(msg, "content", []) or []:
+                    if isinstance(block, TextBlock):
+                        last_assistant_text = block.text
+
+            if isinstance(msg, ResultMessage):
+                last_result = msg
+
+            yield msg
+
+        duration_ms = (time.monotonic() - started_at) * 1000.0
+        if last_result is not None:
+            ev = TelemetryEvent.session_ended_ok(
+                session_id=session_id,
+                agent_name=agent_name,
+                result=last_result,
+                duration_ms=duration_ms,
+                last_assistant_text=last_assistant_text,
+            )
+            if upstream_session_id is not None:
+                ev.payload["upstream_session_id"] = upstream_session_id
+            await pipeline.emit(ev)
+        else:
+            # Upstream finished without a ResultMessage — synthesize one event.
+            await pipeline.emit(
+                TelemetryEvent(
+                    kind="session_ended",
+                    session_id=session_id,
+                    agent_name=agent_name,
+                    payload={
+                        "is_error": False,
+                        "subtype": "no_result",
+                        "result": last_assistant_text,
+                        "duration_ms": duration_ms,
+                        "num_turns": 0,
+                        "total_cost_usd": 0.0,
+                        "usage": {},
+                    },
+                )
+            )
+    except BaseException as exc:
+        duration_ms = (time.monotonic() - started_at) * 1000.0
+        try:
+            await pipeline.emit(
+                TelemetryEvent.session_ended_error(
+                    session_id=session_id,
+                    agent_name=agent_name,
+                    exc=exc,
+                    duration_ms=duration_ms,
+                )
+            )
+        except Exception:  # noqa: BLE001
+            logger.debug("error-path telemetry emit failed", exc_info=True)
+        raise
+    finally:
+        try:
+            await pipeline.flush()
+        except Exception:  # noqa: BLE001
+            logger.debug("pipeline flush in query() finally failed", exc_info=True)
+
+
+def _derive_agent_name(options: Any) -> str | None:
+    """Pick a stable agent name from options.
+
+    Strategy:
+      1. Explicit ``agent_name`` attribute (not in upstream today but cheap to
+         honour if a fork adds it).
+      2. First non-empty line of ``system_prompt`` (NordAssist's prod prompt
+         starts with "You are NordAssist..." — that line is the natural label).
+      3. ``None`` — the sinks fall back to an anonymous hash.
+    """
+    if options is None:
+        return None
+    name = getattr(options, "agent_name", None)
+    if isinstance(name, str) and name:
+        return name
+    sp = getattr(options, "system_prompt", None)
+    if isinstance(sp, str) and sp:
+        first = sp.strip().splitlines()[0].strip()
+        if first:
+            return first[:80]
+    return None

computeragent/policy/__init__.py

@@ -0,0 +1,59 @@
+"""Policy-based tool-use authorization.
+
+Public surface:
+
+* :class:`~computeragent.policy.types.PolicyEngine` — Protocol implemented by
+  :class:`~computeragent.policy.opa.OpaPolicyEngine` and
+  :class:`~computeragent.policy.cedar.CedarPolicyEngine`.
+* :class:`~computeragent.policy.types.PolicyInput` and friends
+  (``PolicyPrincipal``, ``PolicyAction``, ``PolicyResource``, ``PolicyResult``,
+  ``PolicyDecision``) — canonical engine-agnostic shapes.
+* :class:`~computeragent.policy.authorizer.PolicyToolAuthorizer` — drop into
+  ``ClaudeAgentOptions.can_use_tool`` to gate every tool call through your
+  engine of choice.
+
+Engines are imported lazily so a user who installs only ``computer-agent-py``
+(no Cedar extra) doesn't pay an ``ImportError`` cost on
+``from computeragent.policy import OpaPolicyEngine``.
+"""
+
+from __future__ import annotations
+
+from .authorizer import PolicyToolAuthorizer
+from .types import (
+    FailMode,
+    PolicyAction,
+    PolicyDecision,
+    PolicyEngine,
+    PolicyInput,
+    PolicyPrincipal,
+    PolicyResource,
+    PolicyResult,
+)
+
+__all__ = [
+    "FailMode",
+    "OpaPolicyEngine",
+    "CedarPolicyEngine",
+    "PolicyAction",
+    "PolicyDecision",
+    "PolicyEngine",
+    "PolicyInput",
+    "PolicyPrincipal",
+    "PolicyResource",
+    "PolicyResult",
+    "PolicyToolAuthorizer",
+]
+
+
+def __getattr__(name: str):  # type: ignore[no-untyped-def]
+    """Lazy import — only raise ImportError for the engine the user asked for."""
+    if name == "OpaPolicyEngine":
+        from .opa import OpaPolicyEngine as _OpaPolicyEngine
+
+        return _OpaPolicyEngine
+    if name == "CedarPolicyEngine":
+        from .cedar import CedarPolicyEngine as _CedarPolicyEngine
+
+        return _CedarPolicyEngine
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

computeragent/policy/authorizer.py

@@ -0,0 +1,161 @@
+"""``PolicyToolAuthorizer`` — adapter from :class:`PolicyEngine` to
+``claude_agent_sdk.types.CanUseTool``.
+
+Drops straight onto ``ClaudeAgentOptions.can_use_tool``. On each tool the
+agent wants to execute, the authorizer:
+
+1. Builds a :class:`PolicyInput` using the user-supplied resolvers + the
+   ``ToolPermissionContext`` upstream gives us.
+2. Calls ``await engine.evaluate(input)``.
+3. Returns ``PermissionResultAllow`` or ``PermissionResultDeny``.
+4. Emits a ``policy_decision`` telemetry event so the OTel sink can annotate
+   the active ``execute_tool`` span.
+
+If the engine raises, the result depends on the engine's ``fail_mode`` (the
+engine controls fail-closed-vs-open, not the authorizer).
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Literal
+
+from claude_agent_sdk.types import (
+    PermissionResultAllow,
+    PermissionResultDeny,
+)
+
+from ..telemetry import TelemetryEvent, get_pipeline
+from .types import PolicyDecision, PolicyEngine, PolicyInput, PolicyPrincipal, PolicyResource
+
+if TYPE_CHECKING:
+    from claude_agent_sdk.types import ToolPermissionContext
+
+logger = logging.getLogger("computeragent.policy")
+
+PrincipalResolver = Callable[["ToolPermissionContext"], PolicyPrincipal]
+ResourceResolver = Callable[["ToolPermissionContext"], PolicyResource]
+ContextResolver = Callable[["ToolPermissionContext"], dict[str, Any]]
+# Async variants are also acceptable — we await whatever the resolver returns
+# in case the user wants to fetch metadata from a database or env.
+PrincipalResolverAsync = Callable[["ToolPermissionContext"], Awaitable[PolicyPrincipal]]
+ResourceResolverAsync = Callable[["ToolPermissionContext"], Awaitable[PolicyResource]]
+ContextResolverAsync = Callable[["ToolPermissionContext"], Awaitable[dict[str, Any]]]
+
+
+class PolicyToolAuthorizer:
+    """``can_use_tool`` callable that delegates to a :class:`PolicyEngine`."""
+
+    def __init__(
+        self,
+        *,
+        engine: PolicyEngine,
+        principal_resolver: PrincipalResolver | PrincipalResolverAsync,
+        resource_resolver: ResourceResolver | ResourceResolverAsync | None = None,
+        context_resolver: ContextResolver | ContextResolverAsync | None = None,
+        on_deny: Literal["deny", "interrupt"] = "deny",
+    ) -> None:
+        self._engine = engine
+        self._principal_resolver = principal_resolver
+        self._resource_resolver = resource_resolver
+        self._context_resolver = context_resolver
+        self._on_deny = on_deny
+
+    async def __call__(
+        self,
+        tool_name: str,
+        tool_input: dict[str, Any],
+        context: ToolPermissionContext,
+    ) -> PermissionResultAllow | PermissionResultDeny:
+        started_at = time.monotonic()
+        input_obj = await self._build_input(tool_name, tool_input, context)
+        try:
+            result = await self._engine.evaluate(input_obj)
+        except Exception as exc:  # noqa: BLE001 - engines are user code; never break the agent
+            # The engine's own fail_mode would normally swallow this, but if
+            # the engine itself misbehaves (unhandled), default to deny.
+            logger.warning(
+                "policy engine %r raised unexpectedly; denying",
+                type(self._engine).__name__,
+                exc_info=True,
+            )
+            permission = PermissionResultDeny(
+                message=f"policy engine error: {exc}",
+                interrupt=self._on_deny == "interrupt",
+            )
+            await self._emit_telemetry(input_obj, None, exc, started_at)
+            return permission
+
+        await self._emit_telemetry(input_obj, result, None, started_at)
+
+        if result.decision == PolicyDecision.ALLOW:
+            return PermissionResultAllow(updated_input=tool_input)
+        return PermissionResultDeny(
+            message=result.reason or "denied by policy",
+            interrupt=self._on_deny == "interrupt",
+        )
+
+    # ── helpers ────────────────────────────────────────────────────────────
+
+    async def _build_input(
+        self,
+        tool_name: str,
+        tool_input: dict[str, Any],
+        context: ToolPermissionContext,
+    ) -> PolicyInput:
+        from .types import PolicyAction  # local import to keep module surface tidy
+
+        principal = await _maybe_await(self._principal_resolver(context))
+        resource: PolicyResource
+        if self._resource_resolver is not None:
+            resource = await _maybe_await(self._resource_resolver(context))
+        else:
+            resource = PolicyResource(
+                type="agent",
+                session_id=getattr(context, "session_id", "") or "",
+            )
+        ctx: dict[str, Any]
+        if self._context_resolver is not None:
+            ctx = await _maybe_await(self._context_resolver(context))
+        else:
+            ctx = {"session_id": getattr(context, "session_id", "") or ""}
+
+        return PolicyInput(
+            principal=principal,
+            action=PolicyAction(
+                name="tool_use",
+                tool_name=tool_name,
+                tool_input=dict(tool_input or {}),
+            ),
+            resource=resource,
+            context=ctx,
+        )
+
+    async def _emit_telemetry(
+        self,
+        input_obj: PolicyInput,
+        result: Any,
+        error: BaseException | None,
+        started_at: float,
+    ) -> None:
+        latency_ms = (time.monotonic() - started_at) * 1000.0
+        try:
+            event = TelemetryEvent.policy_decision(
+                input=input_obj,
+                result=result,
+                error=error,
+                latency_ms=latency_ms,
+                engine_name=getattr(self._engine, "name", type(self._engine).__name__),
+            )
+            await get_pipeline().emit(event)
+        except Exception:  # noqa: BLE001
+            logger.debug("policy_decision telemetry emit failed", exc_info=True)
+
+
+async def _maybe_await(value: Any) -> Any:
+    """Allow resolvers to be either sync (return a value) or async (return a coroutine)."""
+    if hasattr(value, "__await__"):
+        return await value
+    return value

computeragent/policy/cedar.py

@@ -0,0 +1,182 @@
+"""``CedarPolicyEngine`` — in-process Cedar evaluation via ``cedarpy``.
+
+Cedar policies and entities are compiled / loaded at engine construction.
+Each ``evaluate`` call translates :class:`PolicyInput` into Cedar's request
+shape, then calls ``cedarpy.is_authorized``.
+
+Translation rules:
+
+* ``PolicyPrincipal(id="alice", groups=["engineer"])``
+  → ``User::"alice"`` with parents ``[Group::"engineer", ...]``.
+* ``PolicyAction(name="tool_use", tool_name="Read")``
+  → ``Action::"toolUse"`` with attribute ``tool: "Read"``.
+* ``PolicyResource(type="agent", agent_name="nordassist")``
+  → ``Agent::"nordassist"``.
+
+Optional extra: ``pip install 'computer-agent-py[cedar]'``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+try:
+    import cedarpy as _cedarpy
+except ImportError as _exc:  # pragma: no cover - guarded by lazy attribute
+    raise ImportError(
+        "CedarPolicyEngine requires the [cedar] extra. "
+        "Install with: pip install 'computer-agent-py[cedar]'"
+    ) from _exc
+
+from .types import FailMode, PolicyDecision, PolicyInput, PolicyResult
+
+logger = logging.getLogger("computeragent.policy")
+
+
+class CedarPolicyEngine:
+    """Local Cedar engine. No network calls.
+
+    Pass either ``policies`` (one or more Cedar policy texts) or ``schema``
+    (Cedar schema text). ``entities`` is an optional pre-loaded list using
+    cedarpy's entity dict shape; per-request entities (one for principal,
+    action, and resource) are merged in automatically.
+    """
+
+    name = "cedar"
+
+    def __init__(
+        self,
+        *,
+        policies: str | list[str],
+        entities: list[dict[str, Any]] | None = None,
+        schema: str | None = None,
+        fail_mode: FailMode = "deny",
+    ) -> None:
+        self._policies = "\n".join(policies) if isinstance(policies, list) else policies
+        self._schema = schema
+        self._static_entities = list(entities or [])
+        self._fail_mode = fail_mode
+
+        # Fail fast on policy parse errors at startup, not at first request.
+        try:
+            _cedarpy.format_policies(self._policies)
+        except Exception as exc:  # noqa: BLE001 - cedarpy raises various types
+            raise ValueError(f"Cedar policy parse error: {exc}") from exc
+
+    async def evaluate(self, input: PolicyInput) -> PolicyResult:
+        try:
+            request, entities = _build_request_and_entities(input, self._static_entities)
+            result = _cedarpy.is_authorized(
+                request=request,
+                policies=self._policies,
+                entities=entities,
+                schema=self._schema,
+            )
+            allow = result.decision == _cedarpy.Decision.Allow
+            reasons = list(getattr(result.diagnostics, "reasons", []) or [])
+            errors = list(getattr(result.diagnostics, "errors", []) or [])
+            reason_parts: list[str] = []
+            if reasons:
+                reason_parts.append(f"policies={','.join(reasons)}")
+            if errors:
+                reason_parts.append(f"errors={','.join(str(e) for e in errors)}")
+            reason = "; ".join(reason_parts) or ("cedar allowed" if allow else "cedar denied")
+            return PolicyResult(
+                decision=PolicyDecision.ALLOW if allow else PolicyDecision.DENY,
+                reason=reason,
+                engine=self.name,
+            )
+        except Exception as exc:  # noqa: BLE001 - cedarpy raises bare exceptions
+            return self._failure_result(exc)
+
+    async def aclose(self) -> None:
+        # Nothing to close — cedarpy is purely in-process.
+        return
+
+    # ── helpers ────────────────────────────────────────────────────────────
+
+    def _failure_result(self, exc: BaseException) -> PolicyResult:
+        if self._fail_mode == "allow":
+            logger.warning("Cedar policy engine error; fail_mode=allow → allowing: %s", exc)
+            return PolicyResult(
+                decision=PolicyDecision.ALLOW,
+                reason=f"policy engine unavailable (fail_mode=allow): {exc}",
+                engine=self.name,
+            )
+        logger.warning("Cedar policy engine error; fail_mode=deny → denying: %s", exc)
+        return PolicyResult(
+            decision=PolicyDecision.DENY,
+            reason=f"policy engine unavailable: {exc}",
+            engine=self.name,
+        )
+
+
+def _build_request_and_entities(
+    input: PolicyInput,
+    static_entities: list[dict[str, Any]],
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    """Translate a PolicyInput into cedarpy's ``request`` + ``entities`` shape."""
+    user_uid = {"type": "User", "id": input.principal.id or "anonymous"}
+    agent_uid = {
+        "type": "Agent",
+        "id": input.resource.agent_name or input.resource.session_id or "anonymous",
+    }
+
+    # Build the per-request entities: principal + groups + agent.
+    group_entities: list[dict[str, Any]] = [
+        {"uid": {"type": "Group", "id": g}, "attrs": {}, "parents": []}
+        for g in input.principal.groups
+    ]
+    principal_entity = {
+        "uid": user_uid,
+        "attrs": _coerce_attrs(input.principal.attributes),
+        "parents": [{"type": "Group", "id": g} for g in input.principal.groups],
+    }
+    resource_entity = {
+        "uid": agent_uid,
+        "attrs": _coerce_attrs(
+            {
+                "model": input.resource.model,
+                "session_id": input.resource.session_id,
+                **(input.resource.attributes or {}),
+            }
+        ),
+        "parents": [],
+    }
+    # Cedar's action attributes live on the action entity itself; tool_name
+    # is the most useful key to expose for `when` clauses like
+    # `action.tool == "Read"`.
+    action_entity = {
+        "uid": {"type": "Action", "id": "toolUse"},
+        "attrs": _coerce_attrs(
+            {
+                "tool": input.action.tool_name,
+                # tool_input is omitted from attrs by default — Cedar prefers
+                # primitives, and tool inputs can be arbitrary dicts. Users
+                # who want to write policies against tool inputs should
+                # supply a context_resolver that flattens specific keys.
+            }
+        ),
+        "parents": [],
+    }
+    entities = [
+        *static_entities,
+        principal_entity,
+        resource_entity,
+        action_entity,
+        *group_entities,
+    ]
+
+    request = {
+        "principal": f'User::"{user_uid["id"]}"',
+        "action": 'Action::"toolUse"',
+        "resource": f'Agent::"{agent_uid["id"]}"',
+        "context": _coerce_attrs(input.context),
+    }
+    return request, entities
+
+
+def _coerce_attrs(attrs: dict[str, Any]) -> dict[str, Any]:
+    """Drop None values; Cedar treats missing attribute as ``has`` = false."""
+    return {k: v for k, v in attrs.items() if v is not None and v != ""}

computeragent/policy/opa.py

@@ -0,0 +1,124 @@
+"""``OpaPolicyEngine`` — remote-HTTP OPA backend.
+
+POSTs to ``{url}/v1/data/{policy_path}`` with body ``{"input": <PolicyInput>}``.
+Parses OPA's response in either of two common shapes:
+
+* ``{"result": true | false}`` — bare boolean decision.
+* ``{"result": {"allow": bool, "reason": str?, "obligations": list?}}`` —
+  object form with optional reason / advisory obligations.
+
+Failure modes (network error, timeout, non-2xx, malformed JSON) honour
+``fail_mode=`` — DENY by default, ``"allow"`` for non-prod environments.
+Uses ``httpx`` which is already a core dependency, so no extra to install.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, cast
+
+import httpx
+
+from .types import FailMode, PolicyDecision, PolicyInput, PolicyResult
+
+logger = logging.getLogger("computeragent.policy")
+
+
+class OpaPolicyEngine:
+    """Open Policy Agent backend over OPA's REST data API.
+
+    Parameters mirror an OPA sidecar deployment. The ``policy_path`` is the
+    period-or-slash-separated path under ``/v1/data``: e.g. for a Rego file
+    ``package computeragent.tools`` with rule ``allow``, set
+    ``policy_path="computeragent/tools/allow"``.
+    """
+
+    name = "opa"
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        policy_path: str,
+        fail_mode: FailMode = "deny",
+        timeout: float = 2.0,
+        headers: dict[str, str] | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._url = url.rstrip("/")
+        self._policy_path = policy_path.strip("/").replace(".", "/")
+        self._fail_mode = fail_mode
+        self._timeout = timeout
+        self._headers = headers or {}
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+
+    async def evaluate(self, input: PolicyInput) -> PolicyResult:
+        endpoint = f"{self._url}/v1/data/{self._policy_path}"
+        body = {"input": input.to_json()}
+        try:
+            response = await self._client.post(
+                endpoint,
+                json=body,
+                headers=self._headers,
+                timeout=self._timeout,
+            )
+            response.raise_for_status()
+            payload = response.json()
+        except (httpx.HTTPError, ValueError) as exc:
+            # Connection error, timeout, non-2xx, JSON decode failure.
+            return self._failure_result(exc)
+
+        return self._parse_result(payload)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            try:
+                await self._client.aclose()
+            except Exception:  # noqa: BLE001 - cleanup must not raise
+                logger.debug("opa client aclose failed", exc_info=True)
+
+    # ── helpers ────────────────────────────────────────────────────────────
+
+    def _parse_result(self, payload: dict[str, Any]) -> PolicyResult:
+        result_val = payload.get("result")
+        if isinstance(result_val, bool):
+            return PolicyResult(
+                decision=PolicyDecision.ALLOW if result_val else PolicyDecision.DENY,
+                reason="opa allowed" if result_val else "opa denied",
+                engine=self.name,
+            )
+        if isinstance(result_val, dict):
+            allow = bool(result_val.get("allow", False))
+            reason = str(result_val.get("reason") or "")
+            obligations_raw = result_val.get("obligations") or []
+            obligations: list[dict[str, Any]] = []
+            if isinstance(obligations_raw, list):
+                obligations = [
+                    cast("dict[str, Any]", o) for o in obligations_raw if isinstance(o, dict)
+                ]
+            return PolicyResult(
+                decision=PolicyDecision.ALLOW if allow else PolicyDecision.DENY,
+                reason=reason or ("opa allowed" if allow else "opa denied"),
+                obligations=obligations,
+                engine=self.name,
+            )
+        # Unknown shape — treat as deny with diagnostics.
+        return self._failure_result(
+            ValueError(f"unexpected OPA result shape: {type(result_val).__name__}")
+        )
+
+    def _failure_result(self, exc: BaseException) -> PolicyResult:
+        if self._fail_mode == "allow":
+            logger.warning("OPA policy engine error; fail_mode=allow → allowing: %s", exc)
+            return PolicyResult(
+                decision=PolicyDecision.ALLOW,
+                reason=f"policy engine unavailable (fail_mode=allow): {exc}",
+                engine=self.name,
+            )
+        logger.warning("OPA policy engine error; fail_mode=deny → denying: %s", exc)
+        return PolicyResult(
+            decision=PolicyDecision.DENY,
+            reason=f"policy engine unavailable: {exc}",
+            engine=self.name,
+        )