Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
fix(tool): make read cache backend-aware so Read->Edit works in workspaces (#2092)
nolanchica40487a754ab
diff --git a/src/agentscope/state/_state.py b/src/agentscope/state/_state.pyindex 54c34b2c0..0c44922d1 100644--- a/src/agentscope/state/_state.py+++ b/src/agentscope/state/_state.py@@ -43,24 +43,34 @@ class ToolContext(BaseModel):"""The names of the activated tool groups, each group contains a set oftools."""- async def get_cache(self, file_path: str) -> ReadCacheEntry | None:+ async def get_cache(+ self,+ file_path: str,+ mtime: float | None = None,+ ) -> ReadCacheEntry | None:"""Get cached file content if still valid.Args:- file_path: The absolute path of the file.+ file_path (`str`):+ The absolute path of the file.+ mtime (`float | None`, optional):+ The file's modification time, obtained from the same+ filesystem that read the file, e.g. a workspace backend.+ Falls back to the host filesystem when not provided.Returns:- The cached entry if valid, otherwise None.+ `ReadCacheEntry | None`:+ The cached entry if valid, otherwise None."""# Find the cache entryfor entry in self.read_file_cache:if entry.file_path == file_path:- # Check if cache is still valid- try:- updated_at = await aiofiles.os.path.getmtime(file_path)- except Exception:- updated_at = None+ if mtime is None:+ try:+ mtime = await aiofiles.os.path.getmtime(file_path)+ except Exception:+ mtime = None# Concurrent calls may have reordered or dropped the entry# while awaiting, so locate it again by the object itself.@@ -68,7 +78,7 @@ class ToolContext(BaseModel):return Noneself.read_file_cache.remove(entry)- if updated_at != entry.updated_at:+ if mtime != entry.updated_at:# Cache is outdated, or the file no longer existsreturn None@@ -77,18 +87,30 @@ class ToolContext(BaseModel):return entryreturn None- async def cache_file(self, file_path: str, lines: list[str]) -> None:+ async def cache_file(+ self,+ file_path: str,+ lines: list[str],+ mtime: float | None = None,+ ) -> None:"""Cache file content with LRU eviction.Args:- file_path: The absolute path of the file.- lines: The lines of the file content.+ file_path (`str`):+ The absolute path of the file.+ lines (`list[str]`):+ The lines of the file content.+ mtime (`float | None`, optional):+ The file's modification time, obtained from the same+ filesystem that read the file, e.g. a workspace backend.+ Falls back to the host filesystem when not provided."""- try:- updated_at = await aiofiles.os.path.getmtime(file_path)- except Exception:- # Cannot get mtime, skip caching- return+ if mtime is None:+ try:+ mtime = await aiofiles.os.path.getmtime(file_path)+ except Exception:+ # Cannot get mtime, skip caching+ return# Calculate size in KBnew_entry_bytes = (@@ -119,7 +141,7 @@ class ToolContext(BaseModel):self.read_file_cache.append(ReadCacheEntry(lines=lines,- updated_at=updated_at,+ updated_at=mtime,bytes=new_entry_bytes,file_path=file_path,),diff --git a/src/agentscope/tool/_builtin/_edit.py b/src/agentscope/tool/_builtin/_edit.pyindex d9765c240..4753a84bd 100644--- a/src/agentscope/tool/_builtin/_edit.py+++ b/src/agentscope/tool/_builtin/_edit.py@@ -301,7 +301,13 @@ Usage:content = Noneif _agent_state is not None:- cache = await _agent_state.tool_context.get_cache(file_path)+ # Take the mtime from the backend that reads the file, so the+ # cache also works for sandbox-only paths.+ mtime = await self._backend.stat_mtime(file_path)+ cache = await _agent_state.tool_context.get_cache(+ file_path,+ mtime=mtime,+ )if cache is None:# Haven't read this file beforereturn ToolChunk(diff --git a/src/agentscope/tool/_builtin/_read.py b/src/agentscope/tool/_builtin/_read.pyindex 2d90e2330..f6167ad73 100644--- a/src/agentscope/tool/_builtin/_read.py+++ b/src/agentscope/tool/_builtin/_read.py@@ -500,7 +500,13 @@ Usage:# Read file content via backendlines = Noneif _agent_state is not None:- cache = await _agent_state.tool_context.get_cache(file_path)+ # Take the mtime from the backend that reads the file, so+ # the cache also works for sandbox-only paths.+ mtime = await self._backend.stat_mtime(file_path)+ cache = await _agent_state.tool_context.get_cache(+ file_path,+ mtime=mtime,+ )if cache is not None:lines = cache.lines@@ -518,6 +524,7 @@ Usage:await _agent_state.tool_context.cache_file(file_path=file_path,lines=lines,+ mtime=mtime,)# Apply offset and limit (offset is 1-based)diff --git a/src/agentscope/tool/_builtin/_write.py b/src/agentscope/tool/_builtin/_write.pyindex 83e6b5cfb..d39d03344 100644--- a/src/agentscope/tool/_builtin/_write.py+++ b/src/agentscope/tool/_builtin/_write.py@@ -254,7 +254,13 @@ Usage:await self._backend.file_exists(file_path)and _agent_state is not None):- cache = await _agent_state.tool_context.get_cache(file_path)+ # Take the mtime from the backend that reads the file, so the+ # cache also works for sandbox-only paths.+ mtime = await self._backend.stat_mtime(file_path)+ cache = await _agent_state.tool_context.get_cache(+ file_path,+ mtime=mtime,+ )if cache is None:return ToolChunk(content=[diff --git a/tests/builtin_file_cache_backend_test.py b/tests/builtin_file_cache_backend_test.pynew file mode 100644index 000000000..d178ff650--- /dev/null+++ b/tests/builtin_file_cache_backend_test.py@@ -0,0 +1,148 @@+# -*- coding: utf-8 -*-+"""Read cache tests for files that only exist inside a workspace backend."""+import os+from unittest.async_case import IsolatedAsyncioTestCase++from agentscope.state import AgentState+from agentscope.tool import Edit, Read, Write+from agentscope.tool._builtin._backend import BackendBase, ExecResult+++class _MemoryBackend(BackendBase):+ """A backend whose paths do NOT exist on the host filesystem.++ Mirrors a sandbox backend such as ``DockerWorkspace``: files live only+ in the backend, so the host cannot stat them.+ """++ def __init__(self) -> None:+ """Initialize the in-memory file store."""+ self._files: dict[str, bytes] = {}+ self._mtimes: dict[str, float] = {}++ async def exec_shell(+ self,+ command: list[str],+ *,+ cwd: str | None = None,+ timeout: float | None = None,+ ) -> ExecResult:+ """Pretend any command succeeds, e.g. ``mkdir -p`` for parents."""+ return ExecResult(exit_code=0, stdout=b"", stderr=b"")++ async def read_file(self, path: str) -> bytes:+ """Return the stored content for ``path``."""+ return self._files[path]++ async def write_file(self, path: str, data: bytes) -> None:+ """Store ``data`` under ``path`` and bump its mtime."""+ self._files[path] = data+ self._mtimes[path] = self._mtimes.get(path, 1000.0) + 0.001++ async def stat_mtime(self, path: str) -> float | None:+ """Return the backend's own mtime, or None if unknown."""+ return self._mtimes.get(path)++ async def file_exists(self, path: str) -> bool:+ """Return whether ``path`` is in the in-memory store."""+ return path in self._files++ async def is_dir(self, path: str) -> bool:+ """These tests never read a directory."""+ return False++ def isabs(self, path: str) -> bool:+ """Treat any path starting with ``/`` as absolute."""+ return path.startswith("/")++ def dirname(self, path: str) -> str:+ """Return the parent directory of ``path``."""+ return os.path.dirname(path) or "/"+++class BackendAwareCacheTest(IsolatedAsyncioTestCase):+ """Read cache must work for paths that only exist in the backend."""++ async def asyncSetUp(self) -> None:+ """Build tools backed by a sandbox-only memory backend."""+ self.backend = _MemoryBackend()+ self.read_tool = Read(backend=self.backend)+ self.write_tool = Write(backend=self.backend)+ self.edit_tool = Edit(backend=self.backend)+ self.state = AgentState()+ # A path that exists only in the backend, mirroring a+ # DockerWorkspace path like /workspace/test.txt.+ self.path = "/workspace/test.txt"+ await self.backend.write_file(self.path, b"alpha\n")++ async def test_read_caches_backend_only_path(self) -> None:+ """Read must cache a path the host filesystem cannot stat."""+ await self.read_tool(file_path=self.path, _agent_state=self.state)++ self.assertListEqual(+ [+ entry.model_dump()+ for entry in self.state.tool_context.read_file_cache+ ],+ [+ {+ "lines": ["alpha\n"],+ "updated_at": 1000.001,+ "bytes": 6 / 1024,+ "file_path": "/workspace/test.txt",+ },+ ],+ )++ async def test_edit_after_read(self) -> None:+ """Read then Edit must succeed instead of looping, see #2084."""+ await self.read_tool(file_path=self.path, _agent_state=self.state)+ chunk = await self.edit_tool(+ file_path=self.path,+ old_string="alpha",+ new_string="beta",+ _agent_state=self.state,+ )++ self.assertEqual(chunk.state, "running")+ self.assertEqual(await self.backend.read_file(self.path), b"beta\n")++ async def test_write_after_read(self) -> None:+ """Read then Write must not demand a host-side read."""+ await self.read_tool(file_path=self.path, _agent_state=self.state)+ chunk = await self.write_tool(+ file_path=self.path,+ content="gamma\n",+ _agent_state=self.state,+ )++ self.assertEqual(chunk.state, "running")+ self.assertEqual(await self.backend.read_file(self.path), b"gamma\n")++ async def test_edit_without_read(self) -> None:+ """The "must read first" guard still fires with nothing cached."""+ chunk = await self.edit_tool(+ file_path=self.path,+ old_string="alpha",+ new_string="beta",+ _agent_state=self.state,+ )++ self.assertEqual(chunk.state, "error")+ self.assertIn("must first read", chunk.content[0].text)++ async def test_edit_after_backend_side_change(self) -> None:+ """A change made inside the backend must invalidate the cache."""+ await self.read_tool(file_path=self.path, _agent_state=self.state)+ await self.backend.write_file(self.path, b"changed\n")++ chunk = await self.edit_tool(+ file_path=self.path,+ old_string="alpha",+ new_string="beta",+ _agent_state=self.state,+ )++ self.assertEqual(chunk.state, "error")+ self.assertIn("must first read", chunk.content[0].text)+ self.assertListEqual(self.state.tool_context.read_file_cache, [])