fix(testing): make a2a_compat_shim resilient to wrong a2a-sdk in /tmp worktrees (#433)

* fix(testing): make a2a_compat_shim resilient to wrong a2a-sdk in /tmp worktrees

Attribute assignments like `pb.Role.user = pb.Role.ROLE_USER` at module
import time would raise AttributeError if a2a-sdk isn't at the pinned
version (>=1.0.1,<1.0.2), propagating through conftest.py's top-level
import and breaking pytest collection entirely. Agents running in fresh
/tmp worktrees with uninitialized environments hit this on PRs #391, #406, #407.

Two changes:
- `a2a_compat_shim.py`: introduce `_proto_alias()` helper that guards each
  attribute alias independently with hasattr + a per-alias RuntimeWarning
  (includes install command) rather than letting AttributeError propagate.
- `conftest.py`: wrap the shim import in try/except (ImportError|AttributeError)
  with a fallback to None; update the autouse fixture to no-op when the shim
  is unavailable, so collection always succeeds and only A2A tests fail.

https://claude.ai/code/session_01AnL37fUet4e3yXt9YBxd7a

* fix(testing): stacklevel=2 in _proto_alias + document _STATE_STRING_MAP asymmetry

stacklevel=2 makes the per-alias warning point at the _proto_alias() call
site in the module body (the useful diagnostic location) rather than at
the warnings.warn() line inside the helper.

Add a comment at _STATE_STRING_MAP explaining that any AttributeError from
the dict literal is caught by conftest.py's import guard, so the different
guard pattern is intentional and collection still succeeds.

https://claude.ai/code/session_01AnL37fUet4e3yXt9YBxd7a

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: bokelley

tests/a2a_compat_shim.py

@@ -25,6 +25,7 @@
 from __future__ import annotations
 
 import sys
+import warnings
 from typing import Any
 
 from a2a import types as pb
@@ -62,26 +63,45 @@
 ]
 
 
