fix(utils): Preserve decorated type for @experimental and @working_in_progress

Merge google#6030

## Summary

The feature decorators (`@experimental`, `@working_in_progress`) were typed as returning `Any`, so any class or function they decorated (e.g. `BaseEnvironment`) was seen as `Any` by type checkers. This erased the base class, producing spurious `"no base method present"` errors on every `@override` in subclasses (`LocalEnvironment`, and any future subclass).

This adds a `_FeatureDecorator` `Protocol` with `@overload` signatures so the decorators preserve the decorated object's type across all three call forms — `@experimental`, `@experimental()`, `@experimental("msg")` — for both classes and functions.

## Impact

- `BaseEnvironment` now resolves as `type[BaseEnvironment]` instead of `Any`.
- `LocalEnvironment`'s 6 spurious `@override` errors drop to 0 (verified with pyright).
- Runtime behavior is unchanged: warnings still fire, class names and callability are preserved.

## Test plan

- [x] `pytest tests/unittests/utils/test_feature_decorator.py` (17 passed)
- [x] `pytest tests/unittests/features/test_feature_decorator.py` (11 passed)
- [x] `pyright src/google/adk/utils/feature_decorator.py` — 0 errors
- [x] Verified `LocalEnvironment` override errors went 6 → 0

Co-authored-by: Wei Sun (Jack) <weisun@google.com>
COPYBARA_INTEGRATE_REVIEW=google#6030 from google:fix/experimental-typing 5bdb8a4
PiperOrigin-RevId: 929281312

Author: 2 people

src/google/adk/environment/_base_environment.py

@@ -58,6 +58,17 @@ class BaseEnvironment(ABC):
     4. Call ``close()`` when done.
   """
 
+  _is_initialized: bool = False
+
+  @property
+  def is_initialized(self) -> bool:
+    """Whether the environment has been initialized."""
+    return self._is_initialized
+
+  @is_initialized.setter
+  def is_initialized(self, value: bool) -> None:
+    self._is_initialized = value
+
   async def initialize(self) -> None:
     """Initialize the environment (e.g. create working directory).
 

src/google/adk/environment/_local_environment.py

@@ -59,6 +59,7 @@ def __init__(
     self._working_dir = working_dir
     self._env_vars = env_vars
     self._auto_created = False
+    self._is_initialized = False
 
   @property
   @override
@@ -75,13 +76,15 @@ async def initialize(self) -> None:
       logger.debug('Created temporary folder: %s', self._working_dir)
     else:
       os.makedirs(self._working_dir, exist_ok=True)
+    self._is_initialized = True
 
   @override
   async def close(self) -> None:
     if self._auto_created and self._working_dir:
       shutil.rmtree(self._working_dir, ignore_errors=True)
       logger.debug('Removed temporary workspace: %s', self._working_dir)
       self._working_dir = None
+    self._is_initialized = False
 
   @override
   async def execute(
@@ -138,21 +141,21 @@ async def write_file(self, path: str | Path, content: str | bytes) -> None:
     resolved = self._resolve_path(path)
     return await asyncio.to_thread(self._sync_write, resolved, content)
 
-  def _resolve_path(self, path: str | Path) -> str:
+  def _resolve_path(self, path: str | Path) -> Path:
     """Resolve a relative path against the working directory."""
-    path = str(path)
-    if os.path.isabs(path):
-      return path
-    return os.path.join(self._working_dir, path)
+    path_obj = Path(path)
+    if path_obj.is_absolute():
+      return path_obj
+    return self.working_dir / path_obj
 
   @staticmethod
-  def _sync_read(path: str) -> bytes:
+  def _sync_read(path: Path) -> bytes:
     with open(path, 'rb') as f:
       return f.read()
 
   @staticmethod
-  def _sync_write(path: str, content: str | bytes) -> None:
-    os.makedirs(os.path.dirname(path), exist_ok=True)
+  def _sync_write(path: Path, content: str | bytes) -> None:
+    os.makedirs(path.parent, exist_ok=True)
     mode = 'w' if isinstance(content, str) else 'wb'
     kwargs = {'encoding': 'utf-8'} if isinstance(content, str) else {}
     with open(path, mode, **kwargs) as f:

src/google/adk/utils/feature_decorator.py

@@ -20,12 +20,35 @@
 from typing import Any
 from typing import cast
 from typing import Optional
+from typing import overload
+from typing import Protocol
 from typing import TypeVar
 import warnings
 
 T = TypeVar("T")
 
 
+class _FeatureDecorator(Protocol):
+  """A feature decorator usable with or without a message argument.
+
+  Preserves the decorated object's type so that subclasses and type
+  checkers continue to see the real class/function rather than ``Any``.
+  """
+
+  # @decorator (bare, on a class or function)
+  @overload
+  def __call__(self, message_or_obj: T) -> T:
+    ...
+
+  # @decorator() or @decorator("message")
+  @overload
+  def __call__(self, message_or_obj: Optional[str] = ...) -> Callable[[T], T]:
+    ...
+
+  def __call__(self, message_or_obj: Any = None) -> Any:
+    ...
+
+
 def _is_truthy_env(var_name: str) -> bool:
   value = os.environ.get(var_name)
   if value is None:
@@ -39,7 +62,7 @@ def _make_feature_decorator(
     default_message: str,
     block_usage: bool = False,
     bypass_env_var: Optional[str] = None,
-) -> Callable[..., Any]:
+) -> _FeatureDecorator:
   def decorator_factory(message_or_obj: Any = None) -> Any:
     # Case 1: Used as @decorator without parentheses
     # message_or_obj is the decorated class/function
@@ -57,7 +80,7 @@ def decorator_factory(message_or_obj: Any = None) -> Any:
     )
     return _create_decorator(message, label, block_usage, bypass_env_var)
 
-  return decorator_factory
+  return cast(_FeatureDecorator, decorator_factory)
 
 
 def _create_decorator(