Table of Contents

🇬🇧 English version

Conformité VFS

Orkeon impose au code du framework un principe Virtual File System (VFS) uniquement : tout accès au système de fichiers doit passer par IFileSystemService afin que les frontières de mounts, les droits d'accès et la validation des chemins soient respectés uniformément. L'usage direct de System.IO.File, System.IO.Directory, FileStream, FileInfo, DirectoryInfo et FileSystemWatcher est interdit dans les assemblies du framework.

Ce document décrit :

  • l'analyseur Roslyn Orkeon.Compliance.Vfs qui applique la règle Ă  la compilation
  • ses sept codes de diagnostic ORKVFS et leurs sĂ©vĂ©ritĂ©s (le mĂŞme analyseur porte aussi ORKCON001, voir ConformitĂ© console)
  • les pĂ©rimètres exemptĂ©s et la manière d'opter pour une exception documentĂ©e

L'analyseur

Projet : src/analyzers/Orkeon.Compliance.Vfs/ Cible : analyseur Roslyn netstandard2.0, câblé dans src/Directory.Build.props avec OutputItemType=Analyzer.

L'analyseur s'applique à chaque projet sous src/ sauf lui-même (une ProjectReference avec ReferenceOutputAssembly=false), donc les violations cassent le build immédiatement. tests/analyzers/Orkeon.Compliance.Vfs.Tests exerce chaque règle sur des extraits compilés.

Les appels sont jugés sur leur symbole résolu, pas sur leur graphie : using static System.IO.File; ReadAllText(p) déclenche ORKVFS001 comme File.ReadAllText(p), et un FileStream fs = new(path, …) typé par la cible déclenche ORKVFS003 comme new FileStream(path, …).

Le même analyseur est publié sur NuGet sous le nom Orkeon.Compliance.Vfs (dépendance de développement, sans aucune dépendance d'exécution vers Orkeon — voir la matrice de publication), pour les projets qui veulent le même garde-fou. Hors de ce dépôt, ses sévérités se règlent de la manière Roslyn standard, dans .editorconfig (dotnet_diagnostic.ORKVFS007.severity = none pour un projet qui n'utilise pas IFileSystemService).

Codes de diagnostic

Code Sévérité Détecte Correction suggérée
ORKVFS001 Error Appel direct à System.IO.File.* Injecter IFileSystemService et utiliser TryReadAllBytesAsync / WriteAllTextAsync / ExistsAsync / …
ORKVFS002 Error Appel direct Ă  System.IO.Directory.* Utiliser CreateDirectoryAsync, DeleteAsync, EnumerateFilesAsync
ORKVFS003 Error new FileStream(string …), new FileInfo(string), new DirectoryInfo(string) Utiliser OpenReadStreamAsync, OpenWriteStreamAsync, TryGetEntryAsync
ORKVFS004 Error Path.GetFullPath(…) (peut contourner la validation des mounts) Pour une entrée fournie par l'utilisateur, appeler ResolveAndValidate
ORKVFS005 Error new FileSystemWatcher(…) Injecter IVirtualFileSystemWatcher et consommer WatchAsync (événements de changement en chemins virtuels)
ORKVFS006 Error new StreamReader(string) / new StreamWriter(string) (surcharges par chemin) Ouvrir via OpenReadStreamAsync / OpenWriteStreamAsync et envelopper le Stream retourné
ORKVFS007 Error Champ ou paramètre IFileSystemService? nullable Injecter IFileSystemService en dépendance requise (non-nullable)

Tous les diagnostics sont définis dans src/analyzers/Orkeon.Compliance.Vfs/DiagnosticDescriptors.cs et émettent un lien d'aide stable finissant en #ork-vfs-00N — les ancres de la colonne Code ci-dessus sont ces cibles.

Périmètres exemptés (par chemin)

L'analyseur ignore les chemins de l'allowlist (SystemIoUsageAnalyzer.IsExemptByPath). Elle est volontairement étroite — les exemptions par dossier entier ont été remplacées par une allowlist explicite par fichier, pour qu'un nouveau fichier sous le même dossier ne soit pas exempté silencieusement.