+def _proto_alias(cls: Any, src: str, dst: str) -> None:
+    """Set cls.dst = cls.src, warning independently per alias if src is absent.
+
+    Guarding each alias independently avoids partial-patch state: if one
+    source attribute is missing the rest still land, and each missing
+    attribute gets its own actionable warning rather than a group abort.
+    """
+    if not hasattr(cls, src):
+        warnings.warn(
+            f"a2a_compat_shim: {cls.__name__}.{src} not found — "
+            "verify a2a-sdk>=1.0.1,<1.0.2 is installed. "
+            "Run: pip install 'a2a-sdk>=1.0.1,<1.0.2'. A2A tests may fail.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return
+    setattr(cls, dst, getattr(cls, src))
+
+
 # --- Role enum backwards-compat aliases (attribute-level monkey-patch) ---
 # ``Role.user`` / ``Role.agent`` didn't exist on the proto enum; tests
 # referenced them verbatim. Adding them once here means every call site
 # (``role=Role.user``) keeps compiling without per-file edits.
-pb.Role.user = pb.Role.ROLE_USER  # type: ignore[attr-defined]
-pb.Role.agent = pb.Role.ROLE_AGENT  # type: ignore[attr-defined]
+_proto_alias(pb.Role, "ROLE_USER", "user")
+_proto_alias(pb.Role, "ROLE_AGENT", "agent")
 
 
 # --- TaskState backwards-compat aliases ---
 # Tests reference ``TaskState.working`` / ``TaskState.completed`` / etc.
 # Proto enums don't have these symbol-shaped attributes; shim them in.
-pb.TaskState.completed = pb.TaskState.TASK_STATE_COMPLETED  # type: ignore[attr-defined]
-pb.TaskState.failed = pb.TaskState.TASK_STATE_FAILED  # type: ignore[attr-defined]
-pb.TaskState.working = pb.TaskState.TASK_STATE_WORKING  # type: ignore[attr-defined]
-pb.TaskState.submitted = pb.TaskState.TASK_STATE_SUBMITTED  # type: ignore[attr-defined]
-pb.TaskState.input_required = pb.TaskState.TASK_STATE_INPUT_REQUIRED  # type: ignore[attr-defined]
-pb.TaskState.auth_required = pb.TaskState.TASK_STATE_AUTH_REQUIRED  # type: ignore[attr-defined]
-pb.TaskState.canceled = pb.TaskState.TASK_STATE_CANCELED  # type: ignore[attr-defined]
-pb.TaskState.rejected = pb.TaskState.TASK_STATE_REJECTED  # type: ignore[attr-defined]
-pb.TaskState.unknown = pb.TaskState.TASK_STATE_UNSPECIFIED  # type: ignore[attr-defined]
+_proto_alias(pb.TaskState, "TASK_STATE_COMPLETED", "completed")
+_proto_alias(pb.TaskState, "TASK_STATE_FAILED", "failed")
+_proto_alias(pb.TaskState, "TASK_STATE_WORKING", "working")
+_proto_alias(pb.TaskState, "TASK_STATE_SUBMITTED", "submitted")
+_proto_alias(pb.TaskState, "TASK_STATE_INPUT_REQUIRED", "input_required")
+_proto_alias(pb.TaskState, "TASK_STATE_AUTH_REQUIRED", "auth_required")
+_proto_alias(pb.TaskState, "TASK_STATE_CANCELED", "canceled")
+_proto_alias(pb.TaskState, "TASK_STATE_REJECTED", "rejected")
+_proto_alias(pb.TaskState, "TASK_STATE_UNSPECIFIED", "unknown")
 
 
 Role = pb.Role
@@ -125,6 +145,12 @@ def Message(  # noqa: N802 (0.3 fixture shim)
     return pb.Message(**kwargs)
 
 
+# Note: this dict accesses pb.TaskState.TASK_STATE_* directly (no _proto_alias guard).
+# Any AttributeError here propagates out of the module, but conftest.py's
+# `except (ImportError, AttributeError)` catches it and sets _a2a_compat_shim=None,
+# so collection still succeeds. _proto_alias guards only the setattr side-effects;
+# this dict is purely read-only at construction and is only reached when pb.TaskState
+# has the correct 1.0 shape.
 _STATE_STRING_MAP: dict[str, pb.TaskState.ValueType] = {
     "completed": pb.TaskState.TASK_STATE_COMPLETED,
     "failed": pb.TaskState.TASK_STATE_FAILED,

tests/conftest.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings as _warnings
 from pathlib import Path
 from types import UnionType
 from typing import Any
@@ -10,7 +11,18 @@
 # Import the a2a-sdk 1.0 compat shim early so monkey-patches like
 # ``Role.user = ROLE_USER`` and ``TaskStatus.__init__`` string coercion
 # land before any test module constructs those proto types.
-from tests import a2a_compat_shim as _a2a_compat_shim  # noqa: F401
+# Guard with try/except so a missing or wrong-version a2a-sdk doesn't
+# break collection — only A2A tests that actually use the shim will fail.
+try:
+    from tests import a2a_compat_shim as _a2a_compat_shim
+except (ImportError, AttributeError) as _shim_exc:
+    _warnings.warn(
+        f"a2a_compat_shim unavailable ({_shim_exc}); "
+        "run: pip install 'a2a-sdk>=1.0.1,<1.0.2'. A2A tests may fail.",
+        RuntimeWarning,
+        stacklevel=1,
+    )
+    _a2a_compat_shim = None  # type: ignore[assignment]
 
 _INTEGRATION_DIR = (Path(__file__).parent / "integration").resolve()
 
@@ -48,7 +60,7 @@ def _a2a_compat_send_and_aggregate(
     a real a2a-sdk server and must NOT be shimmed — they rely on the
     genuine async-generator contract.
     """
-    if _is_integration_test(request):
+    if _a2a_compat_shim is None or _is_integration_test(request):
         return
     _a2a_compat_shim.patch_send_and_aggregate(monkeypatch)