Skip to content

Build and run agents you can see, understand and trust.

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.py
index 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 of
tools."""
- 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 entry
for 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 None
self.read_file_cache.remove(entry)
- if updated_at != entry.updated_at:
+ if mtime != entry.updated_at:
# Cache is outdated, or the file no longer exists
return None
@@ -77,18 +87,30 @@ class ToolContext(BaseModel):
return entry
return 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 KB
new_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.py
index d9765c240..4753a84bd 100644
--- a/src/agentscope/tool/_builtin/_edit.py
+++ b/src/agentscope/tool/_builtin/_edit.py
@@ -301,7 +301,13 @@ Usage:
content = None
if _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 before
return ToolChunk(
diff --git a/src/agentscope/tool/_builtin/_read.py b/src/agentscope/tool/_builtin/_read.py
index 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 backend
lines = None
if _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.py
index 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.py
new file mode 100644
index 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, [])