Exemptions par dossier (s_exemptFolderSegments) :

  • /core/Orkeon.Domain/FileSystem/ — contrats publics du VFS (l'abstraction elle-mĂŞme)
  • /core/Orkeon.Infrastructure/FileSystem/ — implĂ©mentation du VFS (disk/fake/watcher)
  • /tests/ — les fixtures reposent sur DiskBackedFileSystemService et le disque rĂ©el
  • /examples/ — hors pĂ©rimètre de conformitĂ© du framework

Exemptions par fichier (s_exemptFileSuffixes) — chacune porte un marqueur inline EXCEPTION-… / OUT-OF-SCOPE :

  • Sandbox/SandboxSession.cs — mounts enregistrĂ©s avant la DI (EXCEPTION-BOOTSTRAP)
  • Sandbox/HostProcessRunner.cs, Sandbox/DockerSandbox.cs — sondage de binaires hĂ´te (OUT-OF-SCOPE)
  • Security/PathValidator.cs — la rĂ©solution symlink/realpath est son rĂ´le

Tout autre fichier légitimement « brut » s'appuie sur un [SuppressVfsCompliance] étroit au site d'usage plutôt qu'une exemption par chemin (voir les exceptions permanentes ratifiées ci-dessous).

Opt-out : [SuppressVfsCompliance]

Pour les exceptions documentées qui ne correspondent à aucune exemption par chemin, appliquer l'attribut déclaré dans src/core/Orkeon.Domain/Attributes/SuppressVfsComplianceAttribute.cs (espace de noms Orkeon.Compliance.Vfs). L'analyseur le reconnaît à son nom complet, pas à son assembly : un projet qui ne référence pas Orkeon.Domain en déclare sa propre copie internal — c'est ce que fait Orkeon.Hosting.Aspire :

[Orkeon.Compliance.Vfs.SuppressVfsCompliance("EXCEPTION-BOOTSTRAP: provisions the physical directory the /sandbox mount points at")]
internal sealed partial class SandboxSession { … }

[SuppressVfsCompliance("OUT-OF-SCOPE: probes external toolchain (esbuild) binary location, not a VFS mount.")]
internal string ResolveBinary() { … }

Placement :

  • Assembly — opt-out large pour un projet entier (Ă  utiliser avec parcimonie, prĂ©fĂ©rer un pĂ©rimètre plus Ă©troit).
  • Classe / struct — exempte tous les membres d'un type (p. ex. une classe de bootstrap comme RunnerHost).
  • MĂ©thode / constructeur / propriĂ©tĂ© / champ — pĂ©rimètre le plus Ă©troit.

L'argument reason est obligatoire et doit nommer la catégorie d'audit dont il relève :

  • EXCEPTION-BOOTSTRAP — s'exĂ©cute avant l'enregistrement des mounts VFS.
  • EXCEPTION-WATCHER-BRIDGE — adaptateur qui enveloppe System.IO.FileSystemWatcher pour implĂ©menter un port watcher Orkeon.
  • OUT-OF-SCOPE — sondage au niveau de l'hĂ´te (chemin d'installation du SDK, dĂ©couverte de binaires système) qui ne cible jamais un mount VFS.

EXCEPTION-BACKCOMPAT et EXCEPTION-OBSOLETE ne sont pas des catégories acceptées : tout outil ou service prend un IFileSystemService non nullable (un nullable déclenche ORKVFS007).

Toute nouvelle classe d'exception doit d'abord être consignée dans l'audit de conformité VFS (l'archive des mainteneurs, audit-vfs-compliance-*) avant l'ajout d'une suppression.

Exceptions permanentes ratifiées

