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

PiperOrigin-RevId: 929389871

Author: google-genai-bot

src/google/adk/environment/_base_environment.py

@@ -58,17 +58,6 @@ 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,7 +59,6 @@ def __init__(
     self._working_dir = working_dir
     self._env_vars = env_vars
     self._auto_created = False
-    self._is_initialized = False
 
   @property
   @override
@@ -76,15 +75,13 @@ 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(
@@ -141,21 +138,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) -> Path:
+  def _resolve_path(self, path: str | Path) -> str:
     """Resolve a relative path against the working directory."""
-    path_obj = Path(path)
-    if path_obj.is_absolute():
-      return path_obj
-    return self.working_dir / path_obj
+    path = str(path)
+    if os.path.isabs(path):
+      return path
+    return os.path.join(self._working_dir, path)
 
   @staticmethod
-  def _sync_read(path: Path) -> bytes:
+  def _sync_read(path: str) -> bytes:
     with open(path, 'rb') as f:
       return f.read()
 
   @staticmethod
-  def _sync_write(path: Path, content: str | bytes) -> None:
-    os.makedirs(path.parent, exist_ok=True)
+  def _sync_write(path: str, content: str | bytes) -> None:
+    os.makedirs(os.path.dirname(path), 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,35 +20,12 @@
 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:
@@ -62,7 +39,7 @@ def _make_feature_decorator(
     default_message: str,
     block_usage: bool = False,
     bypass_env_var: Optional[str] = None,
-) -> _FeatureDecorator:
+) -> Callable[..., Any]:
   def decorator_factory(message_or_obj: Any = None) -> Any:
     # Case 1: Used as @decorator without parentheses
     # message_or_obj is the decorated class/function
@@ -80,7 +57,7 @@ def decorator_factory(message_or_obj: Any = None) -> Any:
     )
     return _create_decorator(message, label, block_usage, bypass_env_var)
 
-  return cast(_FeatureDecorator, decorator_factory)
+  return decorator_factory
 
 
 def _create_decorator(