ێj0dZddlZddlZddlZddlZddlZddlZddlZddlZddl m Z ddl m Z ddl mZddlmZmZmZddlmZdd lmZdd lmZmZdd lmZdd lmZmZmZm Z m!Z!m"Z"dd l#m$Z$ddl%m&Z&m'Z'ddl(m)Z)m*Z*m+Z+m,Z,dZ-dZ.dZ/GddZ0dS)uWorkspaceBase — abstract interface and shared backend-driven impl. A workspace provides: - **Resources** — skills available to the agent. - **Tools** — MCPs and built-in tools for operating on resources. - **Offload** — persistence of compressed context and tool results for agentic retrieval. Three concrete implementations: - :class:`agentscope.workspace.LocalWorkspace` — local filesystem. - :class:`agentscope.workspace.DockerWorkspace` — Docker container. - :class:`agentscope.workspace.E2BWorkspace` — E2B cloud sandbox. - :class:`agentscope.workspace.OpenSandboxWorkspace` — OpenSandbox remote sandbox. Consumers: - **Agent** — calls ``list_mcps``, ``list_skills``, ``list_tools``, ``offload_context``, ``offload_tool_result``. - **User** — dynamically adds/removes MCPs and skills via ``add_mcp`` / ``remove_mcp`` / ``add_skill`` / ``remove_skill``. - **Developer** — manages lifecycle via ``initialize`` / ``close``. - **Backend consumers** access the active backend via :meth:`get_backend`. Shared implementation --------------------- The base class implements every operation that can be expressed against the workspace's :class:`BackendBase` plus a fixed layout derived from ``workdir``: .. code-block:: text {workdir}/ ├── .mcp # persisted MCP client configs (JSON array) ├── data/ # offloaded multimodal payloads ├── skills/ # skill subdirectories └── sessions/ # per-session context and tool-result files Subclasses only set ``self.workdir`` (the agent-visible root); all other directory paths are derived via :meth:`BackendBase.join_path`, keeping path semantics consistent with whichever backend is bound. N)abstractmethod)deepcopy)Path) AsyncIteratorLiteralSelf)AnyUrl)logger) _generate_id_normalize_local_path) MCPClient) Base64Source DataBlockMsg TextBlockToolResultBlock URLSource)Skill) BackendBaseToolBase)DEFAULT_DATA_DIRDEFAULT_MCP_FILEDEFAULT_SESSIONS_DIRDEFAULT_SKILLS_DIRaimport tarfile, sys, os src, dst = sys.argv[1], sys.argv[2] os.makedirs(dst, exist_ok=True) dst_real = os.path.realpath(dst) tf = tarfile.open(src) try: members = tf.getmembers() for m in members: target = os.path.realpath(os.path.join(dst, m.name)) if not (target == dst_real or target.startswith(dst_real + os.sep)): raise Exception('unsafe tar member: ' + m.name) tf.extractall(dst, members=members) finally: tf.close() os.unlink(src) aimport os, sys, tarfile, zipfile src, dst, fmt, limit = sys.argv[1:5] limit = int(limit) os.makedirs(dst, exist_ok=True) dst_real = os.path.realpath(dst) def check(name): target = os.path.realpath(os.path.join(dst, name)) if not (target == dst_real or target.startswith(dst_real + os.sep)): raise Exception('unsafe archive member: ' + name) if fmt == 'zip': ar = zipfile.ZipFile(src) members = ar.infolist() total = sum(m.file_size for m in members) names = [m.filename for m in members] else: ar = tarfile.open(src) members = ar.getmembers() total = sum(m.size for m in members) names = [m.name for m in members] for m in members: if m.issym() or m.islnk(): check(os.path.join(os.path.dirname(m.name), m.linkname)) try: if total > limit: raise Exception('archive expands to %d bytes, limit is %d' % (total, limit)) for name in names: check(name) ar.extractall(dst, members) finally: ar.close() os.unlink(src) i@c eZdZUdZeed< eed< eed< edzed< ee ed< eeed< ee ed < e j ed < e j ed < e d edzfd Z dddddedzdee dzdeedzd dfdZe d efdZe d efdZe d efdZe d efdZe d efdZeded efdZed;dZed;dZd;dZd efdZd efdZded dfdZed efdZd ee fdZ!d ee fd Z"ed!e d dfd"Z#ed#ed dfd$Z$d;d%Z%d&ed'ee&d efd(Z'd&ed)e(d efd*Z)d+e*d e*fd,Z+d ee,fd-Z-d.ed dfd/Z.e/fd0e0e1d1e2d2d3ed4e3d df d5Z4d6ed efd7Z5d3ed efd8Z6d#ed dfd9Z7d;d:Z8dS)< WorkspaceBasea<Abstract base class for all workspace implementations. Subclasses provide concrete behaviour for one execution backend (local filesystem, Docker container, E2B sandbox). The base class owns: - lifecycle scaffolding (``async with`` protocol, ``is_alive``); - the canonical workspace layout derived from ``workdir`` (data/, skills/, sessions/, .mcp); - shared backend-driven implementations of offload, MCP persistence and a basic skill manager that subclasses can override (LocalWorkspace does, with a hash-indexed variant). workspace_idworkdiris_aliveN_backend default_mcps skill_paths_mcps _mcp_lock _skill_lockreturncdS)aaOptional path (backend-side) to the ``Glob`` helper script. ``None`` means the :class:`Glob` builtin tool falls back to its default behaviour (suitable for :class:`LocalBackend`). Remote backends override this with a sandbox-/container-side script path so :class:`Glob` can run efficiently inside the workspace. Nselfs HC:\Projects\DSCons\.venv\Lib\site-packages\agentscope\workspace\_base.py_glob_helper_pathzWorkspaceBase._glob_helper_path t)rr#r$c |p t|_d|_d|_t |pg|_d|pgD|_g|_tj |_ tj |_ dS)a>Initialise the shared workspace state. Subclasses must call ``super().__init__`` and then set :attr:`workdir` themselves before any base-class method is invoked. Backend binding (``self._backend``) is left to the subclass (Local sets it eagerly; Docker/E2B set it during :meth:`initialize`). Args: workspace_id (`str | None`, optional): Existing identifier to adopt; ``None`` mints a fresh UUID. default_mcps (`list[MCPClient] | None`, optional): MCP clients to register when the workspace boots without a persisted ``.mcp`` file. skill_paths (`list[str] | None`, optional): Local skill directories to copy into ``skills/`` on first start. FNc,g|]}t|Sr*)r ).0paths r- z*WorkspaceBase.__init__..s.   ,0 !$ ' '   r0) r rr!r"listr#r$r%asyncioLockr&r')r,rr#r$s r-__init__zWorkspaceBase.__init__s4):LNN   !344  4?4E2     "<>>r0cf||jtS)u6``${workdir}/data`` — offloaded multimodal payloads.) get_backend join_pathr rr+s r- _data_dirzWorkspaceBase._data_dir)!!++DL:JKKKr0cf||jtS)u/``${workdir}/skills`` — skill subdirectories.)r;r<r rr+s r- _skills_dirzWorkspaceBase._skills_dirs0!!++ L    r0cf||jtS)u6``${workdir}/sessions`` — per-session offload files.)r;r<r rr+s r- _sessions_dirzWorkspaceBase._sessions_dirs0!!++ L    r0cf||jtS)u4``${workdir}/.mcp`` — persisted MCP registrations.)r;r<r rr+s r- _mcp_filezWorkspaceBase._mcp_file r>r0cdS)aCWhether the workspace storage survives :meth:`close`. Defaults to ``True``. Subclasses with conditional persistence (e.g. :class:`DockerWorkspace` without a host bind-mount) override this to gate the cost of writing ``.mcp`` and other files that would not survive the next session. Tr*r+s r- is_persistentzWorkspaceBase.is_persistentr/r0r4cx|drd|St|S)aConvert an absolute backend-side path to a ``file://`` URI. Absolute POSIX paths (every remote backend, plus :class:`LocalBackend` on Linux/macOS) start with ``/`` and use the plain ``file://{path}`` form. Windows absolute paths (e.g. ``C:\Users\...``) round-trip through :meth:`pathlib.Path.as_uri` to produce ``file:///C:/...`` form. /zfile://) startswithras_uri)r4s r-_path_to_file_urizWorkspaceBase._path_to_file_uris> ??3   $#T## #Dzz  """r0c KdS)z6Provision resources, connect MCP servers, copy skills.Nr*r+s r- initializezWorkspaceBase.initialize+ r0c KdS)z&Release all resources and connections.Nr*r+s r-closezWorkspaceBase.close/rNr0c KdS)uReset the workspace to a clean state. Closes and removes all registered MCPs, deletes all skills, and wipes per-session state (offloaded context / tool results and any data files). Constructor-time ``default_mcps`` and ``skill_paths`` are **not** re-seeded — reset returns the workspace to an empty state, not its initial state. The default implementation is a no-op. Subclasses with user state must override this. Nr*r+s r-resetzWorkspaceBase.reset3rNr0cf|j$tt|jd|jS)aReturn the workspace's active filesystem/execution backend. Docker and E2B workspaces may replace their backend when reconnecting, so callers should resolve it from the workspace when beginning an operation rather than retaining a stale private ``_backend`` value. Raises: RuntimeError: If the workspace has not been initialized or has no active backend. NzO has no active backend. Initialize the workspace before requesting its backend.)r" RuntimeErrortype__name__r+s r-r;zWorkspaceBase.get_backend@sF = ::&JJJ }r0cLK|d{Vd|_|S)zwContext manager support for ``async with``. Calls ``initialize()`` and returns the workspace instance. NT)rMr!r+s r- __aenter__zWorkspaceBase.__aenter__Ss6oo  r0exccLK|d{Vd|_dS)zrContext manager support for ``async with``. Calls ``close()`` and returns the workspace instance. NF)rPr!)r,rYs r- __aexit__zWorkspaceBase.__aexit__[s3jjll r0c KdS)z*Workspace-specific system prompt fragment.Nr*r+s r-get_instructionszWorkspaceBase.get_instructionsdrNr0cKddlm}m}m}m}m}m}|}d|i}|j |j|d<||j ||||di|||||||gS) a_Built-in tools scoped to this workspace. Returns the six builtin tools (:class:`Bash`, :class:`Edit`, :class:`Glob`, :class:`Grep`, :class:`Read`, :class:`Write`), each bound to the workspace's active backend so that all filesystem and process I/O happens inside the workspace's execution environment. :class:`Bash` is rooted at :attr:`workdir`; :class:`Glob` receives the optional :attr:`_glob_helper_path` when the backend ships one. Raises: RuntimeError: If the workspace has not been initialised yet. r )BashEditGlobGrepReadWritebackendNglob_helper_path)cwdre)rer*) toolr_r`rarbrcrdr;r.r ) r,r_r`rarbrcrdre glob_kwargss r- list_toolszWorkspaceBase.list_toolsjs ?>>>>>>>>>>>>>>>""$$&0  ! -.2.DK* + DT\7 3 3 3 D ! ! ! D  ;   D ! ! ! D ! ! ! E' " " "   r0c.Kt|jS)z,Return the currently registered MCP clients.)r6r%r+s r- list_mcpszWorkspaceBase.list_mcpssDJr0 mcp_clientc KdS)zRegister a new MCP server. Args: mcp_client (`MCPClient`): The MCP to register. Raises: `ValueError`: If an MCP with the same name already exists. Nr*)r,rms r-add_mcpzWorkspaceBase.add_mcprNr0namec KdS)zDeregister an MCP server by name. Args: name (`str`): MCP name to remove. Unknown names log a warning and return silently. Nr*)r,rps r- remove_mcpzWorkspaceBase.remove_mcprNr0cNK|jsdS|j}|dStjd|jDddd} ||j|d{VdS#t$r&}tj d|j|Yd}~dSd}~wwxYw)uPersist ``self._mcps`` to ``${workdir}/.mcp`` via backend. No-op when :attr:`is_persistent` is ``False`` (e.g. ephemeral Docker container without a host bind-mount). Failures are logged but not raised — the in-memory MCP list remains the authoritative copy regardless of whether disk persistence succeeded. Callers are expected to hold :attr:`_mcp_lock` already. Nc:g|]}|dS)json)mode) model_dump)r3ms r-r5z0WorkspaceBase._save_mcp_file..s& ; ; ;1Q\\v\ & & ; ; ;r0r F)indent ensure_asciiutf-8z!Failed to save MCP file at %s: %s) rFr"rudumpsr%encode write_filerD Exceptionr warning)r,repayloades r-_save_mcp_filezWorkspaceBase._save_mcp_files!  F- ? F* ; ; ; ; ;    &//   $$T^W== = = = = = = = = =    N3          s!A44 B$>BB$ session_idmsgsc&K|}||j|}||d}t|}g}|D]}t |jt srg} |jD]a} t | tr5t | jtr| | d{V} | | b| |_| | d |dz} d} ||d{V} n#tt f$rYnwxYw||| | dzd{V|S)uEPersist compressed context for agentic retrieval. Appends every message in ``msgs`` to ``${workdir}/sessions//context.jsonl`` (one message per JSONL line). Inline base64 :class:`DataBlock` payloads are extracted into ``data/`` and rewritten as ``file://`` URL blocks before serialisation so the JSONL line size stays bounded. Args: session_id (`str`): Session-scope key used to partition offloaded data (one subdirectory per session). msgs (`list[Msg]`): Conversation messages to offload. Not mutated — a deep copy is used internally. Returns: `str`: Backend-side path of the JSONL file that received the new lines. z context.jsonlN r0r{)r;r<rBr isinstancecontentstrrsourceroffload_data_blockappendmodel_dump_jsonjoin read_fileFileNotFoundErrorOSErrorr~r}) r,rrrebaser4copiedlinesmsgrblockrexistings r-offload_contextzWorkspaceBase.offload_contexts6""$$  !3Z@@  77$ 0 0Cck3// & " [**E!%33E  $99E'+&=&=e&D&D D D D D D DNN5))))% LL,,.. / / / /))E""T) $..t44444444HH!7+    D   x'..2I2I'IJJJJJJJJJ s,EEE tool_resultc K|}||j|}||d|jd}d}||d{VrB||d|jd|d}|dz }||d{VBg}t |jtr||jn|jD]}t |tr||j 2t |trt |j tr5||d{V} t| j j} nt|j j} |d| d|jd |j jd ||d |d d{V|S) uPPersist a single tool result as a flat text file. Writes ``${workdir}/sessions//tool_result-.txt``. Text blocks are concatenated verbatim; :class:`DataBlock` items emit ```` placeholders, with inline base64 payloads first offloaded to ``data/``. On a filename clash (same tool-result ``id`` written twice in one session) the new file is suffixed with ``(1)``, ``(2)``, … to avoid clobbering the prior content. Args: session_id (`str`): Session-scope key used to partition offloaded data. tool_result (`ToolResultBlock`): The tool result block to persist. Returns: `str`: Backend-side path of the offloaded text file. z tool_result-z.txtrN(z).txtz r{)r;r<rBid file_existsroutputrrrtextrrrrurlrp media_typer~rr}) r,rrrerr4indexpartsrdrs r-offload_tool_resultz!WorkspaceBase.offload_tool_resultsa4""$$  !3Z@@  'Jkn'J'J'JKK''-------- $$<{~<<<<<D QJE ''--------  k(# . .  LL+ , , , ,$+  eY// LL,,,,y11 !%, ==4"&"9"9%"@"@@@@@@@!!(,//!%,"233LLDcDD5:DD',|'>DDD   rwwu~~'<'.``. Hashing the *base64* text rather than the decoded bytes lets a second offload of the same block short-circuit (same key → same file → no write). Args: block (`DataBlock`): A data block. Blocks already backed by a :class:`URLSource` are returned unchanged. Returns: `DataBlock`: A new :class:`DataBlock` whose source is a portable ``workspace://`` URL pointing at the persisted file inside the workspace. z.binrHNz workspace:///)rr)rrpr)rrrr;hashlibsha256datar} hexdigest mimetypesguess_extensionrrr<r=rr~base64 b64decoderrrprr )r,rrehash_strextrelr4s r-rz WorkspaceBase.offload_data_block:sw(%, 55 L""$$>%,"3":":"<"<==GGII' (?@@JF!33H3c33  H1Cc1C1CDD((........ $$ !233       x030011 <2    r0c Kddl}|}||jd{VsgS||jdd{V}g}|D]}||dkr ||d{V}||d}| d}| d} |r| s| tt|t| | ||jpd d #t$r!} t!jd || Yd} ~ d} ~ wwxYw|S) a3Enumerate skills under ``${workdir}/skills``. Walks ``skills/`` recursively, parses every ``SKILL.md``'s YAML front matter, and yields one :class:`Skill` per file that has both ``name`` and ``description``. Subclasses with richer indexing (e.g. :class:`LocalWorkspace` with its ``.skills`` hash index) override this method. Returns: `list[Skill]`: Skills available to the agent. Empty when ``skills/`` is missing or contains no parseable ``SKILL.md``. rNT) recursiveSKILL.mdr{rp descriptionrg)rprdirmarkdown updated_atzFailed to load skill %s: %s) frontmatterr;is_dirr@list_dirbasenamerloadsdecodegetrrrdirnamerrr r) r,fmreentriesskillsmd_pathrawdocrpdescrs r- list_skillszWorkspaceBase.list_skillsms !   ""$$^^D$455555555 I(()9T(JJJJJJJJ  J JG((J66 J#--g66666666hhszz'2233wwvww}--4  YY$'II#OOG44!$!2#&  J J J\^^>>f>> #, 8, 8, 8, 8, 8, 8, 8, 8$$gtT5E%FGG G G G G G G G'' 2,..22G&&|V<< < < < < < < <" 8&11!-$/00        yy{{&F!=//CCFF "227;;;;;;;;"&"6"6x"@"@@@@@@@ $//))$*:IFFwwyy&D9DD;--gyAADD ))'222222222)),7777777777))'222222222)),77777777777Y, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8\  *It7GHHHHHs,.s000A000r0zSkill z not found. Available: zRemoved skill %r at %s)r;rrprKeyErrorrr r)r,rprer target_dirr  availables r- remove_skillzWorkspaceBase.remove_skillps""$$''))))))))!%   Av~~U   00000ICCC CC !!*--------- ,dJ?????r0c K|jsdS|j}|dS||jd{V}|rdS|jD]K} ||d{V#t $r }t jd||Yd}~Dd}~wwxYwdS)uCopy :attr:`skill_paths` into ``${workdir}/skills`` once. Skips seeding when: - :attr:`skill_paths` is empty; - the backend is not bound; or - ``skills/`` already contains entries (assume the prior run, or the user, is the source of truth). Individual failures are logged and skipped — a single bad skill cannot block startup. NzSkip skill %r: %s)r$r"rr@rrr r)r,rerr4rs r- _setup_skillszWorkspaceBase._setup_skillss  F- ? F(()9::::::::   F$  D nnT**********   '   sA!! B +BB )r(N)9rV __module__ __qualname____doc__r__annotations__boolrr6rr7r8propertyr.r9r=r@rBrDrF staticmethodrKrrMrPrRr;rrXobjectr[r]rrjrlrorrrrrrrrrrrrDEFAULT_MAX_EXTRACTED_BYTESrbytesrintrrrrrr*r0r-rrs  8 LLLENNN0D    Ky/!!!*cF  ?|A7 3:X$(/3(, %*%*%*Dj%*9o, %* #Y% %*  %*%*%*%*RL3LLLXL S   X  s   X L3LLLXLtX # # # # #\ #EEE^E555^5     [&$Ft9999^9  $x.    < i       d    ^   S T   ^ @663i6 6666p99%9 9999v/ i/ I/ / / / f.4;....`CF#CF$CFCFCFCFT$? YIYIe$YI+ ,YI YI ! YI  YIYIYIYIvCcCcCCCC>cc(@s@t@@@@:r0r)1rr7rrrrurrrabcrcopyrpathlibrtypingrrrpydanticr _loggingr _utils._commonr r mcprmessagerrrrrrskillrrhrr_utilsrrrrrrrrr*r0r-r)s,,\   //////////@@@@@@@@((((((((. J0Y Y Y Y Y Y Y Y Y Y r0