fix: add artifacts in each agent's .adk folder

The local artifact service wrote to a single <agents_dir>/.adk/artifacts
root shared by all agents, while session storage is per-agent under
<agents_dir>/<agent>/.adk. Route artifacts the same way so each agent's
artifacts live next to its session.db.

For adk web/api_server this moves the default artifact location to
<agents_dir>/<agent>/.adk/artifacts. To stay backward compatible,
PerAgentFileArtifactService falls back to reading the old shared root on
a miss, so existing artifacts keep loading; new writes go per-agent
(copy-on-write migration). create_artifact_service_from_options logs a
WARNING when a legacy shared root is found, pointing users at the manual
move (the users/ dir into <agent>/.adk/artifacts). adk run is unaffected
(it already resolved to the per-agent path).

Also harden _resolve_agent_dir to use Path.is_relative_to instead of a
string-prefix check, which accepted prefix-sharing siblings (e.g.
app_name "../agents_evil" under an "agents" root). This guards both the
artifact and session per-agent paths.

Change-Id: Ib1b911fa35de00ebf8335a0825a03bb98dfab336

Author: GWeale

src/google/adk/cli/cli.py

@@ -321,8 +321,9 @@ def _setup_runner_context(
   )
 
   artifact_service = create_artifact_service_from_options(
-      base_dir=agent_root,
+      base_dir=agent_parent_path,
       artifact_service_uri=artifact_service_uri,
+      app_name_to_dir=app_name_to_dir,
       use_local_storage=use_local_storage,
   )
   memory_service = create_memory_service_from_options(

src/google/adk/cli/utils/dot_adk_folder.py

@@ -23,7 +23,7 @@ def _resolve_agent_dir(*, agents_root: Path | str, app_name: str) -> Path:
   """Resolves the agent directory with safety checks."""
   agents_root_path = Path(agents_root).resolve()
   agent_dir = (agents_root_path / app_name).resolve()
-  if not str(agent_dir).startswith(str(agents_root_path)):
+  if not agent_dir.is_relative_to(agents_root_path):
     raise ValueError(
         f"Invalid app_name '{app_name}': resolves outside base directory"
     )

src/google/adk/cli/utils/local_storage.py

@@ -22,8 +22,10 @@
 from typing import Mapping
 from typing import Optional
 
+from google.genai import types
 from typing_extensions import override
 
+from ...artifacts.base_artifact_service import ArtifactVersion
 from ...artifacts.base_artifact_service import BaseArtifactService
 from ...artifacts.file_artifact_service import FileArtifactService
 from ...events.event import Event
@@ -37,6 +39,7 @@
 logger = logging.getLogger("google_adk." + __name__)
 
 _BUILT_IN_SESSION_SERVICE_KEY = "__adk_built_in_session_service__"
+_BUILT_IN_ARTIFACT_SERVICE_KEY = "__adk_built_in_artifact_service__"
 
 
 def create_local_database_session_service(
@@ -95,16 +98,31 @@ def create_local_session_service(
 
 
 def create_local_artifact_service(
-    *, base_dir: Path | str
+    *,
+    base_dir: Path | str,
+    per_agent: bool = False,
+    app_name_to_dir: Optional[Mapping[str, str]] = None,
 ) -> BaseArtifactService:
-  """Creates a file-backed artifact service rooted in `.adk/artifacts`.
+  """Creates a file-backed artifact service that persists data in `.adk/artifacts` folders.
 
   Args:
     base_dir: Directory whose `.adk` folder will store artifacts.
+    per_agent: If True, creates a PerAgentFileArtifactService that stores
+      artifacts in each agent's `.adk/artifacts` folder. If False, creates a
+      single FileArtifactService at base_dir/.adk/artifacts.
+    app_name_to_dir: Optional mapping from logical app name to on-disk agent
+      folder name. Only used when per_agent is True; defaults to identity.
 
   Returns:
-    A `FileArtifactService` scoped to the derived root directory.
+    A `BaseArtifactService` backed by the local filesystem.
   """
+  if per_agent:
+    logger.info("Using per-agent artifact storage rooted at %s", base_dir)
+    return PerAgentFileArtifactService(
+        agents_root=base_dir,
+        app_name_to_dir=app_name_to_dir,
+    )
+
   manager = DotAdkFolder(base_dir)
   artifact_root = manager.artifacts_dir
   artifact_root.mkdir(parents=True, exist_ok=True)
@@ -217,3 +235,242 @@ async def get_user_state(
   async def append_event(self, session: Session, event: Event) -> Event:
     service = await self._get_service(session.app_name)
     return await service.append_event(session, event)
+
+
+class PerAgentFileArtifactService(BaseArtifactService):
+  """Routes artifact storage to per-agent `.adk/artifacts` folders."""
+
+  def __init__(
+      self,
+      *,
+      agents_root: Path | str,
+      app_name_to_dir: Optional[Mapping[str, str]] = None,
+  ):
+    self._agents_root = Path(agents_root).resolve()
+    self._app_name_to_dir = dict(app_name_to_dir or {})
+    self._services: dict[str, BaseArtifactService] = {}
+    self._legacy_service: Optional[BaseArtifactService] = None
+    self._service_lock = asyncio.Lock()
+
+  async def _get_service(self, app_name: str) -> BaseArtifactService:
+    async with self._service_lock:
+      if app_name.startswith("__"):
+        storage_key = _BUILT_IN_ARTIFACT_SERVICE_KEY
+        base_dir = self._agents_root
+      else:
+        storage_key = self._app_name_to_dir.get(app_name, app_name)
+        folder = dot_adk_folder_for_agent(
+            agents_root=self._agents_root, app_name=storage_key
+        )
+        base_dir = folder.agent_dir
+
+      service = self._services.get(storage_key)
+      if service is not None:
+        return service
+
+      service = create_local_artifact_service(base_dir=base_dir)
+      self._services[storage_key] = service
+      return service
+
+  async def _get_legacy_service(
+      self, app_name: str
+  ) -> Optional[BaseArtifactService]:
+    """Returns a reader for the pre-per-agent shared `.adk/artifacts` root.
+
+    Returns None for built-in agents (which already use that root) and when
+    no legacy directory exists, so reads fall back only when there is legacy
+    data to find. Never creates the legacy directory.
+    """
+    if app_name.startswith("__"):
+      return None
+    if self._legacy_service is not None:
+      return self._legacy_service
+    legacy_dir = DotAdkFolder(self._agents_root).artifacts_dir
+    if not legacy_dir.exists():
+      return None
+    async with self._service_lock:
+      if self._legacy_service is None:
+        self._legacy_service = FileArtifactService(root_dir=legacy_dir)
+      return self._legacy_service
+
+  @override
+  async def save_artifact(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      filename: str,
+      artifact: types.Part | dict[str, Any],
+      session_id: Optional[str] = None,
+      custom_metadata: Optional[dict[str, Any]] = None,
+  ) -> int:
+    service = await self._get_service(app_name)
+    return await service.save_artifact(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        artifact=artifact,
+        session_id=session_id,
+        custom_metadata=custom_metadata,
+    )
+
+  @override
+  async def load_artifact(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      filename: str,
+      session_id: Optional[str] = None,
+      version: Optional[int] = None,
+  ) -> Optional[types.Part]:
+    service = await self._get_service(app_name)
+    result = await service.load_artifact(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        session_id=session_id,
+        version=version,
+    )
+    if result is not None:
+      return result
+    legacy = await self._get_legacy_service(app_name)
+    if legacy is None:
+      return None
+    return await legacy.load_artifact(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        session_id=session_id,
+        version=version,
+    )
+
+  @override
+  async def list_artifact_keys(
+      self, *, app_name: str, user_id: str, session_id: Optional[str] = None
+  ) -> list[str]:
+    service = await self._get_service(app_name)
+    keys = await service.list_artifact_keys(
+        app_name=app_name, user_id=user_id, session_id=session_id
+    )
+    legacy = await self._get_legacy_service(app_name)
+    if legacy is None:
+      return keys
+    legacy_keys = await legacy.list_artifact_keys(
+        app_name=app_name, user_id=user_id, session_id=session_id
+    )
+    return sorted(set(keys) | set(legacy_keys))
+
+  @override
+  async def delete_artifact(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      filename: str,
+      session_id: Optional[str] = None,
+  ) -> None:
+    service = await self._get_service(app_name)
+    await service.delete_artifact(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        session_id=session_id,
+    )
+    # Also delete any legacy copy so a deleted artifact can't reappear via the
+    # read fallback.
+    legacy = await self._get_legacy_service(app_name)
+    if legacy is not None:
+      await legacy.delete_artifact(
+          app_name=app_name,
+          user_id=user_id,
+          filename=filename,
+          session_id=session_id,
+      )
+
+  @override
+  async def list_versions(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      filename: str,
+      session_id: Optional[str] = None,
+  ) -> list[int]:
+    service = await self._get_service(app_name)
+    versions = await service.list_versions(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        session_id=session_id,
+    )
+    if versions:
+      return versions
+    legacy = await self._get_legacy_service(app_name)
+    if legacy is None:
+      return versions
+    return await legacy.list_versions(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        session_id=session_id,
+    )
+
+  @override
+  async def list_artifact_versions(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      filename: str,
+      session_id: Optional[str] = None,
+  ) -> list[ArtifactVersion]:
+    service = await self._get_service(app_name)
+    versions = await service.list_artifact_versions(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        session_id=session_id,
+    )
+    if versions:
+      return versions
+    legacy = await self._get_legacy_service(app_name)
+    if legacy is None:
+      return versions
+    return await legacy.list_artifact_versions(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        session_id=session_id,
+    )
+
+  @override
+  async def get_artifact_version(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      filename: str,
+      session_id: Optional[str] = None,
+      version: Optional[int] = None,
+  ) -> Optional[ArtifactVersion]:
+    service = await self._get_service(app_name)
+    result = await service.get_artifact_version(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        session_id=session_id,
+        version=version,
+    )
+    if result is not None:
+      return result
+    legacy = await self._get_legacy_service(app_name)
+    if legacy is None:
+      return None
+    return await legacy.get_artifact_version(
+        app_name=app_name,
+        user_id=user_id,
+        filename=filename,
+        session_id=session_id,
+        version=version,
+    )

src/google/adk/cli/utils/service_factory.py

@@ -27,6 +27,7 @@
 from ...sessions.base_session_service import BaseSessionService
 from ...utils.env_utils import is_env_enabled
 from ..service_registry import get_service_registry
+from .dot_adk_folder import DotAdkFolder
 from .local_storage import create_local_artifact_service
 from .local_storage import create_local_session_service
 
@@ -273,6 +274,7 @@ def create_artifact_service_from_options(
     base_dir: Path | str,
     artifact_service_uri: str | None = None,
     strict_uri: bool = False,
+    app_name_to_dir: dict[str, str] | None = None,
     use_local_storage: bool = True,
 ) -> BaseArtifactService:
   """Creates an artifact service based on CLI/web options."""
@@ -312,8 +314,22 @@ def create_artifact_service_from_options(
         "Set --artifact_service_uri for production deployments."
     )
 
+  # Default to per-agent local storage in <agents_root>/<agent>/.adk/artifacts.
+  legacy_artifacts_dir = DotAdkFolder(base_path).artifacts_dir
+  if legacy_artifacts_dir.exists():
+    logger.warning(
+        "Found legacy shared artifacts at %s. Artifacts now persist"
+        " per-agent under <agent>/.adk/artifacts and legacy artifacts remain"
+        " readable via fallback. To migrate, move the 'users' directory into"
+        " the agent's .adk/artifacts folder.",
+        legacy_artifacts_dir,
+    )
   try:
-    return create_local_artifact_service(base_dir=base_path)
+    return create_local_artifact_service(
+        base_dir=base_path,
+        per_agent=True,
+        app_name_to_dir=app_name_to_dir,
+    )
   except OSError as exc:
     if exc.errno not in _LOCAL_STORAGE_ERRNOS and not isinstance(
         exc, PermissionError