Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(service): add workspace artifact list_dir and read_file endpoints (#2187)
Ziyang Guoe55d4c367c94
diff --git a/src/agentscope/app/_app.py b/src/agentscope/app/_app.pyindex fcda800b3..5f7822c54 100644--- a/src/agentscope/app/_app.py+++ b/src/agentscope/app/_app.py@@ -1,5 +1,6 @@# -*- coding: utf-8 -*-"""AgentScope app factory."""+import secretsfrom typing import Type, TYPE_CHECKING, Anyfrom ._lifespan import lifespan@@ -94,6 +95,7 @@ def create_app(custom_subagent_templates: list[SubAgentTemplate] | None = None,custom_agent_cls: Type[Agent] | None = None,resource_access_policy: ResourceAccessPolicyBase | None = None,+ download_secret: str | None = None,title: str = "AgentScope",version: str = __version__,) -> FastAPI:@@ -227,6 +229,13 @@ def create_app(user. When ``None`` (default), a:class:`DenyAllResourceAccessPolicy` is installed whichpreserves the historical owner-isolated behavior.+ download_secret (`str | None`, optional):+ Signs the short-lived tokens that let a browser download a+ workspace file by navigation. Defaults to a value generated+ per process, which is fine for a single instance but **must+ be set explicitly behind a load balancer** — otherwise a+ token minted by one replica is rejected by the next, and+ downloads fail at random.title (`str`, defaults to ``"AgentScope"``):OpenAPI title shown in the docs UI.version (`str`, defaults to the package version):@@ -257,6 +266,7 @@ def create_app()app.state.mcp_hubs = _index_hubs(mcp_hubs, "MCP")app.state.skill_hubs = _index_hubs(skill_hubs, "skill")+ app.state.download_secret = download_secret or secrets.token_urlsafe(32)# Parser / chunker / blob-store defaults only make sense when the# KB feature is actually enabled. When ``knowledge_base_manager`` isdiff --git a/src/agentscope/app/_router/_schema/__init__.py b/src/agentscope/app/_router/_schema/__init__.pyindex a6ac01b1a..5b649ff40 100644--- a/src/agentscope/app/_router/_schema/__init__.py+++ b/src/agentscope/app/_router/_schema/__init__.py@@ -11,6 +11,8 @@ from ._workspace import (AddFromLibraryResponse,AddSkillRequest,AddSkillsFromLibraryRequest,+ DirectoryEntry,+ DownloadTokenResponse,MCPClientStatus,ToolInfo,)@@ -87,6 +89,8 @@ __all__ = ["AddFromLibraryResponse","AddSkillRequest","AddSkillsFromLibraryRequest",+ "DirectoryEntry",+ "DownloadTokenResponse","MCPClientStatus","ToolInfo",# Agentdiff --git a/src/agentscope/app/_router/_schema/_workspace.py b/src/agentscope/app/_router/_schema/_workspace.pyindex 40b905fa4..65ca5ced9 100644--- a/src/agentscope/app/_router/_schema/_workspace.py+++ b/src/agentscope/app/_router/_schema/_workspace.py@@ -48,6 +48,43 @@ class AddFromLibraryResponse(BaseModel):)+class DirectoryEntry(BaseModel):+ """One entry in a workspace directory listing."""++ name: str = Field(+ description="The entry name, without any leading directory.",+ )+ is_dir: bool = Field(+ description="Whether the entry is itself a directory.",+ )+ size_bytes: int | None = Field(+ default=None,+ description=(+ "File size in bytes. Always null for a directory, and null "+ "for a file the backend could not stat."+ ),+ )+ updated_at: float | None = Field(+ default=None,+ description="Last modification time as a Unix timestamp.",+ )+++class DownloadTokenResponse(BaseModel):+ """A capability authorizing one download of one path."""++ token: str = Field(+ description=(+ "Pass as the ``token`` query parameter of "+ "``GET /workspace/files``, in place of the ``X-User-ID`` "+ "header. Valid for this path only."+ ),+ )+ expires_at: float = Field(+ description="Unix timestamp after which the token is refused.",+ )++class ToolInfo(BaseModel):"""The tool info."""diff --git a/src/agentscope/app/_router/_workspace.py b/src/agentscope/app/_router/_workspace.pyindex 4dcdb2d39..7946f2061 100644--- a/src/agentscope/app/_router/_workspace.py+++ b/src/agentscope/app/_router/_workspace.py@@ -1,24 +1,34 @@# -*- coding: utf-8 -*-"""Workspace router — manage MCP clients and skills on a workspace."""+import mimetypes+from urllib.parse import quote+from fastapi import (APIRouter,Depends,File,Form,+ Header,HTTPException,Query,UploadFile,status,)+from fastapi.responses import StreamingResponsefrom pydantic import ValidationErrorfrom ..deps import (get_current_user_id,+ get_download_secret,get_skill_hubs,get_storage,get_workspace_manager,)from ..hub import SkillHubBase+from .._service._download_token import (+ sign_download_token,+ verify_download_token,+)from .._service._skill_upload import (SkillUploadError,UploadManifest,@@ -36,6 +46,8 @@ from ._schema import (AddFromLibraryResponse,AddSkillRequest,AddSkillsFromLibraryRequest,+ DirectoryEntry,+ DownloadTokenResponse,MCPClientStatus,ToolInfo,)@@ -444,3 +456,192 @@ async def remove_skill(workspace_manager,)await workspace.remove_skill(skill_name)+++# ---------------------------------------------------------------------------+# File browsing endpoints+# ---------------------------------------------------------------------------+++@workspace_router.get("/directories")+async def list_workspace_directory(+ agent_id: str = Query(...),+ session_id: str = Query(...),+ path: str = Query(+ default="",+ description=(+ "Absolute path, or one relative to the workspace root. "+ "Empty lists the workspace root itself."+ ),+ ),+ user_id: str = Depends(get_current_user_id),+ storage: StorageBase = Depends(get_storage),+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),+) -> list[DirectoryEntry]:+ """List one directory level, reachable from a session's workspace.++ Paths are not confined to the workspace root: for a sandboxed+ backend the reachable filesystem is the sandbox, and for a local+ one the caller is already trusted with the host.+ """+ workspace = await _resolve_workspace(+ user_id,+ agent_id,+ session_id,+ storage,+ workspace_manager,+ )+ backend = workspace.get_backend()+ target = backend.abspath(path, cwd=workspace.workdir)++ entry = await backend.stat(target)+ if entry is None:+ raise HTTPException(+ status_code=status.HTTP_404_NOT_FOUND,+ detail="Directory not found.",+ )+ if not entry.is_dir:+ raise HTTPException(+ status_code=status.HTTP_400_BAD_REQUEST,+ detail="Requested path is a file, not a directory.",+ )++ # One call for the whole directory: asking per entry would be one+ # round trip each on a sandboxed backend, times three attributes.+ return [+ DirectoryEntry(+ name=entry.name,+ is_dir=entry.is_dir,+ size_bytes=entry.size_bytes,+ updated_at=entry.mtime,+ )+ for entry in await backend.scandir(target)+ ]+++@workspace_router.post("/files/download-token")+async def create_download_token(+ agent_id: str = Query(...),+ session_id: str = Query(...),+ path: str = Query(..., description="The path the token will authorize."),+ user_id: str = Depends(get_current_user_id),+ storage: StorageBase = Depends(get_storage),+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),+ secret: str = Depends(get_download_secret),+) -> DownloadTokenResponse:+ """Mint a short-lived token for a browser-native download.++ The browser writes the response straight to disk only when it+ issues the request itself, and such a request carries no custom+ header — hence a credential in the URL. Fetching with ``X-User-ID``+ instead works but holds the whole file in the tab.++ Minting depends on the normal identity, so whatever replaces+ ``X-User-ID`` guards this too.++ The session is resolved here only to fail early: the download is a+ browser navigation, so an error there surfaces as a raw error page+ rather than something the UI can show.+ """+ await _resolve_workspace(+ user_id,+ agent_id,+ session_id,+ storage,+ workspace_manager,+ )+ # Signed verbatim, not resolved: the download verifies against the+ # query string it receives, and resolving needs a user the token+ # has not been read yet to supply.+ token, expires_at = sign_download_token(secret, user_id, path)+ return DownloadTokenResponse(token=token, expires_at=expires_at)+++@workspace_router.get("/files")+async def read_workspace_file(+ agent_id: str = Query(...),+ session_id: str = Query(...),+ path: str = Query(+ ...,+ description="Absolute path, or one relative to the workspace root.",+ ),+ download: bool = Query(+ default=False,+ description="Force a Content-Disposition attachment.",+ ),+ token: str+ | None = Query(+ default=None,+ description=(+ "A token from ``POST /workspace/files/download-token``, "+ "accepted in place of the ``X-User-ID`` header so a browser "+ "navigation can download the file directly."+ ),+ ),+ x_user_id: str | None = Header(default=None),+ storage: StorageBase = Depends(get_storage),+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),+ secret: str = Depends(get_download_secret),+) -> StreamingResponse:+ """Stream one file out of a session's workspace.++ The body is piped chunk by chunk rather than read whole: the API+ process is shared, so one large download must not be able to+ exhaust it for everyone else.+ """+ if token is not None:+ try:+ user_id = verify_download_token(secret, token, path)+ except ValueError as e:+ raise HTTPException(+ status_code=status.HTTP_401_UNAUTHORIZED,+ detail=str(e),+ ) from e+ elif x_user_id:+ user_id = x_user_id+ else:+ raise HTTPException(+ status_code=status.HTTP_401_UNAUTHORIZED,+ detail="X-User-ID header or download token is required.",+ )++ workspace = await _resolve_workspace(+ user_id,+ agent_id,+ session_id,+ storage,+ workspace_manager,+ )+ backend = workspace.get_backend()+ target = backend.abspath(path, cwd=workspace.workdir)+ basename = backend.basename(target) or "download"++ entry = await backend.stat(target)+ if entry is None:+ raise HTTPException(+ status_code=status.HTTP_404_NOT_FOUND,+ detail="File not found.",+ )+ if entry.is_dir:+ raise HTTPException(+ status_code=status.HTTP_400_BAD_REQUEST,+ detail="Requested path is a directory, not a file.",+ )++ headers: dict[str, str] = {}+ # Lets the browser show real download progress instead of a+ # spinner of unknown length; omitted when the backend cannot stat.+ if entry.size_bytes is not None:+ headers["Content-Length"] = str(entry.size_bytes)+ if download:+ headers[+ "Content-Disposition"+ ] = f"attachment; filename*=UTF-8''{quote(basename)}"++ return StreamingResponse(+ backend.read_stream(target),+ media_type=(+ mimetypes.guess_type(basename)[0] or "application/octet-stream"+ ),+ headers=headers,+ )diff --git a/src/agentscope/app/_service/_download_token.py b/src/agentscope/app/_service/_download_token.pynew file mode 100644index 000000000..875fceac7--- /dev/null+++ b/src/agentscope/app/_service/_download_token.py@@ -0,0 +1,126 @@+# -*- coding: utf-8 -*-+"""Short-lived capability tokens for browser-native file downloads.++A browser only streams a response to disk when it issues the request+itself — a navigation or ``<a download>`` — and such a request cannot+carry a custom header. Fetching with ``X-User-ID`` and building a blob+works, but buffers the whole file in the tab.++So the credential has to travel in the URL. A token minted here says+"this exact user was already authenticated, and may read this exact+path for the next minute" — a capability, not an identity. Only+``GET /workspace/files`` accepts one, and minting depends on the normal+identity dependency, so swapping in OAuth/JWT later changes where the+capability comes from without touching how it is checked.+"""+import base64+import hashlib+import hmac+import time++# Long enough to survive a slow round trip and the user's click, short+# enough that a token leaked through an access log or browser history+# is already dead. There is no revocation list to fall back on.+DEFAULT_DOWNLOAD_TOKEN_TTL = 60+++def _b64(raw: bytes) -> str:+ """Encode without padding, which is not URL-safe to round-trip."""+ return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")+++def _unb64(text: str) -> bytes:+ """Reverse :func:`_b64`, restoring the stripped padding."""+ return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))+++def _signature(secret: str, expires_at: int, user_id: str, path: str) -> bytes:+ """Compute the MAC binding an expiry, a user and a path together.++ ``\\0`` separates the fields because it cannot occur in any of them,+ so no combination of values can be re-cut into a different triple.++ Args:+ secret (`str`):+ The app-wide signing secret.+ expires_at (`int`):+ Unix timestamp after which the token is refused.+ user_id (`str`):+ The user the capability was granted to.+ path (`str`):+ The one path the capability covers.++ Returns:+ `bytes`:+ The raw HMAC-SHA256 digest.+ """+ message = f"{expires_at}\0{user_id}\0{path}".encode("utf-8")+ return hmac.new(secret.encode("utf-8"), message, hashlib.sha256).digest()+++def sign_download_token(+ secret: str,+ user_id: str,+ path: str,+ ttl: int = DEFAULT_DOWNLOAD_TOKEN_TTL,+) -> tuple[str, int]:+ """Mint a token authorizing one download.++ Args:+ secret (`str`):+ The app-wide signing secret.+ user_id (`str`):+ The already-authenticated caller.+ path (`str`):+ The path the token authorizes, verbatim as the download+ request will send it.+ ttl (`int`, defaults to 60):+ Seconds the token stays valid.++ Returns:+ `tuple[str, int]`:+ The token and its expiry as a Unix timestamp.+ """+ expires_at = int(time.time()) + ttl+ signature = _signature(secret, expires_at, user_id, path)+ token = f"{expires_at}.{_b64(user_id.encode('utf-8'))}.{_b64(signature)}"+ return token, expires_at+++def verify_download_token(secret: str, token: str, path: str) -> str:+ """Return the user a token was granted to, for this path.++ The path is not read out of the token but re-derived from the+ request, so a token for one file cannot be replayed against+ another.++ Args:+ secret (`str`):+ The app-wide signing secret.+ token (`str`):+ The token from the request.+ path (`str`):+ The path the request is asking for.++ Returns:+ `str`:+ The user ID the token was minted for.++ Raises:+ `ValueError`:+ The token is malformed, expired, or does not match.+ """+ try:+ raw_expiry, raw_user, raw_signature = token.split(".")+ expires_at = int(raw_expiry)+ user_id = _unb64(raw_user).decode("utf-8")+ signature = _unb64(raw_signature)+ except (ValueError, UnicodeDecodeError) as e:+ raise ValueError("Malformed download token.") from e++ expected = _signature(secret, expires_at, user_id, path)+ if not hmac.compare_digest(signature, expected):+ raise ValueError("Invalid download token.")+ if expires_at < time.time():+ raise ValueError("Expired download token.")+ return user_iddiff --git a/src/agentscope/app/deps.py b/src/agentscope/app/deps.pyindex 255fb2575..78e93be9a 100644--- a/src/agentscope/app/deps.py+++ b/src/agentscope/app/deps.py@@ -165,6 +165,18 @@ async def get_workspace_manager(request: Request) -> WorkspaceManagerBase:return request.app.state.workspace_manager+async def get_download_secret(request: Request) -> str:+ """Return the secret that signs file-download tokens.++ Args:+ request (`Request`): The incoming FastAPI request.++ Returns:+ `str`: The signing secret stored in ``app.state``.+ """+ return request.app.state.download_secret++async def get_extra_agent_middlewares(request: Request,) -> AgentMiddlewareFactory | None:diff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.pyindex 9593e6bfa..ed536d67c 100644--- a/src/agentscope/tool/__init__.py+++ b/src/agentscope/tool/__init__.py@@ -16,6 +16,7 @@ from ._builtin import (Read,Write,BackendBase,+ DirEntry,ExecResult,LocalBackend,)@@ -44,6 +45,7 @@ __all__ = [# Builtin tools"BackendBase","LocalBackend",+ "DirEntry","ExecResult","ResetTools","Bash",diff --git a/src/agentscope/tool/_builtin/__init__.py b/src/agentscope/tool/_builtin/__init__.pyindex 15755149e..ef17336fe 100644--- a/src/agentscope/tool/_builtin/__init__.py+++ b/src/agentscope/tool/_builtin/__init__.py@@ -1,7 +1,7 @@# -*- coding: utf-8 -*-"""The builtin tools in agentscope."""-from ._backend import BackendBase, ExecResult, LocalBackend+from ._backend import BackendBase, DirEntry, ExecResult, LocalBackendfrom ._bash import Bashfrom ._edit import Editfrom ._glob import Glob@@ -23,6 +23,7 @@ __all__ = ["Read","Write","BackendBase",+ "DirEntry","LocalBackend","ExecResult",]diff --git a/src/agentscope/tool/_builtin/_backend.py b/src/agentscope/tool/_builtin/_backend.pyindex aaa0a773e..82b50b602 100644--- a/src/agentscope/tool/_builtin/_backend.py+++ b/src/agentscope/tool/_builtin/_backend.py@@ -46,6 +46,15 @@ from typing import Any, AsyncIteratorimport aiofiles+# Chunk size for streamed reads. Large enough that a big file does not+# turn into thousands of awaits, small enough to stay off the heap.+DEFAULT_READ_CHUNK_SIZE = 1024 * 1024++# One NUL-terminated record per entry, for the shell-based ``scandir``+# and ``stat``. The name goes last because it is the only field that+# may itself contain a tab, so a bounded split keeps it whole.+_FIND_ENTRY_FORMAT = "%Y\\t%s\\t%T@\\t%f\\0"+# ── data class ─────────────────────────────────────────────────────────@@ -74,6 +83,31 @@ class ExecResult:return self.exit_code == 0+@dataclass(frozen=True, slots=True)+class DirEntry:+ """One entry from :meth:`BackendBase.scandir`.++ Mirrors :class:`os.DirEntry`: the metadata comes from the same+ directory read as the name, so a listing costs one round trip+ instead of one per entry plus one per attribute.++ Attributes:+ name: The entry's base name, without any leading directory.+ is_dir: Whether the entry is a directory, following symlinks.+ size_bytes: Size in bytes of a file. Always ``None`` for a+ directory — its on-disk size says nothing a caller wants —+ and ``None`` when it could not be determined (a broken+ symlink, a vanished entry).+ mtime: Modification time as a POSIX timestamp, or ``None``+ for the same reasons.+ """++ name: str+ is_dir: bool+ size_bytes: int | None = None+ mtime: float | None = None++# ── helpers ────────────────────────────────────────────────────────────@@ -331,6 +365,33 @@ class BackendBase(ABC):chunks = [chunk async for chunk in stream]await self.write_file(path, b"".join(chunks))+ async def read_stream(+ self,+ path: str,+ chunk_size: int = DEFAULT_READ_CHUNK_SIZE,+ ) -> AsyncIterator[bytes]:+ """Read ``path`` as a byte stream.++ The default reads the whole file through :meth:`read_file` and+ re-slices it, so peak memory is the file size; only backends+ that override this (``LocalBackend``) are constant-memory.+ Overriding requires incremental access to ``exec_shell``+ stdout, which the remote backends do not expose today.++ Args:+ path (`str`):+ Path to the file inside the backend's environment.+ chunk_size (`int`, defaults to 1 MiB):+ The size of each yielded chunk.++ Yields:+ `bytes`:+ Successive chunks of the file, in order.+ """+ data = await self.read_file(path)+ for start in range(0, len(data), chunk_size):+ yield data[start : start + chunk_size]+# ── derived filesystem ops (shell-based defaults) ──────────────async def getcwd(self) -> str:@@ -469,6 +530,133 @@ class BackendBase(ABC):if part]+ async def scandir(self, path: str) -> list[DirEntry]:+ """List one directory level with each entry's metadata.++ The type, size and mtime come back from the same ``find`` run+ as the names, so listing a directory of N entries costs one+ round trip rather than 1 + 3N. Prefer this over+ :meth:`list_dir` plus per-entry calls whenever the metadata is+ wanted; ``find -printf`` is a GNU extension, so backends on+ non-GNU userlands should override it.++ ``%Y`` follows symlinks, matching what :meth:`is_dir` reports;+ the size and mtime describe the link itself, which only+ differs for the link's own few bytes.++ Args:+ path (`str`):+ Directory to list inside the backend's environment.++ Returns:+ `list[DirEntry]`:+ The immediate children, or an empty list if ``path``+ does not exist or cannot be listed.+ """+ return await self._find_entries(+ [+ "find",+ path,+ "-mindepth",+ "1",+ "-maxdepth",+ "1",+ "-printf",+ _FIND_ENTRY_FORMAT,+ ],+ )++ async def stat(self, path: str) -> DirEntry | None:+ """Return one path's type, size and mtime in a single call.++ The single-path counterpart of :meth:`scandir`, the way+ :func:`os.stat` sits beside :func:`os.scandir`. Prefer it over+ asking :meth:`file_exists`, :meth:`is_dir` and+ :meth:`stat_mtime` in turn, which is three round trips for what+ one command answers.++ Args:+ path (`str`):+ Path to stat inside the backend's environment.++ Returns:+ `DirEntry | None`:+ The entry, or ``None`` if ``path`` does not exist.+ ``name`` is the base name, as :meth:`scandir` reports+ it.+ """+ entries = await self._find_entries(+ ["find", path, "-maxdepth", "0", "-printf", _FIND_ENTRY_FORMAT],+ skip_unresolvable=True,+ )+ return entries[0] if entries else None++ async def _find_entries(+ self,+ command: list[str],+ *,+ skip_unresolvable: bool = False,+ ) -> list[DirEntry]:+ """Parse the records a ``_FIND_ENTRY_FORMAT`` run prints.++ Args:+ command (`list[str]`):+ The ``find`` argv, already carrying the format.+ skip_unresolvable (`bool`, defaults to ``False``):+ Drop entries whose target could not be followed — a+ dangling symlink, most often. :meth:`stat` wants this+ (``os.stat`` follows the link and fails, and a caller+ about to read the file must not be told it is there);+ :meth:`scandir` does not, since ``os.scandir`` lists a+ broken link like any other name.++ Returns:+ `list[DirEntry]`:+ One entry per record, or an empty list when ``find``+ failed (a missing path, most often).+ """+ result = await self.exec_shell(command)+ if not result.ok():+ return []++ entries: list[DirEntry] = []+ for record in result.stdout.split(b"\0"):+ if not record:+ continue+ fields = record.decode("utf-8", errors="surrogateescape").split(+ "\t",+ 3,+ )+ if len(fields) != 4:+ continue+ kind, raw_size, raw_mtime, name = fields+ try:+ size: int | None = int(raw_size)+ except ValueError:+ size = None+ try:+ mtime: float | None = float(raw_mtime)+ except ValueError:+ mtime = None+ # ``%Y`` reports N/L/? when it cannot follow the link. The+ # size and mtime it still prints describe the link itself,+ # which would read as a real 21-byte file; ``os.scandir``+ # reports nothing there, so neither does this.+ if kind in ("N", "L", "?"):+ if skip_unresolvable:+ continue+ size, mtime = None, None+ is_dir = kind == "d"+ entries.append(+ DirEntry(+ name=name,+ is_dir=is_dir,+ size_bytes=None if is_dir else size,+ mtime=mtime,+ ),+ )+ return entries+async def stat_mtime(self, path: str) -> float | None:"""Return the modification time of ``path``, or ``None``.@@ -677,6 +865,27 @@ class LocalBackend(BackendBase):async for chunk in stream:await f.write(chunk)+ async def read_stream(+ self,+ path: str,+ chunk_size: int = DEFAULT_READ_CHUNK_SIZE,+ ) -> AsyncIterator[bytes]:+ """Read a local file chunk by chunk, never holding it whole.++ Args:+ path (`str`):+ Path to the local file.+ chunk_size (`int`, defaults to 1 MiB):+ The size of each yielded chunk.++ Yields:+ `bytes`:+ Successive chunks of the file, in order.+ """+ async with aiofiles.open(path, mode="rb") as f:+ while chunk := await f.read(chunk_size):+ yield chunk+async def getcwd(self) -> str:"""Return the host process's current working directory.@@ -756,6 +965,71 @@ class LocalBackend(BackendBase):return resultsreturn os.listdir(path)+ async def scandir(self, path: str) -> list[DirEntry]:+ """List a local directory with each entry's metadata.++ ``os.scandir`` carries the type in the directory record itself,+ so this is cheaper than ``os.listdir`` followed by a ``stat``+ per entry — the same reason the base class batches its ``find``.++ Args:+ path (`str`):+ Directory to list.++ Returns:+ `list[DirEntry]`:+ The immediate children, or an empty list if ``path``+ does not exist or cannot be listed.+ """+ entries: list[DirEntry] = []+ try:+ with os.scandir(path) as it:+ for entry in it:+ # A symlink can break, or the entry can vanish,+ # between the listing and the stat.+ try:+ is_dir = entry.is_dir()+ stat = entry.stat()+ size, mtime = stat.st_size, stat.st_mtime+ except OSError:+ is_dir, size, mtime = False, None, None+ entries.append(+ DirEntry(+ name=entry.name,+ is_dir=is_dir,+ size_bytes=None if is_dir else size,+ mtime=mtime,+ ),+ )+ except OSError:+ return []+ return entries++ async def stat(self, path: str) -> DirEntry | None:+ """Return one local path's type, size and mtime.++ Args:+ path (`str`):+ Path to stat.++ Returns:+ `DirEntry | None`:+ The entry, or ``None`` if ``path`` does not exist or+ cannot be stat'd.+ """+ try:+ # Follows symlinks, as ``os.DirEntry.stat`` does by default.+ info = os.stat(path)+ except OSError:+ return None+ is_dir = os.path.isdir(path)+ return DirEntry(+ name=os.path.basename(path),+ is_dir=is_dir,+ size_bytes=None if is_dir else info.st_size,+ mtime=info.st_mtime,+ )+async def stat_mtime(self, path: str) -> float | None:"""Return the modification time of a local file.diff --git a/tests/backend_local_test.py b/tests/backend_local_test.pyindex 3d23366d9..e9e52305f 100644--- a/tests/backend_local_test.py+++ b/tests/backend_local_test.py@@ -3,8 +3,9 @@Exercises the three abstract primitives (``exec_shell``, ``read_file``,``write_file``) plus the derived filesystem helpers (``file_exists``,-``is_dir``, ``list_dir``, ``stat_mtime``, ``delete_path``) of the-host-local backend, and the module-level ``normalize_newlines`` helper.+``is_dir``, ``list_dir``, ``scandir``, ``read_stream``, ``stat_mtime``,+``delete_path``) of the host-local backend, and the module-level+``normalize_newlines`` helper.``LocalBackend`` is designed to run on every platform (it spawnsprograms from an argv list without a shell and implements the@@ -265,6 +266,72 @@ class TestLocalBackendFilesystemHelpers(IsolatedAsyncioTestCase):),)+ async def test_scandir_returns_metadata_per_entry(self) -> None:+ """``scandir`` carries type, size and mtime with each name."""+ await self.backend.write_file(+ os.path.join(self.temp_dir.name, "f.txt"),+ b"payload",+ )+ os.makedirs(os.path.join(self.temp_dir.name, "d"))+ entries = {+ e.name: e+ for e in await self.backend.scandir(+ self.temp_dir.name,+ )+ }+ self.assertEqual(sorted(entries), ["d", "f.txt"])+ self.assertFalse(entries["f.txt"].is_dir)+ self.assertEqual(entries["f.txt"].size_bytes, 7)+ self.assertIsNotNone(entries["f.txt"].mtime)+ self.assertTrue(entries["d"].is_dir)+ # A directory's own size is noise; the contract pins it to None.+ self.assertIsNone(entries["d"].size_bytes)++ async def test_stat_reports_file_and_directory(self) -> None:+ """``stat`` answers type, size and mtime in one call."""+ path = os.path.join(self.temp_dir.name, "f.txt")+ await self.backend.write_file(path, b"payload")+ entry = await self.backend.stat(path)+ self.assertIsNotNone(entry)+ self.assertEqual(entry.name, "f.txt")+ self.assertFalse(entry.is_dir)+ self.assertEqual(entry.size_bytes, 7)+ self.assertIsNotNone(entry.mtime)++ directory = await self.backend.stat(self.temp_dir.name)+ self.assertTrue(directory.is_dir)+ self.assertIsNone(directory.size_bytes)++ async def test_stat_missing_path_returns_none(self) -> None:+ """A path with nothing behind it stats to None, not an error."""+ self.assertIsNone(+ await self.backend.stat(+ os.path.join(self.temp_dir.name, "missing"),+ ),+ )++ async def test_scandir_missing_dir_returns_empty(self) -> None:+ """An unlistable path yields no entries rather than raising."""+ self.assertEqual(+ await self.backend.scandir(+ os.path.join(self.temp_dir.name, "missing"),+ ),+ [],+ )++ async def test_read_stream_chunks_without_buffering(self) -> None:+ """``read_stream`` yields the file in ``chunk_size`` pieces."""+ path = os.path.join(self.temp_dir.name, "f.txt")+ await self.backend.write_file(path, b"abcdefg")+ chunks = [c async for c in self.backend.read_stream(path, 3)]+ self.assertEqual(chunks, [b"abc", b"def", b"g"])++ async def test_read_stream_empty_file_yields_nothing(self) -> None:+ """An empty file produces no chunks, not one empty chunk."""+ path = os.path.join(self.temp_dir.name, "empty.txt")+ await self.backend.write_file(path, b"")+ self.assertEqual([c async for c in self.backend.read_stream(path)], [])+async def test_delete_path_file(self) -> None:"""``delete_path`` removes a single file."""path = os.path.join(self.temp_dir.name, "f.txt")diff --git a/tests/service_workspace_files_test.py b/tests/service_workspace_files_test.pynew file mode 100644index 000000000..0bf4fec4f--- /dev/null+++ b/tests/service_workspace_files_test.py@@ -0,0 +1,595 @@+# -*- coding: utf-8 -*-+"""Tests for the workspace file-browsing endpoints.++These are lightweight unit tests that do not require ``create_app``.+Dependencies are injected by calling the endpoint coroutines directly,+which avoids pulling a full FastAPI / Redis stack.+"""++from __future__ import annotations++import posixpath+import time+from typing import AsyncIterator+from unittest import IsolatedAsyncioTestCase++from fastapi import HTTPException, status++from agentscope.app._router._workspace import (+ create_download_token,+ list_workspace_directory,+ read_workspace_file,+)+from agentscope.app._service._download_token import (+ sign_download_token,+ verify_download_token,+)+from agentscope.app.storage import (+ AgentData,+ AgentRecord,+ SessionConfig,+ SessionRecord,+ SessionSource,+)+from agentscope.agent import ContextConfig, ReActConfig+from agentscope.state import AgentState+from agentscope.tool import DirEntry++SECRET = "test-signing-secret"++# ---------------------------------------------------------------------------+# Fake backend + workspace used by endpoint-level tests+# ---------------------------------------------------------------------------+++class _FakeBackend:+ """A tiny in-memory filesystem — posix paths only."""++ def __init__(self, files: dict[str, bytes] | None = None) -> None:+ self._files: dict[str, bytes] = {}+ self._dirs: set[str] = {"/workspace"}+ self.read_paths: list[str] = []+ for p, data in (files or {}).items():+ self._files[p] = data+ self._ensure_parent_dirs(p)++ def join_path(self, path: str, *paths: str) -> str:+ """Join posix-style path components for the in-memory backend."""+ return posixpath.join(path, *paths)++ def _ensure_parent_dirs(self, file_path: str) -> None:+ cur = posixpath.dirname(file_path)+ while cur and cur not in self._dirs:+ self._dirs.add(cur)+ cur = posixpath.dirname(cur)++ async def is_dir(self, path: str) -> bool:+ """Return True when *path* is a tracked directory."""+ return path in self._dirs++ async def file_exists(self, path: str) -> bool:+ """Return True when *path* is a tracked file or directory."""+ return path in self._files or path in self._dirs++ async def list_dir(+ self,+ path: str,+ *,+ recursive: bool = False,+ ) -> list[str]:+ """Return direct children of *path* sorted lexicographically."""+ _ = recursive+ out: set[str] = set()+ for tracked in list(self._files) + list(self._dirs):+ if posixpath.dirname(tracked) == path:+ name = posixpath.basename(tracked)+ if name:+ out.add(name)+ return sorted(out)++ async def read_file(self, path: str) -> bytes:+ """Return the raw bytes stored for *path*."""+ self.read_paths.append(path)+ if path not in self._files:+ raise FileNotFoundError(path)+ return self._files[path]++ async def read_stream(+ self,+ path: str,+ chunk_size: int = 4,+ ) -> AsyncIterator[bytes]:+ """Yield the stored bytes in small chunks, like a real backend."""+ data = await self.read_file(path)+ for start in range(0, len(data), chunk_size):+ yield data[start : start + chunk_size]++ def isabs(self, path: str) -> bool:+ """Return whether *path* is absolute under POSIX semantics."""+ return posixpath.isabs(path)++ def normpath(self, path: str) -> str:+ """Normalize a POSIX path."""+ return posixpath.normpath(path)++ def abspath(self, path: str, *, cwd: str) -> str:+ """Resolve a relative POSIX path against *cwd*."""+ return posixpath.normpath(+ path if posixpath.isabs(path) else posixpath.join(cwd, path),+ )++ def basename(self, path: str) -> str:+ """Return the final POSIX path component."""+ return posixpath.basename(path)++ async def write_file(self, path: str, data: bytes) -> bytes | None:+ """Write *data* to *path* and ensure parent dirs exist."""+ self._files[path] = data+ self._ensure_parent_dirs(path)+ return None++ async def stat_mtime(self, path: str) -> float | None:+ """Return a deterministic mtime value for tracked paths."""+ if path in self._files or path in self._dirs:+ return 1_700_000_000.0+ return None++ async def stat(self, path: str) -> DirEntry | None:+ """Return one path's metadata, or None when it is not tracked."""+ is_dir = path in self._dirs+ if not is_dir and path not in self._files:+ return None+ return DirEntry(+ name=posixpath.basename(path),+ is_dir=is_dir,+ size_bytes=None if is_dir else len(self._files[path]),+ mtime=1_700_000_000.0,+ )++ async def scandir(self, path: str) -> list[DirEntry]:+ """Return each child with its metadata, as one batch would."""+ entries = []+ for name in await self.list_dir(path):+ child = posixpath.join(path, name)+ is_dir = child in self._dirs+ entries.append(+ DirEntry(+ name=name,+ is_dir=is_dir,+ size_bytes=(+ None if is_dir else len(self._files.get(child, b""))+ ),+ mtime=1_700_000_000.0,+ ),+ )+ return entries+++class _FakeWorkspace:+ def __init__(self, backend: _FakeBackend) -> None:+ self.workdir = "/workspace"+ self._backend = backend++ def get_backend(self) -> _FakeBackend:+ """Expose the injected in-memory backend."""+ return self._backend+++class _FakeWorkspaceManager:+ def __init__(self, workspace: _FakeWorkspace) -> None:+ self._ws = workspace++ async def get_workspace(+ self,+ user_id: str,+ agent_id: str,+ session_id: str,+ workspace_id: str | None = None,+ ) -> _FakeWorkspace:+ """Return the pre-seeded workspace, ignoring identifier args."""+ _ = (user_id, agent_id, session_id, workspace_id)+ return self._ws+++class _FakeStorage:+ def __init__(self, records: list[SessionRecord]) -> None:+ self._records = {(r.user_id, r.agent_id, r.id): r for r in records}++ async def get_session(+ self,+ user_id: str,+ agent_id: str,+ session_id: str,+ ) -> SessionRecord | None:+ """Look up a seeded session record by composite key."""+ return self._records.get((user_id, agent_id, session_id))+++def _make_session(+ *,+ user_id: str = "u",+ agent_id: str = "a",+ session_id: str = "s",+ workspace_id: str = "ws-1",+) -> SessionRecord:+ return SessionRecord(+ user_id=user_id,+ agent_id=agent_id,+ id=session_id,+ source=SessionSource.USER,+ state=AgentState(),+ config=SessionConfig(+ workspace_id=workspace_id,+ name="test session",+ ),+ agent_snapshot=AgentRecord(+ user_id=user_id,+ source="user",+ data=AgentData(+ name="A",+ context_config=ContextConfig(),+ react_config=ReActConfig(),+ ),+ ),+ )+++async def _collect(response: object) -> bytes:+ """Drain a StreamingResponse body into bytes."""+ chunks = [chunk async for chunk in response.body_iterator]+ return b"".join(+ c.encode("utf-8") if isinstance(c, str) else c for c in chunks+ )+++# ---------------------------------------------------------------------------+# Download tokens+# ---------------------------------------------------------------------------+++class DownloadTokenTests(IsolatedAsyncioTestCase):+ """Unit tests for the capability token itself."""++ def test_roundtrip_returns_the_user(self) -> None:+ """A freshly minted token verifies back to who it was for."""+ token, expires_at = sign_download_token(SECRET, "alice", "/w/a.txt")+ self.assertGreater(expires_at, time.time())+ self.assertEqual(+ verify_download_token(SECRET, token, "/w/a.txt"),+ "alice",+ )++ def test_token_does_not_cover_another_path(self) -> None:+ """The path is re-derived from the request, so replay fails."""+ token, _ = sign_download_token(SECRET, "alice", "/w/a.txt")+ with self.assertRaises(ValueError):+ verify_download_token(SECRET, token, "/w/secret.txt")++ def test_another_secret_is_rejected(self) -> None:+ """A token minted elsewhere must not verify here."""+ token, _ = sign_download_token("other-secret", "alice", "/w/a.txt")+ with self.assertRaises(ValueError):+ verify_download_token(SECRET, token, "/w/a.txt")++ def test_expired_token_is_rejected(self) -> None:+ """A TTL that has already passed makes the token useless."""+ token, _ = sign_download_token(SECRET, "alice", "/w/a.txt", ttl=-1)+ with self.assertRaises(ValueError):+ verify_download_token(SECRET, token, "/w/a.txt")++ def test_garbage_is_rejected(self) -> None:+ """Malformed input must raise, not crash with an index error."""+ for bad in ("", "not-a-token", "1.2", "x.y.z", "9999999999.YQ.YQ"):+ with self.assertRaises(ValueError):+ verify_download_token(SECRET, bad, "/w/a.txt")+++# ---------------------------------------------------------------------------+# Endpoints+# ---------------------------------------------------------------------------+++class WorkspaceFileEndpointTests(IsolatedAsyncioTestCase):+ """Call the file-browsing endpoints directly, bypassing FastAPI."""++ async def asyncSetUp(self) -> None:+ files = {+ "/workspace/notes.txt": b"hello world",+ "/workspace/subdir/report.md": b"# report\n\nbody\n",+ "/elsewhere/outside.txt": b"outside the workspace",+ }+ self._backend = _FakeBackend(files=files)+ self._workspace = _FakeWorkspace(self._backend)+ self._wm = _FakeWorkspaceManager(self._workspace)+ self._storage = _FakeStorage([_make_session()])++ # ------------------------------------------------------------------+ # directories+ # ------------------------------------------------------------------++ async def test_list_root(self) -> None:+ """The workspace root lists its seeded files and directories."""+ entries = await list_workspace_directory(+ agent_id="a",+ session_id="s",+ path="",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ )+ by_name = {e.name: e for e in entries}+ self.assertEqual(sorted(by_name), ["notes.txt", "subdir"])+ self.assertFalse(by_name["notes.txt"].is_dir)+ self.assertEqual(by_name["notes.txt"].size_bytes, len(b"hello world"))+ self.assertEqual(by_name["notes.txt"].updated_at, 1_700_000_000.0)+ self.assertTrue(by_name["subdir"].is_dir)+ self.assertIsNone(by_name["subdir"].size_bytes)+ # Listing must not read file contents, or a directory of large+ # files would pull all of them into memory.+ self.assertEqual(self._backend.read_paths, [])++ async def test_relative_path_resolves_against_workdir(self) -> None:+ """A relative path is still convenient, and still works."""+ entries = await list_workspace_directory(+ agent_id="a",+ session_id="s",+ path="subdir",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ )+ self.assertEqual([e.name for e in entries], ["report.md"])++ async def test_absolute_path_outside_workspace_is_allowed(self) -> None:+ """Browsing is not confined to the workspace root."""+ entries = await list_workspace_directory(+ agent_id="a",+ session_id="s",+ path="/elsewhere",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ )+ self.assertEqual([e.name for e in entries], ["outside.txt"])++ async def test_parent_traversal_is_allowed(self) -> None:+ """``..`` is an ordinary path component now, not an attack."""+ entries = await list_workspace_directory(+ agent_id="a",+ session_id="s",+ path="../elsewhere",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ )+ self.assertEqual([e.name for e in entries], ["outside.txt"])++ async def test_missing_session_raises_404(self) -> None:+ """An unknown session id must return a 404 HTTP error."""+ with self.assertRaises(HTTPException) as ctx:+ await list_workspace_directory(+ agent_id="a",+ session_id="does-not-exist",+ path="",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ )+ self.assertEqual(ctx.exception.status_code, status.HTTP_404_NOT_FOUND)++ async def test_missing_directory_raises_404(self) -> None:+ """Listing a path that does not exist raises a 404 error."""+ with self.assertRaises(HTTPException) as ctx:+ await list_workspace_directory(+ agent_id="a",+ session_id="s",+ path="missing-dir",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ )+ self.assertEqual(ctx.exception.status_code, status.HTTP_404_NOT_FOUND)++ async def test_listing_a_file_raises_400(self) -> None:+ """Listing a regular file is a client mistake, not a 404."""+ with self.assertRaises(HTTPException) as ctx:+ await list_workspace_directory(+ agent_id="a",+ session_id="s",+ path="notes.txt",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ )+ self.assertEqual(+ ctx.exception.status_code,+ status.HTTP_400_BAD_REQUEST,+ )++ # ------------------------------------------------------------------+ # files+ # ------------------------------------------------------------------++ async def _read(self, **kwargs: object) -> object:+ """Call the file endpoint with the shared fixtures filled in."""+ return await read_workspace_file(+ agent_id="a",+ session_id="s",+ storage=self._storage,+ workspace_manager=self._wm,+ secret=SECRET,+ **kwargs,+ )++ async def test_read_streams_content_with_inferred_type(self) -> None:+ """The body arrives in chunks, typed from the file extension."""+ response = await self._read(+ path="notes.txt",+ download=False,+ token=None,+ x_user_id="u",+ )+ self.assertEqual(response.media_type, "text/plain")+ # Without this the browser can only show an indeterminate bar.+ self.assertEqual(response.headers["content-length"], "11")+ self.assertNotIn("content-disposition", response.headers)+ self.assertEqual(await _collect(response), b"hello world")++ async def test_unknown_extension_falls_back_to_octet_stream(self) -> None:+ """An unguessable type must not become ``text/plain``."""+ await self._backend.write_file("/workspace/blob.zzz", b"\x00\x01")+ response = await self._read(+ path="blob.zzz",+ download=False,+ token=None,+ x_user_id="u",+ )+ self.assertEqual(response.media_type, "application/octet-stream")++ async def test_download_sets_content_disposition(self) -> None:+ """``download=true`` is what turns a preview into a save."""+ response = await self._read(+ path="notes.txt",+ download=True,+ token=None,+ x_user_id="u",+ )+ self.assertEqual(+ response.headers["content-disposition"],+ "attachment; filename*=UTF-8''notes.txt",+ )++ async def test_absolute_path_outside_workspace_is_readable(self) -> None:+ """Reading, like listing, is not confined to the workspace."""+ response = await self._read(+ path="/elsewhere/outside.txt",+ download=False,+ token=None,+ x_user_id="u",+ )+ self.assertEqual(await _collect(response), b"outside the workspace")++ async def test_missing_file_raises_404(self) -> None:+ """A path with nothing behind it is a 404."""+ with self.assertRaises(HTTPException) as ctx:+ await self._read(+ path="nope.txt",+ download=False,+ token=None,+ x_user_id="u",+ )+ self.assertEqual(ctx.exception.status_code, status.HTTP_404_NOT_FOUND)++ async def test_reading_a_directory_raises_400(self) -> None:+ """Reading a directory is a client mistake, not a 404."""+ with self.assertRaises(HTTPException) as ctx:+ await self._read(+ path="subdir",+ download=False,+ token=None,+ x_user_id="u",+ )+ self.assertEqual(+ ctx.exception.status_code,+ status.HTTP_400_BAD_REQUEST,+ )++ # ------------------------------------------------------------------+ # files — authentication+ # ------------------------------------------------------------------++ async def test_neither_header_nor_token_raises_401(self) -> None:+ """The endpoint takes an optional header, not an absent guard."""+ with self.assertRaises(HTTPException) as ctx:+ await self._read(+ path="notes.txt",+ download=False,+ token=None,+ x_user_id=None,+ )+ self.assertEqual(+ ctx.exception.status_code,+ status.HTTP_401_UNAUTHORIZED,+ )++ async def test_token_stands_in_for_the_header(self) -> None:+ """A minted token authorizes the download it was minted for."""+ minted = await create_download_token(+ agent_id="a",+ session_id="s",+ path="notes.txt",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ secret=SECRET,+ )+ # Sent back exactly as minted — the token binds the query+ # string, since resolving it needs the user it has yet to yield.+ response = await self._read(+ path="notes.txt",+ download=True,+ token=minted.token,+ x_user_id=None,+ )+ self.assertEqual(await _collect(response), b"hello world")++ async def test_token_does_not_cover_the_resolved_path(self) -> None:+ """Minting relative and downloading absolute is not the same."""+ minted = await create_download_token(+ agent_id="a",+ session_id="s",+ path="notes.txt",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ secret=SECRET,+ )+ with self.assertRaises(HTTPException) as ctx:+ await self._read(+ path="/workspace/notes.txt",+ download=True,+ token=minted.token,+ x_user_id=None,+ )+ self.assertEqual(+ ctx.exception.status_code,+ status.HTTP_401_UNAUTHORIZED,+ )++ async def test_token_is_bound_to_its_path(self) -> None:+ """A token for one file cannot be replayed against another."""+ minted = await create_download_token(+ agent_id="a",+ session_id="s",+ path="notes.txt",+ user_id="u",+ storage=self._storage,+ workspace_manager=self._wm,+ secret=SECRET,+ )+ with self.assertRaises(HTTPException) as ctx:+ await self._read(+ path="/elsewhere/outside.txt",+ download=True,+ token=minted.token,+ x_user_id=None,+ )+ self.assertEqual(+ ctx.exception.status_code,+ status.HTTP_401_UNAUTHORIZED,+ )++ async def test_tampered_token_raises_401(self) -> None:+ """An edited signature must not pass."""+ token, _ = sign_download_token(SECRET, "u", "notes.txt")+ with self.assertRaises(HTTPException) as ctx:+ await self._read(+ path="notes.txt",+ download=True,+ token=token[:-1] + ("A" if token[-1] != "A" else "B"),+ x_user_id=None,+ )+ self.assertEqual(+ ctx.exception.status_code,+ status.HTTP_401_UNAUTHORIZED,+ )