Ces accès ne peuvent pas passer par le VFS par nature et sont définitivement autorisés via les marqueurs [SuppressVfsCompliance] inline (ou l'allowlist par chemin) :

Domaine Emplacement Catégorie Justification
Implémentation VFS Domain/FileSystem/*, Infrastructure/FileSystem/* (l'abstraction) C'est le VFS
Bootstrap (pré-DI) SandboxSession, ConsoleApp Cli*MountBootstrapper, Hosting/Runner*, Hosting/CrewMountDeclarations (pré-lit le bloc mounts: d'une crew) EXCEPTION-BOOTSTRAP Lisent appsettings + montent avant que le VFS existe. Couvre le provisionnement d'un montage, jamais l'exposition d'un chemin physique comme chemin virtuel — voir ADR-008
Sondage hôte DockerSandbox, HostProcessRunner, ProcessGitDiffProvider OUT-OF-SCOPE Découvrent docker/dotnet/git sur le PATH, jamais un mount
Toolchain Scripting/Toolchain/EsbuildTranspiler.cs OUT-OF-SCOPE Localise le binaire esbuild + fichiers temp de transpilation ; chaîne d'outils hôte
Toolchain (vérification de types) Scripting/Toolchain/TscTypeChecker.cs OUT-OF-SCOPE (localiser tsc), EXCEPTION-BOOTSTRAP (le dossier de travail) tsc est un processus externe qui lit et imprime des chemins physiques : le vérificateur écrit un dossier de travail (roll-up des typings, tsconfig, copies du script et de ses modules importés dont le pragma orkeon-script est blanchi) sous le répertoire temporaire, hors du VFS et non monté : rien dans le framework ne le relit. Chaque chemin de la sortie du compilateur et d'un message d'échec est remappé vers son chemin virtuel avant affichage ; le dossier est supprimé à la fin, y compris sur annulation
Applications hôtes (pré-DI) orkeon-host (CrewHostService, HostCrewMounts, HostStartup), Hosting/CrewDirectoryLayout, le point d'entrée orkeon (Orkeon.Scripting.Cli, à l'échelle de l'assembly), le Program du REPL EXCEPTION-BOOTSTRAP Valident ou classent les chemins de crew, de script et de settings fournis par l'opérateur avant qu'aucun mount n'existe
Primitive sécurité Security/PathValidator.cs (allowlist) résolution symlink/realpath = son rôle
Watcher bridge Analysis/.../FileSystemWatcherCodebaseWatcher.cs EXCEPTION-WATCHER-BRIDGE Adapte System.IO.FileSystemWatcher vers ICodebaseWatcher
Sonde RaggableTree Analysis/Core/FileSystemDiscoverer.cs (sonde diagnostique uniquement) OUT-OF-SCOPE La découverte batch elle-même utilise EnumerateFilesAsync ; la sonde compte délibérément les entrées physiques pour distinguer « le VFS n'a rien renvoyé » de « le disque est vide »
Persistance SQLite SqliteMemoryProvider, SqliteStateStore gouverné Le moteur exige un chemin réel ; le Data Source est résolu via ResolveAndValidate avant d'atteindre le driver

Ajouter un nouvel outil ou service

  1. Déclarer un paramètre de constructeur IFileSystemService requis, non-nullable et l'injecter via la DI (un nullable déclenche ORKVFS007). Le valider avec ArgumentNullException.ThrowIfNull.
  2. Travailler en chemins virtuels (/workspace/..., /output/..., /tmp/...).
  3. Ne jamais ajouter de fallback System.IO par chemin string. Il n'existe pas de constructeur de rétro-compatibilité — la DI est la seule voie de construction.
  4. Pour énumérer, streamer, copier ou observer, utiliser les méthodes dédiées de IFileSystemService plutôt que les primitives System.IO équivalentes (y compris StreamReader/StreamWriter — envelopper un Stream issu de OpenReadStreamAsync/OpenWriteStreamAsync, jamais un chemin).

Mounts, droits et visibilité

IFileSystemService (Orkeon.Domain.FileSystem) est toute la surface dont un composant a besoin : ResolveAndValidate (virtuel → physique, contrôlé contre un FileAccessRights requis), ToVirtualPath, GetAvailableMounts, EnumerateFilesAsync, ExistsAsync, GetEntryKindAsync, TryGetEntryAsync, TryReadAllTextAsync / TryReadAllBytesAsync, OpenReadStreamAsync, WriteAllTextAsync / WriteAllBytesAsync / AppendAllTextAsync, OpenWriteStreamAsync / OpenAppendStreamAsync, CreateDirectoryAsync, DeleteAsync, CopyAsync. Les notifications de changement viennent de l'interface distincte IVirtualFileSystemWatcher. AddOrkeonFileSystem(configuration) enregistre les deux.

Un mount se déclare par une chaîne — [<ulid>|]<physique>:<virtuel>:<droits>[;<sous-chemin>:<droits>…] :

  • <virtuel> doit commencer par / ; un chemin physique qui contient : ou ;, ou qui finit par une barre oblique inverse, se met entre guillemets ("C:\src\":/workspace:ro).
  • <droits> vaut ro (FileAccessRights.ReadOnly), rw (ReadWrite = Read, Write, Create, Delete) ou rwnd (ReadWriteNoDelete) ; chaque ;<sous-chemin>:<droits> redĂ©finit les droits d'un sous-arbre.
  • L'ULID facultatif de 26 caractères avant | identifie l'entrĂ©e — voir la rĂ©fĂ©rence de configuration.

FileAccessRights est une énumération de drapeaux (Read, Write, Create, Delete) ; chaque opération déclare le droit qu'elle exige et le registre refuse l'appel quand le mount (ou la redéfinition du sous-arbre) ne l'accorde pas. MountVisibility vaut AgentFacing (le défaut, listé par GetAvailableMounts et dans le prompt des agents) ou Internal (ci-dessous).

Répertoire de travail et chemins relatifs

Le registre tient un répertoire de travail (FileSystemRegistry.WorkingDirectory, exposé par IFileSystemService.WorkingDirectory) : le répertoire qu'un hôte a désigné par SetWorkingDirectory(virtualPath) (un chemin absolu dans un mount visible des agents, sans segment . ni ..) tant que son mount est enregistré, sinon /workspace quand un mount visible des agents le réclame, sinon aucun. Les runners le désignent depuis Orkeon:FileSystem:WorkingDirectory, sinon prennent /workspace, sinon /output ; un registre d'exécution (ScopedMountComposition) garde celui du démarrage tant qu'il le monte encore.

  • Un outil fichier (file_read, file_write, edit_file, glob, grep, directory_read, directory_search, count_pattern, les outils node_*, edit_batch, et les outils de donnĂ©es csv_reader, docx_reader, docx_writer, xlsx_reader, xlsx_writer, pdf_reader, xml_parser) rĂ©sout un chemin relatif contre la working_root de l'agent quand il en a une, sinon contre le rĂ©pertoire de travail (WorkingDirectoryResolver.Absolutize) : src/./lib/../stats.js devient /workspace/src/stats.js, chaque appel suivant vise ce chemin, et la rĂ©ponse le renvoie. Le chemin devient absolu avant le contrĂ´le des mounts et la garde de racine : ../p2/x depuis une racine /workspace/wt/p1 est refusĂ© comme hors de la racine. Sans rĂ©pertoire de travail, un chemin relatif reste refusĂ©. structural_search et structural_rewrite (paths), txt_search et mdx_search (path) se rĂ©solvent de mĂŞme, et chaque outil de cette liste, node_outline et node_read compris, refuse un chemin hors de la racine de l'agent avant toute E/S.
  • Un path vide est refusĂ© par path is required: the absolute path of the file, e.g. /workspace/src/stats.js.
  • Un chemin qui ne commence par aucun mount est refusĂ© avec la forme d'une adresse : No mount found for virtual path 'x': a path starts with a mount: /workspace/src/stats.js. Available mounts: ....
  • shell_command sans working_directory s'exĂ©cute dans la racine de l'agent, sinon dans le rĂ©pertoire de travail ; un working_directory relatif se rĂ©sout de mĂŞme. Il ne se replie jamais sur le premier mount qui accorde les droits : avec des mounts mais sans rĂ©pertoire de travail, l'appel est refusĂ© et nomme les mounts. Le working_directory relatif devient absolu avant la garde de racine : ../p2 depuis une racine /workspace/wt/p1 est refusĂ©.
  • Un rĂ©pertoire d'Ă©criture (FileSystemRegistry.WriteDirectory, IFileSystemService.WriteDirectory) reçoit un shell_command d'Ă©criture qui ne nomme aucun working_directory, hors de toute racine d'agent, quand le rĂ©pertoire de travail est refusĂ© pour ses seuls droits. Une commande d'Ă©criture (toute commande hors de la liste en lecture seule) exige tous les droits sur son rĂ©pertoire de travail : lecture, Ă©criture, crĂ©ation et suppression ; un /workspace en lecture seule, comme dans orkeon forge, ne les accorde pas. Tout autre refus (aucun mount, une traversĂ©e, un chemin rĂ©servĂ© par le runtime, le validateur de chemins) est rapportĂ© tel quel. C'est le rĂ©pertoire dĂ©signĂ© par Orkeon:FileSystem:WriteDirectory (SetWriteDirectory, un chemin absolu sans segment . ni .. dont les droits effectifs, surcharges de sous-arbre comprises, accordent l'Ă©criture dans un mount visible des agents, faute de quoi l'hĂ´te refuse de dĂ©marrer), sinon /output quand un mount visible des agents y accorde l'Ă©criture, sinon aucun. Il ne dĂ©pend jamais de l'ordre des mounts. Rien ne change quand le rĂ©pertoire de travail accorde tous les droits (un /workspace montĂ© en lecture-Ă©criture) ; sous une racine d'agent, aucun repli ; sans rĂ©pertoire d'Ă©criture, le refus nomme l'option. Les chemins relatifs des outils de fichiers se rĂ©solvent toujours contre le seul rĂ©pertoire de travail.
  • Un registre d'exĂ©cution reporte les rĂ©pertoires de travail et d'Ă©criture du dĂ©marrage (WorkingDirectoryDesignation.CarryForward) tant qu'il les monte encore ; l'essai de orkeon forge (ForgeTrialScope.Compose) passe aussi par lĂ , sinon il prend son propre /workspace ou /output.

Racine de travail d'un agent et mount

Un agent peut déclarer une working_root (YAML ; AgentBuilder.WorkingRoot(string) ; .workingRoot(path) sur un agent script de .ork.ts) : un chemin virtuel tel que /workspace/.orkeon/worktrees/x qui doit se trouver sous un mount, faute de quoi le run est refusé au démarrage par une erreur qui nomme la racine. C'est une intersection avec les mounts, jamais une extension :

  • les outils fichier (FileToolBase.ResolveVirtualPath, via AgentRootGuard) refusent, avant toute E/S, un chemin du mĂŞme mount situĂ© hors de la racine ; les autres mounts (/output, /tmp) gardent leurs propres droits ;
  • shell_command refuse un rĂ©pertoire de travail ou un argument de chemin hors de la racine, prend la racine pour rĂ©pertoire de travail par dĂ©faut et y restreint les chemins confinĂ©s de son bac Ă  sable (plus, quand la racine est un worktree git liĂ©, les rĂ©pertoires git par lesquels il commite : Confinement du shell) ;
  • un refus reprend la forme du refus VFS : les chemins physiques sont masquĂ©s.

La racine d'un agent script tient chaque outil que son corps exécute. ctx.llm.act et ctx.tools s'exécutent en tant que l'agent. L'espace global tools ne sait pas quel agent l'appelle : il suit la racine des agents ouverts tant qu'ils en partagent une, et refuse l'appel quand des agents de racines différentes s'exécutent en même temps ; un corps qui s'exécute à côté d'autres appelle ctx.tools. Un enfant lancé par spawn_agent ou ctx.spawnBackground sans racine propre s'exécute sous celle de son parent, comme chaque crew.send ultérieur à cette instance.

Absente, rien ne change : les mounts seuls confinent l'agent.

Périmètre de fichiers d'un agent

Un agent peut aussi déclarer une liste filesystem: (YAML ; AgentBuilder.FileSystem(...) en C# ; .filesystem([...]) sur un agent scripté .ork.ts) : les seuls chemins virtuels que ses outils peuvent toucher. Une entrée est un chemin, ou {path, access} avec access parmi ro, rw, rwnd :

agents:
  writer:
    filesystem:
      - /workspace/docs                 # les droits du mount Ă  cet endroit
      - path: /output/report
        access: rwnd                    # réduit à lecture-écriture sans suppression
  • Les droits viennent du mount : une entrĂ©e sĂ©lectionne et rĂ©duit (une intersection), n'Ă©tend jamais. Une entrĂ©e hors de tout mount, ou un access que le mount n'accorde pas Ă  cet endroit (ses surcharges de sous-chemin comprises), refuse le run au dĂ©marrage avec une erreur qui nomme l'agent et l'entrĂ©e ; de mĂŞme un chemin relatif, un .., une entrĂ©e dĂ©clarĂ©e deux fois et une entrĂ©e dont l'accès n'accorde aucun droit. Une liste vide est refusĂ©e au chargement.
  • Un pĂ©rimètre dĂ©clarĂ© est exhaustif : pendant les appels d'outil de l'agent, le système de fichiers refuse tout chemin hors de lui sur tous les mounts, dans sa forme de refus habituelle (Access denied for '<chemin virtuel>'), en nommant l'agent et son pĂ©rimètre, et aucun autre mount. Le contrĂ´le est dans FileSystemService.ResolveAndValidate, avant celui des mounts : tout outil qui passe par le VFS est tenu — les outils fichier, list_mounts (qui liste les entrĂ©es du pĂ©rimètre avec les droits en vigueur), glob/grep, les outils de recherche, PDF et RAG, les pièces jointes e-mail et drive. Un chemin que le pĂ©rimètre accorde mais qu'un mount refuse est refusĂ© dans la mĂŞme forme, en nommant le pĂ©rimètre, jamais les autres mounts du run. shell_command ne lie dans son bac Ă  sable que les entrĂ©es du pĂ©rimètre, chacune avec les droits en vigueur.
  • Un chemin contrĂ´lĂ© est lu comme l'hĂ´te le lit, et quand cette lecture est ambiguĂ« le pĂ©rimètre n'accorde que ce que chaque lecture accorde. Hors Windows, une barre oblique inverse fait partie d'un nom (/output/notes\x.md est le fichier notes\x.md de /output), sauf juste après la racine d'un mount, oĂą le registre la prend pour un sĂ©parateur. L'entrĂ©e la plus spĂ©cifique est aussi cherchĂ©e sans la casse et sans les points ou espaces finaux d'un segment, si bien qu'un hĂ´te insensible Ă  la casse (/output/REPORT, ou /output/report. sous Windows) n'obtient jamais plus que ce que cette entrĂ©e accorde. Le pĂ©rimètre peut ainsi refuser un chemin qu'un hĂ´te sensible Ă  la casse permettrait, jamais l'inverse.
  • Une Ă©numĂ©ration sous un pĂ©rimètre (directory_read, glob, grep, toute Ă©numĂ©ration du VFS) ne donne que les entrĂ©es qu'une lecture permettrait, chacune contrĂ´lĂ©e contre le pĂ©rimètre et les surcharges de sous-chemin du mount. Une suppression rĂ©cursive est refusĂ©e avant que rien ne soit supprimĂ© quand une entrĂ©e sous le rĂ©pertoire retient Delete (/output rw, /output/report ro).
  • Les outils du graphe sĂ©mantique lisent un index qu'un autre run a pu remplir : pendant un appel Ă  pĂ©rimètre, ils Ă©cartent chaque nĹ“ud dont le pĂ©rimètre ne laisse pas l'agent lire le fichier, et tout ce qui en nomme un (une arĂŞte, un chemin d'appel, un cycle, un rĂ©sultat de recherche, une entrĂ©e de complexitĂ© ou de centralitĂ©, la source d'un symbole, en cache ou non). Un nĹ“ud de monorepo ou de paquet (un rĂ©pertoire) reste visible sur le chemin d'une entrĂ©e du pĂ©rimètre ; un nĹ“ud sans chemin virtuel (un symbole externe, un nĹ“ud du plan d'une page Firefox) est gardĂ©. rag_ingest juge chaque source qui n'est pas une adresse web, quelle que soit son Ă©criture (relative, avec barres obliques inverses, enracinĂ©e Ă  la Windows). start_job Ă©crit son journal de job sous jobs/ d'un endroit oĂą le pĂ©rimètre laisse l'agent Ă©crire (/output/jobs d'abord), sinon il est refusĂ© en nommant le pĂ©rimètre.
  • Seuls les appels d'outil de l'agent sont tenus. Les E/S propres du framework pendant le run (mĂ©moire, connaissances, fichiers de sortie, manifestes) ne sont pas celles de l'agent et gardent les droits des mounts.
  • Un enfant lancĂ© depuis un appel d'outil d'un agent Ă  pĂ©rimètre (spawn_agent, une tâche dĂ©lĂ©guĂ©e, ctx.spawnBackground, un crew.send ultĂ©rieur Ă  cette instance) s'exĂ©cute sous le pĂ©rimètre de son parent ; son propre filesystem: ne peut que le rĂ©duire, et une entrĂ©e hors du pĂ©rimètre du parent ou au-delĂ  de ses droits refuse le run de l'enfant. Un enfant qui n'en dĂ©clare aucun tient les droits de son parent sous son propre nom d'agent, que nomment ses refus et son prompt.
  • En .ork.ts, ctx.delegate transmet le pĂ©rimètre de l'appelant comme le fait delegate_work_to_coworker (la racine de travail de l'agent dĂ©lĂ©guĂ© reste la sienne). Un run que le script lance lui-mĂŞme pendant que des agents tournent (crew.run, crew.runAgent, crew.runStream, celui d'une sous-crew) prend le pĂ©rimètre des tentatives ouvertes, et il est refusĂ© quand leurs pĂ©rimètres diffèrent ; tools.* appelĂ© depuis le code est tenu de la mĂŞme façon. Les pĂ©rimètres se comparent par ce qu'ils accordent, chaĂ®ne des parents comprise. Les hooks onAgentStart/onAgentStop d'un agent exĂ©cutent leurs outils sous sa racine de travail et son pĂ©rimètre, un hook de crew sous ceux du premier agent ; un hook de cycle de vie dont les mounts refusent le pĂ©rimètre de l'agent n'est pas exĂ©cutĂ©, et un avertissement dit pourquoi. rag.ingest appelĂ© depuis un corps Ă  pĂ©rimètre dĂ©veloppe ses globs sous le pĂ©rimètre et refuse une source hors de lui.
  • Avec une working_root, la racine doit ĂŞtre dans le pĂ©rimètre (sinon le run est refusĂ©) : le pĂ©rimètre dit ce que l'agent peut toucher, la racine oĂą il travaille par dĂ©faut et oĂą se rĂ©solvent les chemins relatifs. DĂ©clarer les deux donne un rĂ©pertoire par dĂ©faut Ă  un agent Ă  pĂ©rimètre.

Absent, rien ne change : les mounts (et la working_root, s'il y en a une) confinent seuls l'agent.

Le système de fichiers dans le prompt

Un agent qui a un outil de fichiers (IBaseTool.UsesFileSystem : les outils fichier, de recherche, RAG, de pièces jointes, email_parser, image_generation, firefox, index_codebase, incremental_reindex, list_mounts, shell_command) reçoit une section ## File system dans son prompt système : les entrées de son périmètre, sinon les mounts du run visibles des agents (jamais les internes), chacun avec ses droits et ses surcharges de sous-chemin, triés par chemin virtuel pour que le prompt soit le même d'un run à l'autre ; puis sa racine de travail, ou le répertoire contre lequel se résolvent les chemins relatifs (dit hors du périmètre quand il l'est, pour que l'agent écrive chaque chemin en entier). announce_mounts: false la retire, pour un agent ou, au niveau crew, pour chaque agent qui ne fixe pas le sien (AgentBuilder.AnnounceMounts(false), .announceMounts(false)). Le prompt de ctx.llm.act d'un agent scripté est celui du script et ne porte pas cette section : le corps la lit dans ctx.fileSystem.prompt (le même texte, "" quand aucun chemin n'est visible, quand l'agent n'a pas d'outil de fichiers ou quand il fixe .announceMounts(false)) et la place où il veut (AgentFileSystemPrompt.Render la rend pour les deux formes).

Racines internes et accès privilégié

Un runner monte pour lui-même quelques racines en montages internes (Orkeon:FileSystem:InternalMounts, MountVisibility.Internal) : /llm-logs (les fichiers d'échanges de --llm-log), /sandbox (où les sandboxes de code déposent ce qu'elles exécutent), /state (le magasin de checkpoints), /runs (l'historique des runs), /llm-mock et /llm-cassette (--llm-mock, --llm-record/--llm-replay) et /credentials (les jetons OAuth des comptes e-mail et drive — montée seulement quand un compte OAuth de l'une des deux familles est déclaré). Le registre refuse un montage interne à tout appelant ordinaire et le signale comme un chemin inexistant : aucun outil destiné aux agents ne peut l'atteindre ni même le nommer (ADR-008). Les quelques composants qui doivent y écrire demandent PrivilegedFileSystemAccess à la DI, par son nom : l'enregistreur des échanges, les sandboxes de code et les magasins de jetons (FileSystemEmailTokenStore et FileSystemDriveTokenStore, que l'hôte des runners enregistre sur /credentials/email et /credentials/drive). Ils passent toujours par le VFS. Le seul System.IO brut sur ce chemin est la création, par le runner, du répertoire physique credentials et de ses sous-répertoires email et drive (réservés au propriétaire sous Unix) avant qu'aucun montage n'existe — du bootstrap Hosting/Runner*, une portée EXCEPTION-BOOTSTRAP déjà ratifiée, pas une nouvelle catégorie. orkeon run refuse un montage utilisateur qui revendique l'une de ces racines (EnsureReservedRootsAreFree, /state et /runs compris) ; chaque autre point d'entrée refuse les racines qu'il se réserve (/crew et /sandbox pour --list-tools et mcp serve), et tous refusent /credentials, quels que soient les comptes.

Mounts par scope (surcharge ambiante des mounts)

L'ensemble des mounts est un singleton défini au démarrage : AddOrkeonFileSystem construit un FileSystemRegistry unique à partir de Orkeon:FileSystem:Mounts, et IFileSystemService est un singleton au-dessus. C'est correct pour un runner mono-tenant, mais un hôte qui exécute plusieurs crews dans un même processus (p. ex. un moteur d'exécution pilotant un profil différent par run) doit pouvoir donner ses propres mounts à un flux d'exécution sans perturber les autres.

IFileSystemService ne peut pas devenir DI-scoped pour cela : des dizaines de singletons l'injectent, donc une durée de vie scoped en ferait une dépendance captive. À la place, les mounts par scope sont fournis par une surcharge ambiante — IFileSystemScope (enregistré en singleton, adossé à AsyncLocal<FileSystemRegistry?>, AsyncLocalFileSystemScope). Le singleton FileSystemService la lit à chaque opération : il résout contre le registre ambiant quand un flux d'exécution en a installé un, et contre le registre de démarrage sinon. AsyncLocal isole la valeur par flux de contrôle asynchrone, donc des runs concurrents ne voient jamais les mounts les uns des autres, et un hôte qui n'entre jamais dans un scope conserve un comportement identique à l'octet près.

// Dans un scope de run : installer les mounts de ce run pour ce flux async uniquement.
var granted = grantedMountStrings.Select(FileSystemMount.Parse).ToList();
using var registry = ScopedMountComposition.ForExecution(bootRegistry, granted);
using var _ = fileSystemScope.Enter(registry);          // restauré au dispose (imbrication supportée)

// Tout appel IFileSystemService sur CE flux async résout désormais contre `granted` ;
// les autres runs concurrents continuent de voir les mounts de démarrage.

Composer, jamais construire à la main. Entrer dans un scope REMPLACE le jeu de mounts — ActiveRegistry vaut scope?.Current ?? boot, jamais une union — donc un registre bâti sur les seuls dossiers d'une exécution emporte tout le jeu de boot avec lui pour la durée de ce flux. ForExecution reporte donc les mounts de boot et laisse ceux de l'exécution les masquer aux chemins virtuels qu'ils revendiquent ; la substitution plutôt que l'addition est la raison d'être du mécanisme, puisque deux crews recevant chacun /output sur des dossiers différents est précisément ce qu'un registre plat ne sait pas exprimer.

Les deux moitiés du jeu de boot doivent survivre, pour des raisons différentes. Les mounts internes (RunnerVirtualRoots : /llm-logs, /sandbox, /state, /runs, /credentials, …) relèvent de la confidentialité : les perdre arrête la journalisation des échanges, les deux sandboxes de code et le magasin de jetons e-mail, et fait tomber IsUnderInternalMountUnsafe, le contrôle qui empêche l'un d'eux de gagner une seconde adresse atteignable par un agent via un mount de l'exécution. Les mounts agent-facing portent tout autant : orkeon-host monte le dossier de chaque crew hébergé sous /crews puis charge le crew par ce chemin virtuel, depuis l'intérieur du scope. Un registre composé des seuls mounts de l'exécution laisserait le crew injoignable, et ExistsAsync, qui avale le refus, le rendrait comme un échec de run générique.

Qui en entre un aujourd'hui. orkeon-host est le seul hôte de runner livré qui le fasse, une fois par crew hébergé, depuis Orkeon:Host:Crews:*:Mounts — deux crews hébergés peuvent donc adresser chacun son /output sur des dossiers différents, ce que l'unique registre de boot, plat, ne sait pas exprimer. L'essai de orkeon forge (ForgeTrialScope) en entre un aussi, sur ses dossiers d'essai. Tous les autres runners gardent les mounts de boot : un processus par lancement rend la question sans objet chez eux.

Les gardes s'appliquent aux mounts scopés exactement comme aux mounts de démarrage, car elles s'exécutent à chaque opération sur le registre actif : le registre applique les droits de mount + le confinement contre la traversée de chemin, et IPathValidator applique indépendamment les contrôles racine-workspace / chemins bloqués / extensions (PathSecurity:DefaultWorkspaceRoot, AdditionalAllowedDirectories). Un dossier accordé dans Orkeon:Host:Crews:*:Mounts est une entrée du démon : il est lisible où qu'il soit, sans --allow-external-mounts. L'appelant possède la durée de vie du FileSystemRegistry scopé (Enter ne le dispose pas — le disposer soi-même, comme ci-dessus).

Comportement en CI

Les sept diagnostics (ORKVFS001–ORKVFS007) sont tous des erreurs, donc la CI bloque tout merge qui réintroduit un accès fichier System.IO, un StreamReader/StreamWriter par chemin, un Path.GetFullPath sur entrée utilisateur, ou un IFileSystemService nullable dans le code du framework sans attribut [SuppressVfsCompliance] justifié.