ێj&dZddlZddlZddlZddlZddlZddlZddlmZm Z m Z ddl Z ddl m Z ddlmZddlmZmZdd lmZdd lmZdd lmZdd lmZdd lmZmZmZGdde ZGdde Z de!de!fdZ"GddeZ#dS)zThe local workspace class.N) AsyncIteratorLiteral TypedDict)DEFAULT_WORKSPACE_INSTRUCTIONS)logger) _generate_id_normalize_local_path) MCPClient)Skill)ToolBase) LocalBackend)DEFAULT_MAX_EXTRACTED_BYTES_EXTRACT_ARCHIVE_SHIM WorkspaceBasec*eZdZUdZeed< eed<dS) _SkillEntryz)A single entry in the .skills index file.hash skill_nameN)__name__ __module__ __qualname____doc__str__annotations__SC:\Projects\DSCons\.venv\Lib\site-packages\agentscope\workspace\_local_workspace.pyrrs-33 III7OOOMMrrc:eZdZUdZeed< eeefed<dS) _SkillsFilez:Schema of the .skills index file stored inside skills_dir.skills_dir_mtimeskillsN) rrrrfloatrdictrrrrrr!r!%s=DDE k! """"NNrr!namereturnc.tjdd|S)aSanitize a skill name into a safe directory name. Allowed characters: ASCII letters, digits, CJK unified ideographs, hyphens, and underscores. Everything else is replaced with ``_``. Args: name (`str`): The raw skill name from SKILL.md frontmatter. Returns: `str`: A sanitized string safe to use as a directory name on Windows, macOS, and Linux. u [^\w一-鿿-]_)resubr&s r_sanitize_dir_namer-.s 6"C . ..rc eZdZdZdddeddededzdeedzdeedzded df fd Zd ee fd Z d*d Z d efd Z ded e fdZdede d dfdZded eeeefdzfdZded eeeefdzfdZd*dZd*dZd eefdZdede ded e fdZdeded edzfdZded dfdZd ed dfd!Zded dfd"Zefd#eed$e d%d&ed'e!d df d(Z"d ed dfd)Z#xZ$S)+LocalWorkspaceuMLocal-directory workspace. Layout:: {workdir}/ ├── .mcp # persisted MCP client configs (JSON array) ├── data/ # offloaded multimodal files ├── skills/ # skill subdirectories └── sessions/ # per-session context and tool-result files N) workspace_id default_mcps skill_paths instructionsworkdirr0r1r2r3r'ct|tj||_|d|j|_t|pg|_ d|pgD|_ t|_ g|_ tj|_tj|_dS)aConstruct a :class:`LocalWorkspace`. Args: workdir (`str`): Filesystem path to the workspace root. Created on demand. Always resolved to an absolute path. workspace_id (`str | None`, optional): Existing workspace identifier to adopt. ``None`` generates a fresh UUID. default_mcps (`list[MCPClient] | None`, optional): MCP clients seeded into a brand-new workspace. Ignored on subsequent restarts that already have a persisted ``/.mcp`` file. skill_paths (`list[str] | None`, optional): Local skill directories seeded into ``/skills`` on first :meth:`initialize`. instructions (`str`, defaults to `_DEFAULT_WORKSPACE_INSTRUCTIONS`): System-prompt fragment template returned by :meth:`get_instructions`. Supports the ``{workdir}`` placeholder. )r0local)backendr4c,g|]}t|Sr)r ).0paths r z+LocalWorkspace.__init__..vs.' ' ' ,0 !$ ' '' ' ' rN)super__init__osr:abspathr4formatr3listr1r2r_backend_mcpsasyncioLock _skill_lock _mcp_lock)selfr4r0r1r2r3 __class__s rr=zLocalWorkspace.__init__Ls> l333ww// (//L0   .2,2D"-E-E' ' 4?4E2' ' '  % &( "<>> rcRKddlm}m}m}m}m}m}m}|}d|i} |j |j | d<tj dkr||j |} n||j |} | |||d i| ||||||gS) z?Return builtin tools, using PowerShell as the shell on Windows.r)BashEditGlobGrep PowerShellReadWriter7Nglob_helper_pathnt)cwdr7)r7r) toolrKrLrMrNrOrPrQ get_backend_glob_helper_pathr>r&r4) rHrKrLrMrNrOrPrQr7 glob_kwargsshells r list_toolszLocalWorkspace.list_toolss JJJJJJJJJJJJJJJJJJ""$$&0  ! -.2.DK* + 7d??(jT\7KKKEEDT\7;;;E  D ! ! ! D  ;   D ! ! ! D ! ! ! E' " " "   rc K|jrdStj|jdtj|jd}|j|d{Vr|j|d{V}tj | d}|D]p} |j tj|0#t $r4}t#jd|dd|Yd}~id}~wwxYwn3t)|j|_ |d{Vg}|j D]s}|jrj|jsc |d{V,#t $r:}t#jd |j|| |Yd}~kd}~wwxYwt|D]}|j |tj|jd }tj|d||d{V} | d } d | D} d | D} t=| } d }|j D]}|!|d{V}|!|\}}}|| vrt#j"d||ddJ|}d}|| vr|d|d}|dz }|| vtG|}|}d}|| vr|d|}|dz }|| vtj||}tj$|%tj$|tj&zst#jd| tOj(tRj*||d d{Vn<#t $r/}t#jd||tW|Yd}~{d}~wwxYwt#j"d||||||d}|| |<| ,|| ,|| ,|d}|rJ| | d <|j-|d{V}||nd| d<|.|| d{Vd|_dS)a5Initialise the workspace. MCP state is restored from ``.mcp`` if it exists; otherwise ``default_mcps`` are used and persisted so the next start picks them up from disk. ``skill_paths`` are seeded on first use. Idempotent: a no-op when the workspace is already alive. NTexist_ok.mcputf-8z#Skipping invalid MCP entry '%s': %sr&?z2Failed to connect stateful MCP '%s': %s, removing.r#ch|] }|d Srrr9es r z,LocalWorkspace.initialize..$J$J$J1QvY$J$J$Jrch|] }|d Srrrcs rrez,LocalWorkspace.initialize..)* * * !AlO* * * rF1Skill '%s' (hash: %s...) already exists, skippingr ()r)z0Skill '%s' resolves outside skills_dir, skipping dirs_exist_okz%Failed to copy skill '%s' from %s: %s2Copied skill '%s' (agent name: '%s') from %s to %srrr")/is_aliver>makedirsr4r:joinrB file_exists read_filejsonloadsdecoderCappendr model_validate Exceptionr warninggetrAr1_save_mcp_file is_stateful is_connectedconnectr&remove_load_skills_filevaluessetkeysr2_validate_and_hash_skillinfor-realpath startswithseprD to_threadshutilcopytreeradd stat_mtime_save_skills_file)rHmcp_filerawraw_listmrdfailedmcp skills_dir skills_fileexistingexisting_hashesexisting_agent_namesexisting_dir_namesupdated skill_pathresultr)raw_name skill_hash agent_namecounterbase_dirdir_name dest_pathentrymtimes r initializezLocalWorkspace.initializesk =  F DL400007<< f55**844 4 4 4 4 4 4 ( //99999999Cz#**W"5"566H  J%%i&>q&A&ABBBB N=fc** d/00DJ%%'' ' ' ' ' ' ' '"$: ' 'C 's'7 ''++--'''''''' '''NL MM#&&&&&&&& ' # #C J  c " " " "W\\$,99  J.... 22:>>>>>>>> +6x+@%K$J8I8I$J$J$J* * %-__%6%6* * * (+8==??';';*H H J88DDDDDDDDF~&, #Ax_,, GrrN "JG 444 (66G666 1  444 *(33HHG000&22221 000 Z::I7##I..99  ,,rv5 F 'O"'     ;FF    KD    +5J!O!OE!&HX     + + + $ $Z 0 0 0  " "8 , , ,GG  B$,K !-22:>>>>>>>>E* * +(([AA A A A A A A A sH8,C%% D#/*DD#4F G0GG(P P: $P55P:cK|jS)zGet the workspace instructions.)r3)rHs rget_instructionszLocalWorkspace.get_instructions*s  rrc*Ktj|d}|j|d{VsdidS |j|d{V}t j|d}tt| dd| diS#t$r2}tjd|t|didcYd}~Sd}~wwxYw) zLoad the .skills index file, returning an empty structure if absent. Args: skills_dir (`str`): The skills directory path. Returns: `_SkillsFile`: The parsed index, or a fresh empty structure. .skillsNrr)r"r#r_r"r#z"Failed to load .skills from %s: %s)r>r:rurBrvrwrxryrzr!r$rr}r r~r)rHrr:rdatards rrz LocalWorkspace._load_skills_file.s7w||J 22]..t44444444 ;(+r:: : ; //55555555C:cjj1122D!&txx0BC'H'H!I!Ixx"--  ; ; ; N?s1vv N N N(+r:: : : : : : : ;s B C D 'D D DrcTKtj|d} |j|t j|dddd{VdS#t$r.}tj d|t|Yd}~dSd}~wwxYw)zPersist the .skills index file. Args: skills_dir (`str`): The skills directory path. data (`_SkillsFile`): The index to write. rrF)indent ensure_asciir_Nz Failed to save .skills to %s: %s) r>r:rurB write_filerxdumpsencoder}r r~r)rHrrr:rds rrz LocalWorkspace._save_skills_fileFsw||J 22 M-** 4>>>EEgNN          M M M N=tSVV L L L L L L L L L MsA A// B'9#B""B'rcKtj|d} |j|d{Vst jd|dS|j|d{V}|d}tj |}| d}| d}|r|st jd|dSt|t||fS#t$r.}t jd|t|Yd}~dSd}~wwxYw) aIValidate if a skill path contains a valid SKILL.md file. Args: skill_path (`str`): The path to the skill directory. Returns: `tuple[str, str, str] | None`: A tuple of (name, description, skill_md_content) if valid, None otherwise. SKILL.mdNz'Invalid skill at %s: SKILL.md not foundr_r& descriptionzKInvalid skill at %s: SKILL.md missing required fields (name or description)z"Failed to validate skill at %s: %s)r>r:rurBrvr r~rwrz frontmatterryrrr}) rHr skill_md_pathr content_strcontentr&rrds r_validate_skillzLocalWorkspace._validate_skillZsy Z<< " 22=AAAAAAAA =t // >>>>>>>>C**W--K"' 44G;;v&&D!++m44K { 3 tt99c+.. ; ;    N4A    44444  s$5DB D)D E#D;;EcK||d{V}|dS|\}}}tj|d}|||fS)a6Validate a skill and compute its hash. Args: skill_path (`str`): The path to the skill directory. Returns: `tuple[str, str, str] | None`: A tuple of (skill_path, skill_name, skill_hash) if valid, None otherwise. Nr_)rhashlibsha256r hexdigest)rHrvalidation_resultrr)skill_md_contentrs rrz'LocalWorkspace._validate_and_hash_skills#'"6"6z"B"BBBBBBB  $4*;' A'^  # #G , ,  )++ :z11rcHK|j4d{V|jD]^}|jrU|jrN |d{V,#t $r%}t jd|j|Yd}~Vd}~wwxYw_ dddd{Vn#1d{VswxYwYd|_ dS)uClose every stateful MCP attached to this workspace. ``LocalWorkspace`` itself owns no resources (the workdir is the persistence layer and is left untouched), but stdio / stateful HTTP MCPs hold long-lived sessions that have to be closed explicitly. Stateless HTTP MCPs are skipped — they spin up an ad-hoc session per call and have nothing to close. Nz7Failed to close MCP %r when closing local workspace: %sF) rGrCrrcloser}r r~r&rs)rHrrds rrzLocalWorkspace.closes{>        z  ? s'7  !iikk))))))))$!C H                              s:B AB  A3A.)B .A33B  BBcPK|j4d{V|jD]^}|jrU|jrN |d{V,#t $r%}t jd|j|Yd}~Vd}~wwxYw_g|_tj |j d}|j |d{Vdddd{Vn#1d{VswxYwY|j4d{Vtj |j d}|j |d{Vdddd{Vn#1d{VswxYwYdD]G}tj |j |}|j |d{VHdS)zReturn the workspace to an empty state. Closes and drops all MCPs (including the persisted ``.mcp``) and deletes ``skills/``, ``sessions/``, and ``data/``. ``default_mcps`` and ``skill_paths`` are not re-seeded. Nz$MCP %r close failed during reset: %sr^r#)sessionsr)rGrCrrrr}r r~r&r>r:rur4rB delete_pathrF)rHrrdr skills_pathr+r:s rresetzLocalWorkspace.resets> 6 6 6 6 6 6 6 6z  ?s'7!iikk))))))))$BH DJw||DL&99H-++H55 5 5 5 5 5 5 5 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 # 9 9 9 9 9 9 9 9',,t|X>>K-++K88 8 8 8 8 8 8 8 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9( 2 2C7<< c22D-++D11 1 1 1 1 1 1 1 1 2 2sNCAC A3A.)C.A33AC C"C3AE  EEc NKtjjdj4d{Vjd{Vsgcdddd{VSd{V}jd{V}|d}||dkr ||d{V}fd|d D}tj |ddid{V}g}t|d|D]U\}}t|tr$t!jd|t%|>|||V|cdddd{VS#1d{VswxYwYdS) aList all skills available in the workspace. The method uses the .skills index for agent-facing names, compares the skills directory mtime to detect manual additions/removals since the last write, and reconciles the index when a change is found. Returns: `list[Skill]`: A list of Skill objects found in the workspace. r#Nrrr"cg|]?\}}tj||d@Srh)_load_single_skillr>r:ru)r9rrrHrs rr;z.LocalWorkspace.list_skills..sZ $He ''GLLX66,'rreturn_exceptionsT Failed to load skill from %s: %s)r>r:rur4rFrBis_dirrr_reconcile_skills_diritemsrDgatherzip isinstancer}r r~rr{) rHr current_mtimetasksresultsr#rrrs ` @r list_skillszLocalWorkspace.list_skillssW\\$,99 #& & & & & & & & --j99999999 & & & & & & & & & & & & & & !% 6 6z B BBBBBBBK"&-":"::"F"FFFFFFFM$ #  ,> ???$($>$>!%%  (38'<'B'B'D'D E$NEJTJJJJJJJJGF$' H(=w$G$G * * &fi00*N: F  'MM&)))M& & & & & & & & & & & & & & & & & & & & & & & & & & & & & & s"F,DF F!Frrc.K|d}|d}|j|d{V}t}|D]W}tj||} |j| d{Vr||Xt|} d} | |z D]} tj d| || =d} d| D} d| D}|| z D]}tj||}| |d{V}|@|\}}}||vrtj d |`|}d }|| vr|d |d }|d z }|| v||d }|||<| |||d} tj d||||d<||d<| s||kr| ||d{V|S)akReconcile the .skills index after the skills directory has changed. Handles: - Manually deleted subdirectories: removed from the index. - Manually added subdirectories: validated and added with conflict resolution for both directory name and agent-facing skill name. Args: skills_dir (`str`): Path to the skills directory. skills_file (`_SkillsFile`): The current (stale) index. current_mtime (`float`): The freshly-read mtime of skills_dir. Returns: `_SkillsFile`: The updated index (also persisted to disk). r#r"NFz,Skill directory '%s' removed, updating indexTch|] }|d Srhrrcs rrez7LocalWorkspace._reconcile_skills_dir..Erirch|] }|d Srbrrcs rrez7LocalWorkspace._reconcile_skills_dir..Hrfrz;Manually added skill '%s' already tracked by hash, skippingrrlrmrqz4Manually added skill '%s' indexed as agent name '%s')rBlist_dirrr>r:rurrrr rrrr)rHrrrroriginal_mtimeentries actual_dirsddir_path indexed_dirsrremovedrrnew_dirrrr)rrrrrs rrz$LocalWorkspace._reconcile_skills_dirs*,7x+@$%78 ..z:::::::: #  # #Aw||J22H]))(33333333 #"""8==??++ $k1  G K>   !GG* * %-__%6%6* * * %K$J8I8I$J$J$J"\1  Gj'::J88DDDDDDDDF~&, #Ax_,,  !JG 444 (66G666 1  444+5J!O!OE %HW  $ $Z 0 0 0    + + +G KF     !) H*7 &'  Bm~55(([AA A A A A A A Ar skill_dirrcKtj|d} |j|d{VsdS|j|d{V}|d}|j|d{V}|d}tj |}| d}|stj d|dSt|t|||j|S#t $r.} tj d|t| Yd} ~ dSd} ~ wwxYw) aLoad a single skill from disk using the agent-facing name from the index. Args: skill_dir (`str`): The skill directory path containing SKILL.md. skill_name (`str`): The agent-facing name stored in the .skills index. Returns: `Skill | None`: A Skill object or None if the SKILL.md is missing/invalid. rNrrr_rz2SKILL.md in %s is missing 'description'. Skipping.)r&rdirmarkdown updated_atr)r>r:rurBrvrrwrzrryrr r~r rrr}) rHrrrrrrrrrds rrz!LocalWorkspace._load_single_skillws$ Y ;; " 22=AAAAAAAA t#}77 FFFFFFFFJ!  // >>>>>>>>C**W--K!' 44G!++m44K Ht ,, %      N2A    44444  s$ DBD!%D D?#D::D? mcp_clientcK|j4d{Vtfd|jDrtdjdjr!jsd{V|j| d{Vdddd{VdS#1d{VswxYwYdS)a|Add an MCP client, connect it if stateful, and persist. Args: mcp_client (`MCPClient`): The MCP client to add. Raises: ValueError: If an MCP with the same name already exists. Names are unique because they compose the model-facing tool name ``mcp__{name}__{tool}``. Nc38K|]}|jjkVdS)Nr,)r9rrs r z)LocalWorkspace.add_mcp..s,AA16Z_,AAAAAArzMCP z already exists in workspace.) rGanyrC ValueErrorr&rrrr{r)rHrs `radd_mcpzLocalWorkspace.add_mcps> ( ( ( ( ( ( ( (AAAAdjAAAAA  K:?KKK% +j.E + ((********* J  j ) ) )%%'' ' ' ' ' ' ' ' ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( (sBB99 CCr&cK|j4d{Vt|jD]\}}|j|krp|jr!|jr|d{V|j||d{Vdddd{VdS dddd{Vn#1d{VswxYwYtj d|dS)zRemove an MCP client by name, disconnecting it if stateful. Args: name (`str`): The ``name`` field of the client to remove. Nz$MCP client %r not found in workspace) rG enumeraterCr&rrrpoprr r~)rHr&irs r remove_mcpzLocalWorkspace.remove_mcps>        #DJ//  38t##*3+;*!iikk)))))))JNN1%%%--/////////              #                             =tDDDDDsBB9%B99 CCcKt|}tj|jd}|j4d{Vtj|d||d{V}|td|d|\}}}| |d{V}|d}d| D} || vr2tj d||dd  dddd{VdSd | D} t|} |} d } | | vr|d | d } | d z } | | vt|}|}d } || vr|d| }| d z } || vtj||}tj|tj|tjzstd|dt'jt*j||dd{Vtj d|| |||| d||<||d<|j|d{V}||nd|d<|||d{Vdddd{VdS#1d{VswxYwYdS)aAdd a skill to the workspace by copying from the given path. The skill directory must contain a valid ``SKILL.md`` file with ``name`` and ``description`` frontmatter fields. Duplicate skills (identified by the SHA-256 hash of ``SKILL.md``) are silently skipped. Name and directory conflicts are resolved by appending a numeric suffix. Args: skill_path (`str`): Absolute or relative path to the skill directory to copy. Raises: ValueError: If the skill at ``skill_path`` is invalid (missing or malformed ``SKILL.md``). r#NTr\zInvalid skill at zK: missing or malformed SKILL.md (requires 'name' and 'description' fields).ch|] }|d Srbrrcs rrez+LocalWorkspace.add_skill..s(N(N(Nq6(N(N(Nrrjrkch|] }|d Srhrrcs rrez+LocalWorkspace.add_skill..s)...$%,...rrrlrmr)z Skill path z resolves outside skills_dir.Frnrprqrrr")r r>r:rur4rFrtrrrrr rrrr-rrrrDrrrrBrr)rHrrrr)rrrrrrrrrrrrrs r add_skillzLocalWorkspace.add_skills"+:66 W\\$,99 #J BJ BJ BJ BJ BJ BJ BJ B K T 2 2 2 288DDDDDDDDF~ K KKK '- #Ax $ 6 6z B BBBBBBBK/:8/DH(N(NHOO>>>>>>>E* * +(([AA A A A A A A AUJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BJ BsB1J;F J;; KKstreamfmt)rtartar.gzrmax_extracted_bytesc 6Ktj|jdt }|d|dkrdn|} |j||d{V|jddt|||t|gd{V}| s+td|j dd |||d{Vd{V|j|d{V|j|d{VdS#|j|d{V|j|d{VwxYw) uExpand a skill archive, then install it as a local directory. Unpacks inside the workspace and hands the result to :meth:`add_skill`, so hash dedup, name conflict resolution and the ``.skills`` index behave exactly as for a path install — which is also why ``dir_name`` is ignored here: the directory name comes from the ``SKILL.md`` front matter. Args: stream (`AsyncIterator[bytes]`): The archive bytes, in order. fmt (`Literal["zip", "tar", "tar.gz"]`): The archive format. dir_name (`str`): Unused; kept for interface compatibility. max_extracted_bytes (`int`): Ceiling on the archive's expanded size. Raises: ValueError: If the archive holds no valid ``SKILL.md``. RuntimeError: If expanding the archive fails. z.skill-staging-.rNpython3z-cz Failed to expand skill archive: r_replace)r>r:rur4r rB write_stream exec_shellrrok RuntimeErrorstderrrzr_find_skill_rootr)rHrrrrstaging archive_pathrs radd_skill_archivez LocalWorkspace.add_skill_archive6s>',, L .lnn . .  "JJxHHSJJ  :-,,\6BB B B B B B B B=33) +,,        F99;; "B}++GY??BB..t'<'r:rur4rFrBrr r~rrrrrr) rHr&rrr target_dirrrskill_dir_pathrs r remove_skillzLocalWorkspace.remove_skillqsW\\$,99 #, B, B, B, B, B, B, B, B--j99999999 M , B, B, B, B, B, B, B, B, B, B, B, B, B, B!% 6 6z B BBBBBBBK/:8/DH%)J#+>>#3#3  %&$..!)JE/!@$GGG', B, B, B, B, B, B, B, B, B, B, B, B, B, B* W\\*jAAN])).99999999 m//????????? 0" /# $$,K !-22:>>>>>>>>E* * +(([AA A A A A A A AY, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, B, Bs7G%?A'G%9CG%% G/2G/)r'N)%rrrrrrrAr r=rrZrrr!rrtuplerrrrr rr$rrrrrrrbytesrintrr __classcell__)rIs@rr/r/@s  $(/3(,:3(3(3(3(Dj 3( 9o, 3( #Y% 3(3( 3(3(3(3(3(3(j $x.    .PPPPd!!!!!;#;+;;;;0MMM  MMMM(33 sC}  $3333j22 sC}  $2222822222>24;2222h^^!^ ^  ^^^^@666  6666p( (d((((.ESETEEEE"]B#]B$]B]B]B]BH$? 9:9:e$9:+ ,9: 9: ! 9:  9:9:9:9:v:Bs:Bt:B:B:B:B:B:B:B:Brr/)$rrDrrxr>r*rtypingrrrr_utilsr_loggingr _utils._commonr r rr skillr rUrtool._builtin._backendr_baserrrrr!rr-r/rrrrs  4444444444222222@@@@@@@@111111NNNNN)NNNOOOOO)OOO/S/S////$k Bk Bk Bk Bk B]k Bk Bk Bk Bk Br