feat: add adk folder manager and per agent local storage helpers

Creates AdkFolderManager for creating/resetting the .adk layout, helper builders that return SQLite- and filesystembacked services for each agent

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 831206377

tests/unittests/apps/test_apps.py

@@ -19,6 +19,7 @@ from google.adk.agents.context_cache_config import ContextCacheConfig
 from google.adk.apps.app import App
 from google.adk.apps.app import ResumabilityConfig
 from google.adk.plugins.base_plugin import BasePlugin
+import pytest
 
 
 class TestApp:
@@ -168,3 +169,28 @@ class TestApp:
         resumability_config=None,
     )
     assert app.resumability_config is None
+
+  def test_app_rejects_invalid_name(self):
+    """Test that invalid application names are rejected."""
+    mock_agent = Mock(spec=BaseAgent)
+
+    with pytest.raises(ValueError):
+      App(name="../escape_attempt", root_agent=mock_agent)
+
+    with pytest.raises(ValueError):
+      App(name="nested/path", root_agent=mock_agent)
+
+    with pytest.raises(ValueError):
+      App(name="windows\\path", root_agent=mock_agent)
+
+  def test_app_name_must_be_identifier(self):
+    mock_agent = Mock(spec=BaseAgent)
+
+    with pytest.raises(ValueError):
+      App(name="invalid-name", root_agent=mock_agent)
+
+  def test_app_name_cannot_be_user(self):
+    mock_agent = Mock(spec=BaseAgent)
+
+    with pytest.raises(ValueError):
+      App(name="user", root_agent=mock_agent)

tests/unittests/cli/utils/test_dot_adk_folder.py

@@ -0,0 +1,47 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from google.adk.cli.utils.dot_adk_folder import dot_adk_folder_for_agent
+from google.adk.cli.utils.dot_adk_folder import DotAdkFolder
+import pytest
+
+
+def test_paths_are_relative_to_agent_dir(tmp_path: Path):
+  agent_dir = tmp_path / "agent_a"
+  folder = DotAdkFolder(agent_dir)
+
+  assert folder.dot_adk_dir == agent_dir.resolve() / ".adk"
+  assert folder.artifacts_dir == folder.dot_adk_dir / "artifacts"
+  assert folder.session_db_path == folder.dot_adk_dir / "session.db"
+
+
+def test_for_agent_validates_app_name(tmp_path: Path):
+  agents_root = tmp_path / "agents"
+  agents_root.mkdir()
+
+  with pytest.raises(ValueError):
+    dot_adk_folder_for_agent(
+        agents_root=agents_root, app_name="../escape_attempt"
+    )
+
+  folder = dot_adk_folder_for_agent(
+      agents_root=agents_root, app_name="valid_agent"
+  )
+
+  expected_dir = (agents_root / "valid_agent").resolve()
+  assert folder.agent_dir == expected_dir

tests/unittests/cli/utils/test_local_storage.py

@@ -0,0 +1,56 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from google.adk.cli.utils.local_storage import create_local_database_session_service
+from google.adk.cli.utils.local_storage import PerAgentDatabaseSessionService
+from google.adk.sessions.sqlite_session_service import SqliteSessionService
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_per_agent_session_service_creates_scoped_dot_adk(
+    tmp_path: Path,
+) -> None:
+  agent_a = tmp_path / "agent_a"
+  agent_b = tmp_path / "agent_b"
+  agent_a.mkdir()
+  agent_b.mkdir()
+
+  service = PerAgentDatabaseSessionService(agents_root=tmp_path)
+
+  await service.create_session(app_name="agent_a", user_id="user_a")
+  await service.create_session(app_name="agent_b", user_id="user_b")
+
+  assert (agent_a / ".adk" / "session.db").exists()
+  assert (agent_b / ".adk" / "session.db").exists()
+
+  agent_a_sessions = await service.list_sessions(app_name="agent_a")
+  agent_b_sessions = await service.list_sessions(app_name="agent_b")
+
+  assert len(agent_a_sessions.sessions) == 1
+  assert agent_a_sessions.sessions[0].app_name == "agent_a"
+  assert len(agent_b_sessions.sessions) == 1
+  assert agent_b_sessions.sessions[0].app_name == "agent_b"
+
+
+def test_create_local_database_session_service_returns_sqlite(
+    tmp_path: Path,
+) -> None:
+  service = create_local_database_session_service(base_dir=tmp_path)
+
+  assert isinstance(service, SqliteSessionService)