Table of Contents

🇬🇧 English version

Sous-systèmes opt-in

Les sous-systèmes ci-dessous ne sont pas enregistrés par défaut : AddOrkeonApplication() et AddOrkeonInfrastructure() (les deux surcharges) les laissent de côté sauf mention contraire d'une ligne, et chacun s'active par son extension dédiée AddOrkeonXxx().

Principe

Certains de ces sous-systèmes ne sont consommés par aucun chemin d'exécution de production — l'hôte invoque le service lui-même (Préversion ci-dessous) ; d'autres sont câblés par les binaires livrés, comme le dit la colonne Activation. Les enregistrer tous par défaut gonflerait le conteneur DI et masquerait leur statut : l'opt-in rend leur activation intentionnelle, documentée et vérifiable.

Six sections qu'aucun binaire livré ne lit. orkeon run, orkeon-host et orkeon-repl n'appellent aucune des extensions qui lisent ToolRateLimiting, TokenBudget, Orkeon:Dlp, Orkeon:Monitoring, Orkeon:MultiModal et Orkeon:VectorSearch. Écrite dans les réglages de l'un de ces binaires, une telle section n'est lue par rien : le run démarre sans la limite, le budget ou le filtrage qu'elle décrit. Le binaire le dit à son démarrage — une ligne sur stderr par section, qui nomme l'extension par laquelle un hôte écrit en C# la lit — et orkeon doctor le rapporte en ligne warn de runner-settings. Il démarre quand même : un fichier de réglages partagé avec un hôte C# est légitime. Voir Quand un réglage est refusé.

Chaque extension d'activation est autoporteuse : elle enregistre (via TryAdd*) toutes les dépendances dont le sous-système a besoin et qui ne sont pas déjà fournies par l'hôte. Prérequis communs à tous : le logging (services.AddLogging()) et, pour les sous-systèmes qui lient des options de configuration, un IConfiguration enregistré (toujours présent dans une application basée sur Host/WebApplication).

L'ordre recommandé est d'appeler l'extension après AddOrkeonInfrastructure() : les TryAdd* laissent alors la priorité aux services déjà câblés par le socle.

services.AddOrkeonApplication();
services.AddOrkeonInfrastructure();

// Activations explicites (exemples)
services.AddOrkeonMonitoring(configuration);
services.AddOrkeonDlp();
services.AddOrkeonA2A(options => options.EnableServer = true);

Catalogue

Sous-système Activation Projet Ports exposés Maturité
Serveur/protocole A2A AddOrkeonA2A(...) Infrastructure IA2AServer, IA2AClient, IA2AAgentDiscovery, IA2ATaskRouter Expérimental (ORKEXP001)
Backend de monitoring AddOrkeonMonitoring(...) Infrastructure IMetricsAggregation, ITraceExplorer Stable
Conformité NIST AddOrkeonNistCompliance() Infrastructure INistComplianceReporter Préversion
DLP (Data Loss Prevention) AddOrkeonDlp() Infrastructure IDlpPolicyProvider, IPiiDetector, IDlpInterceptor (×5) Préversion
Rate-limiting d'outils & budget de tokens AddOrkeonToolRateLimiting() Infrastructure IToolRateLimiter, ITokenBudgetTracker Préversion
Rotation de clés AddOrkeonKeyRotation() Infrastructure IKeyRotationService Stable
Benchmarking d'évaluation AddOrkeonBenchmarking() — les hôtes runner l'enregistrent Infrastructure IBenchmarkRunner Stable
Contenu multi-modal (vision) AddOrkeonMultiModal(...) Infrastructure IContentValidationService, IMultiModalContentLoader Stable
Hooks de kickoff AddOrkeonKickoffHooks() Application ICrewKickoffHookRunner Préversion
Contexte de codebase (RaggableTree) AddRaggableTree(options) — ⚠️ les hôtes runner font l'inverse (opt-out) : RunnerHost l'enregistre par défaut et RaggableTree:Enabled = false le désactive Analysis ICodebaseContextProvider Stable
Sous-système RAG AddOrkeonRag(config) (namespace Orkeon.Rag.DependencyInjection) + AddOrkeonRagTools() (Orkeon.Tools.Rag) ; profils fast/balanced/quality/adaptive/corrective via Orkeon:Rag:Profile (défaut fast) ; balanced/quality/adaptive exigent le cross-encoder ONNX — AddOrkeonOnnxReranker() (Orkeon.Rag.Onnx + Orkeon.Rag.Onnx.Model, poids embarqués, hors-ligne — enregistré par les trois binaires livrés, orkeon, orkeon-host et le REPL, pas par RunnerHost) ; corrective non (le graphe boucle au lieu de reranker) ; le repli web correctif est purement config — AddOrkeonRag câble déjà le transport, les deux interrupteurs Enabled gouvernent (Orkeon:Rag:Corrective:WebFallback politique, Orkeon:Rag:WebFallback transport) — voir la section détaillée plus bas Orkeon.Rag.Abstractions / Orkeon.Rag / Orkeon.Tools.Rag / Orkeon.Rag.Onnx / Orkeon.Rag.Onnx.Model IRagPipeline (à étages / graphe correctif), IRagProfileResolver, IIngestionPipeline, IDocumentStore, IRagEvalHarness, rag_search/rag_ingest/rag_eval (IBaseTool) Stable
Modèles de décision (TypeSafe, Liquid, Kev) AddOrkeonDecisionProvider(configuration) (le fournisseur actif, nommé par Orkeon:Decision:Provider ou déduit des sections Orkeon:TypeSafe / Orkeon:Liquid et des clés TYPESAFE_API_KEY / LIQUID_API_KEY ; Kev n'est jamais que nommé, sa KEV_API_KEY est facultative ; aussi le modèle derrière le juge LLM du gardien (Orkeon:Guardian:Llm, coupé par défaut), et system_one_decide) · AddOrkeonDecisionProfiles(configuration) (Orkeon:Decision:Profiles) — les trois binaires livrés appellent les deux : le fournisseur quand un est nommé ou déduit, les profils dans tous les cas · rerank.kind: decision — voir Modèles de décision Infrastructure / Orkeon.Rag IDecisionModel (SystemOneDecisionModel, un client pour les trois fournisseurs), DecisionLlmProvider avec les étapes route/guard/verify, DecisionInputGuard, DecisionModelReranker, system_one_decide (IBaseTool) Préversion
Étages de middleware EventHub AddOrkeonEventHubObservability() (journalisation + télémétrie) · AddOrkeonEventHubAcl(policy?) (applique les blocs links: des crews — déjà câblé par le host du runner et orkeon-host, avec le défaut permissif : une crew sans liens se comporte comme avant, une crew qui déclare y est tenue ; seule la politique fermée reste un opt-in) · AddOrkeonEventHubIdempotency(capacity?) (point à point seulement, en mémoire, ne survit pas au processus) · AddOrkeonEventHubValidation() (un SchemaId déclaré doit être enregistré — l'existence du contrat, pas la conformité de la charge utile). Chacun est indépendant ; l'ordre d'enregistrement est l'ordre du pipeline — voir EventHub §12 Infrastructure IEventHubMiddleware, ICrewLinkProvider/ICrewLinkRegistry, IEventSchemaRegistry Stable
Persistance d'état d'exécution AddCrewExecutionStatePersistence(...) Infrastructure ICrewExecutionStateManager (durable via IStateStore) Stable
Barrière de permissions (par appel d'outil) AddOrkeonPermissionGate(config) + Orkeon:Security:PermissionGate:Enabled = true Infrastructure IPermissionGate (ModePermissionGate) — consommé par la boucle scriptée ctx.llm.act et par les appels d'outils des crews YAML (ToolInvocationPipeline) Stable
Shell : interpréteurs & git mutant config seule : Orkeon:Tools:Shell:AllowInterpreters = true Tools.Code (ré-enregistre ShellCommandTool avec allowInterpreters: true — équivalent RCE, ligne SECURITY journalisée au premier appel) Stable
Shell : allowlist personnalisée config seule : Orkeon:Tools:Shell:ExtraAllowedCommands (additive) / Orkeon:Tools:Shell:AllowedCommands (remplacement intégral — annule AllowInterpreters) Tools.Code (façonne l'allowlist d'exécutables de ShellCommandTool ; section absente/vide = défauts) Stable
Streaming console LLM natif AddLlmConsoleStreaming(config, enabledByDefault) (la REPL : actif sauf Orkeon:Cli:ConsoleStreaming:Enabled = false) Cli.Commands.Scripting ILlmDeltaSink (ConsoleLlmDeltaSink) — deltas ctx.llm.act streamés rendus sur la console REPL, l'act de premier plan à mesure, tout autre tour ligne entière par ligne entière Stable
Système de plugins AddOrkeonPlugins(...) (jamais enregistré implicitement ; orkeon-repl l'appelle quand ses réglages portent une section Plugins, aucun autre binaire livré ne le fait) Orkeon.Plugins IOrkeonPlugin, IPluginRegistry — découverte par répertoire, AssemblyLoadContext collectables isolés ; ⚠️ les assemblies chargées s'exécutent en pleine confiance — voir Plugins Stable
Embeddings locaux sur machine AddOrkeonLocalEmbeddings() Tools.Embeddings.Local IEmbeddingProvider (BGE-micro-v2 ONNX, 384 dims, CPU, sans clé API) — premier maillon de la chaîne de résolution des embeddings Stable
Fournisseurs de mémoire externes (Redis, SQLite, ChromaDB, Pinecone, LanceDB) + migration Un type — Memory:Provider, le memoryProvider: d'une crew, Orkeon:Rag:Provider — plus la section hôte de ce provider (Orkeon:Redis, Orkeon:Sqlite, Orkeon:ChromaDb, Orkeon:Pinecone, Orkeon:LanceDb), toutes liées par AddOrkeonInfrastructure() ; MemoryProviderFactory distribue une instance partagée par type, qui se connecte au premier usage. AddOrkeonRedisMemory(configuration) fait de Redis l'IMemoryProvider de l'application ; AddOrkeonLanceDb/AddOrkeonChromaDb/AddOrkeonPinecone(configuration) exposent le provider partagé par sa classe (les deux dernières sont appelées par AddOrkeonInfrastructure(configuration) quand leur section existe) · AddOrkeonMemoryMigration() Infrastructure RedisMemoryProvider, LanceDbMemoryProvider (+ LanceDbMigrationService), MemoryMigrationService — voir Système de mémoire Stable
Mémoire cognitive AddOrkeonCognitiveMemory(configuration) (Orkeon:CognitiveMemory ; les exécuteurs l'appellent quand Orkeon:CognitiveMemory:Enabled vaut true) Infrastructure ICognitiveMemoryService — analyse LLM, détection de contradictions, consolidation, score de rappel composite ; requiert un fournisseur LLM (le profil Orkeon:CognitiveMemory:Profile) et un IEmbeddingProvider ; branché sur les runs avec memory: true — voir Système de mémoire Préversion
Journalisation des échanges LLM AddLlmExchangeLogging(logDirectory, options?) (capture JSONL complète + résumé structuré, handler injecté dans tous les clients IHttpClientFactory sauf ceux qu'une famille d'outils exclut par LlmExchangeLogExclusion — les clients drive et mail ; les clients des outils web et du repli web RAG restent capturés, si bien qu'avec --llm-log les pages qu'ils récupèrent finissent dans le JSONL comme des échanges LLM) — câblé par RunnerHost uniquement quand un run passe --llm-log (section LlmLogging) Infrastructure ILlmExchangeLogger, LlmLoggingDelegatingHandler — voir Fournisseurs LLM Stable
Outil d'entrée humaine AddOrkeonHumanInput() (provider de repli qui approuve tout) / AddOrkeonHumanInput<TProvider>() — câblé par le chemin d'exécution des runners Infrastructure human_input (IBaseTool), IHumanInputProvider Stable
Outils de session AddOrkeonSessionTools(configuration?) (Llm:AvailableModels, Orkeon:Cli:Session, Orkeon:Cli:Memory) — câblé par RunnerHost et le REPL Infrastructure session_store, session_snip, token_budget, memory_store, session_cost, session_stats ; ISessionBufferService, ICategoryMemoryStore (sur fichier par projet quand Orkeon:Cli:Memory:Persist est actif, défaut du REPL) — voir Agent de code (TS) Stable
Outil de recherche sémantique AddSemanticSearchTool() (Orkeon.Hosting) — câblé par orkeon run Hosting semantic_search (SearchTool) + adaptateur IEmbeddingService sur IEmbeddingProvider + IVectorMemoryStore en mémoire Stable
Cœur EventHub + outils agents AddOrkeonInMemoryEventHub() · AddOrkeonEventHubTools() — tous deux câblés par RunnerHost (donc orkeon run et orkeon-host) Infrastructure / Tools.EventHub IEventHub (in-process), les sept outils EventHub — voir EventHub Stable
Outils e-mail AddOrkeonEmailTools(configuration) (Orkeon:Tools:Email, inerte tant qu'aucun compte n'est déclaré) · AddOrkeonEmailTokenStore(fileSystem, virtualDirectory) (store des jetons OAuth) — tous deux câblés par RunnerHost ; le REPL ne câble que les outils Tools.Email les 13 outils email_* — voir Outils e-mail Stable
Outils drive AddOrkeonDriveTools(configuration) (Orkeon:Tools:Drive, inertes tant qu'aucun compte n'est déclaré) · AddOrkeonDriveTokenStore(fileSystem, virtualDirectory) (store des jetons OAuth) — tous deux câblés par RunnerHost ; le REPL ne câble que les outils Tools.Drive les 11 outils drive_* — voir Outils drive Stable
Pont Microsoft Agent Framework AddOrkeonAgentFramework() Interop.AgentFramework ICrewAgentFactory (une crew vue comme AIAgent, chargée et lancée dans un scope à elle à chaque tour) — voir ADR-010 Stable

Hors de ce catalogue — enregistrés par AddOrkeonInfrastructure() et gouvernés par la configuration, pas par un geste d'enregistrement : MCP (section MCP, via la surcharge IConfiguration, ou l'hôte des runners dès que MCP:Servers déclare un serveur), la télémétrie et la recherche vectorielle (même surcharge), le store de checkpointing sans paramètre (AddOrkeonCheckpointing() ; les variantes SQLite/Postgres restent explicites), Evaluation, Consensus, CostTracking, YAML, Encryption et CodeSandbox. Le pipeline Guardian, les sanitizers de prompt et de résultats d'outils et le point d'invocation des outils sont eux aussi enregistrés, et chaque tour d'agent les traverse (Orkeon:Guardian:Enabled en est l'interrupteur — voir Sécurité). Leurs sections de configuration sont cartographiées dans la Référence de configuration.

Les familles d'outils s'enregistrent par leurs propres extensions, que l'hôte des runners et le REPL appellent : AddOrkeonFileSystemTools, AddOrkeonWebTools (plus les extensions à outil unique AddOrkeonWebSearchTool, AddOrkeonBraveSearchTool, AddOrkeonCacheSearchTool, AddOrkeonSlackTool, AddOrkeonSlackReadTool), AddOrkeonDataTools (plus AddRelationalDatabaseTools, AddMongoDbTools, AddGraphDatabaseTools), AddOrkeonCodeTools, AddOrkeonDriveTools, AddOrkeonAbstractionTools, AddRaggableTreeTools — voir l'inventaire des outils.

Briques enregistrées par AddOrkeonInfrastructure()

Ce ne sont pas des opt-ins, mais des extensions publiques qu'un hôte croise quand il compose son propre conteneur : chacune est appelée par AddOrkeonInfrastructure() (toutes utilisent TryAdd*, les rappeler est donc sans effet), et chacune peut aussi s'appeler seule quand un hôte construit un conteneur minimal sans l'infrastructure complète.

Extension Enregistre Consommée par L'appeler soi-même quand
AddOrkeonYaml() CrewFactoryOptions (options simples, résolution d'outils tolérante), ICrewDefinitionLoader → YamlCrewDefinitionLoader, ICrewFactory → CrewFactory (scoped), YamlCrewExporter le chargement de crews des runners ; orkeon forge vous chargez ou exportez des crews YAML sans AddOrkeonInfrastructure(). La résolution stricte des outils est Orkeon:CrewFactory:StrictTools, que lit RunnerHost (défaut true chez lui)
AddOrkeonGuardian() GuardianOptions (Orkeon:Guardian), GuardianPolicyEngine, InputGuard/ToolGuard/DelegationGuard, GuardianPipeline (aussi comme IGuardianPipeline) avec les trois gardes branchés sur leurs phases — aucun quand Enabled = false l'orchestrateur d'exécution (phase d'entrée), le service de streaming, et IToolInvocationPipeline (phases outil et délégation) — enregistré par AddOrkeonApplication() vous composez un conteneur sans AddOrkeonInfrastructure() et voulez quand même les gardes — voir Sécurité

Le service de migration de mémoire est la seule extension de déplacement de données qui n'est pas enregistrée par défaut : AddOrkeonMemoryMigration() — voir Système de mémoire.

Maturité — Stable : implémentation testée dont l'API est couverte par l'engagement de stabilité 1.x, sauf les membres marqués [Experimental] (le pipeline RAG correctif dans le sous-système RAG : voir APIs expérimentales) ; ce qu'elle ne fait pas encore, ou ce qui n'a pas été exécuté contre un vrai service, figure dans les Limitations connues. Préversion : implémentation fonctionnelle mais non câblée dans le pipeline d'exécution (l'hôte invoque le service lui-même) ou comportement encore partiel (signalé au cas par cas ci-dessous). L'étiquette parle du comportement, pas de l'API : l'API d'un sous-système en Préversion est figée par le même engagement 1.x que celle d'un sous-système Stable ; seuls son câblage et son comportement peuvent encore s'étendre. Expérimental : réservé à une API marquée [Experimental] (A2A, ORKEXP001), hors de cet engagement — voir APIs expérimentales. Aucune des deux étiquettes ne dit si les binaires livrés activent un sous-système : la ligne Binaires livrés de sa section le dit.


Serveur/protocole A2A — AddOrkeonA2A(...)

Complément persistance des tâches : AddOrkeonA2ATaskPersistence() stocke les cycles de vie des tâches A2A sur l'IStateStore de checkpointing opt-in (à enregistrer d'abord), transformant GET /a2a/tasks/{id} en vrai endpoint 200/404 au lieu du 501 explicite.

  • RĂ´le : communication agent-Ă -agent inter-processus (protocole A2A) : dĂ©couverte d'agents (/.well-known/agent.json), client HTTP, routage de tâches et, en option, un serveur HTTP (HttpListener) exposant POST /a2a/tasks/send, sendSubscribe (SSE), GET/DELETE /a2a/tasks/{id}.
  • Activation :
    // Par configuration (section "A2A" ; "A2A:Security" pour mTLS/auth)
    services.AddOrkeonA2A(configuration);
    
    // Ou par délégué, sans IConfiguration
    services.AddOrkeonA2A(options => options.EnableServer = true);
    
    IA2AServer n'est enregistré que si EnableServer est vrai, avec un service hébergé : un hôte générique démarre le serveur avec lui et l'arrête à l'extinction — aucun code de l'hôte ne résout IA2AServer ni n'appelle StartAsync. Un processus qui ne fait jamais tourner l'hôte ne le démarre jamais.
  • ExĂ©cution : la carte liste les skills du routeur enregistrĂ© (IA2ATaskRouter.GetSkillsAsync) — celui par dĂ©faut, une skill par agent disponible — et le routeur exĂ©cute l'agent dont l'id Ă©gale le skillId de la requĂŞte (l'id que publie la carte) via IAgentExecutionService ; l'hĂ´te appelle donc aussi AddOrkeonApplication() — sans lui, une tâche rĂ©pond Failed et le dit. Un hĂ´te qui route autrement enregistre d'abord son propre IA2ATaskRouter : le routeur par dĂ©faut, et l'annuaire d'agents ci-dessous, ne sont enregistrĂ©s que si aucun routeur ne l'est.
  • DĂ©pendances : l'extension enregistre elle-mĂŞme (TryAdd) IHttpClientFactory, IDomainEventDispatcher, IUnitOfWork, ainsi que — avec le routeur par dĂ©faut — l'annuaire d'agents A2A (IAgentRegistrationStore singleton + IAgentRepository scoped, voir ci-dessous) lorsque l'hĂ´te ne les a pas dĂ©jĂ  câblĂ©s via AddOrkeonInfrastructure().
  • Cycle de vie du dĂ©pĂ´t d'agents (scoped par requĂŞte) :
    • IAgentRepository est scoped ; le routeur (un singleton) ne le capture jamais — il ouvre un scope DI par requĂŞte A2A (la carte, chaque tâche) via IServiceScopeFactory et rĂ©sout le dĂ©pĂ´t dedans. La rĂ©solution passe avec ValidateScopes = true (dĂ©faut en Development).
    • Un dĂ©pĂ´t scoped ne conserve rien entre deux requĂŞtes : les enregistrements vivent dans IAgentRegistrationStore, un backing store singleton thread-safe (InMemoryAgentRegistrationStore, ConcurrentDictionary) dont le dĂ©pĂ´t scoped (SharedStoreAgentRepository) s'hydrate Ă  chaque appel. Les agents enregistrĂ©s par le pipeline (dans ses propres scopes) sont donc visibles du routeur A2A, et rĂ©ciproquement.
    • Composition : si l'hĂ´te a appelĂ© AddOrkeonInfrastructure() (qui enregistre le InMemoryAgentRepository Ă  store par scope), AddOrkeonA2A(...) surclasse cette implĂ©mentation par dĂ©faut vers SharedStoreAgentRepository (mĂŞme durĂ©e de vie scoped, donnĂ©es partagĂ©es) — sinon le routeur ne retrouverait jamais les agents. Tout autre enregistrement d'IAgentRepository (dĂ©pĂ´t custom/BD, qui fournit dĂ©jĂ  un stockage inter-requĂŞtes) est laissĂ© intact. Appeler AddOrkeonA2A(...) après AddOrkeonInfrastructure() et après un Ă©ventuel dĂ©pĂ´t custom (ordre recommandĂ©, cf. Principe) ; un dĂ©pĂ´t custom enregistrĂ© après AddOrkeonA2A(...) gagne (dernier enregistrement).
  • Binaires livrĂ©s : orkeon-host appelle AddOrkeonA2A quand Orkeon:Host:A2A:Enabled est posĂ©, après avoir enregistrĂ© son propre routeur — une skill par crew que la section expose, une tâche Ă©tant un run de cette crew — de sorte que ses runs gardent leur dĂ©pĂ´t d'agents par scope (voir HĂ´te de service) ; orkeon run et le REPL ne l'appellent pas. Voir ConformitĂ© A2A — ExĂ©cution des tâches et Activation.
  • Limites connues : le store in-memory est local au processus — pour un annuaire d'agents multi-instances, fournir un IAgentRepository custom adossĂ© Ă  un stockage partagĂ© externe (il sera respectĂ© tel quel par l'extension).

Backend de monitoring — AddOrkeonMonitoring(...)

  • Binaires livrĂ©s : aucun ne l'active. orkeon run, orkeon-host et orkeon-repl ne lisent pas Orkeon:Monitoring, et le disent Ă  leur dĂ©marrage quand les rĂ©glages l'Ă©crivent.
  • RĂ´le : agrĂ©gation in-process des mĂ©triques Orkeon (MeterListener sur le meter Orkeon) et exploration des traces rĂ©centes (buffer circulaire) pour exposition par un endpoint hĂ´te (dashboard, API de diagnostic).
  • Activation :
    services.AddOrkeonMonitoring(configuration); // lie Orkeon:Monitoring
    services.AddOrkeonMonitoring();              // options par défaut
    
  • DĂ©pendances : logging uniquement (les options par dĂ©faut sont enregistrĂ©es si aucune configuration n'est passĂ©e).
  • Note : ne remplace pas la tĂ©lĂ©mĂ©trie OpenTelemetry (AddOrkeonTelemetry), qui reste câblĂ©e par la surcharge AddOrkeonInfrastructure(IConfiguration).

Traces et métriques suivent les conventions GenAI d'OpenTelemetry

Pas un opt-in — chaque run les émet, et les runners (orkeon run, orkeon-host) les exportent là où pointe la variable standard OTEL_EXPORTER_OTLP_ENDPOINT (un AppHost .NET Aspire la pose — voir ADR-011) ou là où la section Telemetry des réglages le dit (Telemetry:OtlpEndpoint). Le chemin d'exécution lui-même porte les spans, nommés et attribués selon les conventions sémantiques OpenTelemetry pour l'IA générative, si bien que Langfuse, Honeycomb, Application Insights ou le dashboard Aspire les lisent sans mapping. Les noms sont les constantes de Orkeon.Constants.Llm.GenAiAttributes.

Span (ActivitySource) Nom Attributs
Tour d'agent (Orkeon.Agent) invoke_agent {agent} gen_ai.operation.name=invoke_agent, gen_ai.agent.name, gen_ai.agent.id, gen_ai.provider.name, gen_ai.request.model, orkeon.task.id
Appel au modèle (Orkeon.Llm, kind Client) chat {model} gen_ai.operation.name=chat, gen_ai.provider.name (minuscules), gen_ai.request.model, gen_ai.request.temperature, gen_ai.request.max_tokens, gen_ai.response.model, gen_ai.response.id, gen_ai.response.finish_reasons, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, error.type en cas d'échec ; hors d'un tour d'agent (le manager, le planificateur, un appel propre à l'hôte) l'entrée des fournisseurs l'ouvre, avec orkeon.llm.operation, gen_ai.agent.name et orkeon.task.id quand ils sont connus — un par appel, jamais un second dans un chat courant
Embedding (Orkeon.Llm) embeddings {model} gen_ai.operation.name=embeddings, gen_ai.provider.name, gen_ai.request.model, orkeon.embeddings.text_count, error.type en cas d'échec ; un par appel au modèle d'embedding — un embedding servi par le cache n'en a pas
Exécution d'outil (Orkeon.Tool) execute_tool {tool} gen_ai.operation.name=execute_tool, gen_ai.tool.name, gen_ai.tool.call.id (l'identifiant donné par le modèle), gen_ai.agent.name, error.type en cas d'échec
Exécution d'un crew (Orkeon.Crew) crew.run orkeon.crew.id, orkeon.crew.name, orkeon.crew.process, orkeon.crew.task_count ; en erreur quand l'exécution échoue ou est annulée
Tâche (Orkeon.Task) task.run une par tâche, orkeon.task.id ; en erreur quand la tâche échoue ou est annulée
Mémoire (Orkeon.Memory) memory.recall, memory.store sous la tâche qui rappelle ou stocke
Runtime de scripting (Orkeon.Scripting) les trois mêmes, plus crew.run mêmes attributs ; orkeon.llm.method (complete/act), orkeon.crew.name, orkeon.crew.process ; la source figure dans OrkeonActivitySources.AllNames, donc les spans du script sont exportés

Une exécution est une trace : crew.run > task.run > invoke_agent et memory.* ; les chat du manager et du planificateur se placent sous crew.run, les embeddings d'une mémoire sous son span memory.*.

Métriques (meter Orkeon, OrkeonMeter ; le MeterListener l'écoute) : gen_ai.client.token.usage (histogramme, tokens, gen_ai.token.type = input | output) et gen_ai.client.operation.duration (histogramme, secondes), toutes deux étiquetées gen_ai.provider.name et gen_ai.request.model ; les compteurs orkeon.* (appels, exécutions d'outils, coût) gardent leurs noms. Ce qui n'a pas de convention garde le préfixe orkeon. — le crew, la tâche, le coût estimé.

Instrument Type, unité Attributs Mesuré
orkeon.llm.calls compteur, {call} opération, fournisseur, modèle chaque appel au modèle, une fois
gen_ai.client.operation.duration histogramme, s opération, fournisseur, modèle, error.type en cas d'échec chaque appel au modèle
gen_ai.client.token.usage histogramme, {token} opération, fournisseur, modèle, gen_ai.token.type l'usage rapporté par le fournisseur ; un usage non rapporté n'est pas enregistré
orkeon.cost.total_usd jauge observable, USD aucun total, à l'échelle du processus, des coûts en USD rapportés depuis son démarrage ; un coût dans une autre devise n'y entre pas
orkeon.crew.executions compteur, {execution} orkeon.crew.name, orkeon.crew.process, orkeon.outcome (completed, failed, cancelled) chaque exécution de crew, une fois, à sa fin — avec ou sans écouteur de spans
orkeon.crew.duration histogramme, s ceux de orkeon.crew.executions chaque exécution de crew, à sa fin
orkeon.crew.active compteur haut-bas, {crew} orkeon.crew.name, orkeon.crew.process +1 au début d'une exécution, -1 à sa fin
orkeon.task.executions compteur, {execution} orkeon.crew.name, orkeon.agent.role quand la tâche a un seul agent, orkeon.outcome (completed, failed, cancelled) chaque tâche, une fois, à sa fin ; une tâche écartée parce qu'une dépendance a échoué, ou encore ouverte à la fin de l'exécution, compte cancelled
orkeon.task.duration histogramme, s ceux de orkeon.task.executions chaque tâche, à sa fin
orkeon.task.active compteur haut-bas, {task} orkeon.crew.name, orkeon.agent.role quand la tâche a un seul agent +1 au début d'une tâche, -1 à sa fin
orkeon.tool.executions compteur, {execution} orkeon.tool.name, orkeon.outcome (success, failure, blocked, cancelled) chaque appel passé par le pipeline d'outils, une fois, avec ou sans journal d'audit ; une réponse Success=false compte failure
orkeon.tool.duration histogramme, s orkeon.tool.name, orkeon.outcome chaque appel exécuté ; un appel blocked n'a pas de durée
orkeon.security.events compteur, {event} orkeon.security.kind (block, warn, injection), orkeon.tool.name quand il est connu un par appel que le Guardian bloque (une garde qui lève une exception compte block), un par résultat Warn, un par résultat d'outil où un motif d'injection est repéré (pas un par motif)
orkeon.llm.active compteur haut-bas, {call} aucun déclaré, pas encore alimenté

Aucun attribut ne porte l'identifiant d'un crew, d'une tâche ou d'un agent.

Conformité NIST — AddOrkeonNistCompliance()

  • RĂ´le : gĂ©nĂ©ration de rapports de conformitĂ© NIST SP 800-53 Ă  partir de la piste d'audit (IAuditLogger).
  • Activation : services.AddOrkeonNistCompliance();
  • DĂ©pendances : l'extension TryAdd une chaĂ®ne d'audit de repli (StructuredLogAuditSink + AuditLogger) ; quand l'hĂ´te a appelĂ© AddOrkeonInfrastructure(), la chaĂ®ne d'audit du socle (sinks structurĂ© + in-memory, options Security:Audit) est utilisĂ©e.
  • Limites connues : le rapport lit la piste qu'Ă©crivent les tours d'agent — un Ă©vĂ©nement ToolExecution par appel d'outil et un SecurityEvent par blocage ou avertissement du Guardian et par motif d'injection trouvĂ© dans un rĂ©sultat d'outil ; les appels LLM, les accès fichiers et les requĂŞtes HTTP ne sont pas des Ă©vĂ©nements auditĂ©s ; aucun contrĂ´le automatisĂ© n'est exĂ©cutĂ©.

DLP — AddOrkeonDlp()

  • Binaires livrĂ©s : aucun ne l'active. orkeon run, orkeon-host et orkeon-repl ne lisent pas Orkeon:Dlp, et le disent Ă  leur dĂ©marrage quand les rĂ©glages l'Ă©crivent : la DLP n'y filtre rien. Ce qu'ils filtrent se règle par Security:Prompt et Security:ToolResults.
  • RĂ´le : prĂ©vention de fuite de donnĂ©es — dĂ©tection de PII par expressions rĂ©gulières (IPiiDetector), politiques par canal (IDlpPolicyProvider, section Orkeon:Dlp) et 5 intercepteurs de canaux (sortie d'outil, dĂ©lĂ©gation, logs, mĂ©moire, sortie externe).
  • Activation : services.AddOrkeonDlp();
  • DĂ©pendances : logging + IConfiguration (liaison Orkeon:Dlp). Autoporteuse pour le reste.
  • Limites connues : les intercepteurs ne sont pas invoquĂ©s automatiquement par le pipeline d'exĂ©cution — l'hĂ´te les rĂ©sout (GetServices<IDlpInterceptor>()) et les applique aux canaux qu'il veut protĂ©ger. Une exception : l'intercepteur de sortie externe d'un hĂ´te qui a enregistrĂ© la DLP s'applique aux arguments d'un appel d'outil diffusĂ©, retenus jusqu'Ă  la fin de l'appel et Ă©mis en un seul delta rĂ©digĂ©. Ă€ ne pas confondre avec le PiiDetectionValidator du pipeline de validation de sortie, qui reste enregistrĂ© par dĂ©faut et est indĂ©pendant.

Rate-limiting d'outils & budget de tokens — AddOrkeonToolRateLimiting()

  • Binaires livrĂ©s : aucun ne l'active. orkeon run, orkeon-host et orkeon-repl ne lisent ni ToolRateLimiting ni TokenBudget, et le disent Ă  leur dĂ©marrage quand les rĂ©glages en Ă©crivent une. Les limites qu'ils appliquent sont celles des appels au modèle : RateLimiting.
  • RĂ´le : limitation de dĂ©bit par outil (IToolRateLimiter, section ToolRateLimiting) et suivi de budget de tokens par agent/crew (ITokenBudgetTracker, section TokenBudget).
  • Activation : services.AddOrkeonToolRateLimiting();
  • DĂ©pendances : logging + IConfiguration. Si AddOrkeonCostTracking() (inclus dans le socle) a enregistrĂ© IModelPricingRegistry, le tracker l'utilise pour la conversion tokens → coĂ»t. Son estimation de coĂ»t lit les lignes de prix rattachĂ©es Ă  un fournisseur quand l'hĂ´te passe l'identifiant du fournisseur (RecordUsage(crewId, agentRole, promptTokens, completionTokens, model, provider)). L'identifiant est le nom du fournisseur tel qu'Orkeon l'Ă©crit dans Llm:Provider — deepseek, zai, kimi, qwen, gemini, mistral, grok, minimax, together, mammouth, ollama pour les fournisseurs qui ont leurs propres lignes intĂ©grĂ©es ; la casse est ignorĂ©e. Le registre choisit alors la ligne comme pour Orkeon:CostTracking : une ligne CustomPricings l'emporte sur une ligne intĂ©grĂ©e, et dans chaque groupe les lignes rattachĂ©es au fournisseur passent avant celles qui n'en nomment aucun — un modèle Ollama coĂ»te 0 sauf si une ligne CustomPricings le tarife. AppelĂ© sans le fournisseur, ou avec un identifiant qu'aucune ligne ne nomme, le tracker ne lit que les lignes qui ne nomment aucun fournisseur. Un modèle qu'aucune ligne ne tarife est comptĂ© aux taux approximatifs du tracker, avec ou sans le fournisseur.
  • Limites connues : non câblĂ© dans l'exĂ©cution des outils — l'hĂ´te interroge le limiteur/le tracker autour de ses appels d'outils. Le rate-limiting LLM (ILlmRateLimiter), lui, reste enregistrĂ© par dĂ©faut car il est posĂ© Ă  l'entrĂ©e de chaque provider que l'hĂ´te construit ou enregistre — chaque appel au modèle y prend un bail, tour d'agent ou non.

Rotation de clés — AddOrkeonKeyRotation()

  • RĂ´le : re-chiffrement rĂ©el des entrĂ©es d'un store mĂ©moire chiffrĂ© lors d'une rotation de clĂ© — IKeyRotationService.RotateAsync(store, oldProvider, newProvider, options?) — plus la gĂ©nĂ©ration et la persistance d'une nouvelle clĂ© via ProvisionNewKeyAsync(secretStore, secretName, keySizeInBits) (IWritableSecretProvider, implĂ©mentĂ© par DpapiSecretProvider).
  • Fonctionnement : parcours en deux phases. Staging : chaque entrĂ©e est dĂ©chiffrĂ©e avec l'ancienne clĂ©, re-chiffrĂ©e avec la nouvelle et Ă©crite sous une clĂ© de staging (<clĂ©>::rotation-staging) — les originaux restent intacts. Bascule : chaque copie re-chiffrĂ©e remplace son original puis le staging est supprimĂ©. Un marqueur d'Ă©tat (__orkeon.key-rotation.state, JSON en clair) persiste la version de clĂ© et la phase ; chaque entrĂ©e re-chiffrĂ©e porte la propriĂ©tĂ© orkeon-key-version.
  • Échecs et reprise :
    • Ă©chec en staging → rollback automatique des copies de staging : le store reste intĂ©gralement lisible avec l'ancienne clĂ© ;
    • Ă©chec en bascule → roll-forward : relancer RotateAsync avec les mĂŞmes providers reprend la rotation lĂ  oĂą elle s'est arrĂŞtĂ©e. La classification par dĂ©chiffrement authentifiĂ© (AES-GCM) garantit l'idempotence : aucune entrĂ©e perdue, aucune double-chiffrĂ©e ;
    • entrĂ©e illisible avec les deux clĂ©s → Ă©chec fail-closed par dĂ©faut (rollback) ; KeyRotationOptions.ContinueOnUnreadableEntries permet de l'ignorer (entrĂ©e laissĂ©e telle quelle et signalĂ©e dans KeyRotationResult.Errors).
  • Activation : services.AddOrkeonKeyRotation(); — Ă  coupler avec AddOrkeonEncryption() (le fournisseur AES-256-GCM, lui, reste dans le socle).
  • DĂ©pendances : logging uniquement (le store et les providers sont passĂ©s en arguments de mĂ©thode).
  • Marche Ă  suivre :
    var rotation = provider.GetRequiredService<IKeyRotationService>();
    
    // 1. Générer et persister la nouvelle clé sous un nom de secret versionné
    //    (refuse d'écraser un secret existant — fail-closed)
    await rotation.ProvisionNewKeyAsync(writableSecrets, "orkeon-encryption-key-v2");
    
    // 2. Re-chiffrer le store brut (sous le décorateur) de l'ancienne vers la nouvelle clé
    var result = await rotation.RotateAsync(rawStore, oldProvider, newProvider);
    
    // 3. Basculer la configuration de l'hĂ´te sur le nouveau nom de secret
    
  • Limites connues : la rotation s'exĂ©cute sur le provider mĂ©moire brut (sous le dĂ©corateur EncryptedMemoryProviderDecorator, type MemoryProviderBase pour l'Ă©numĂ©ration des clĂ©s) et suppose qu'aucune Ă©criture concurrente n'a lieu pendant la fenĂŞtre de rotation. AesEncryptionProvider.RotateKeyAsync est neutralisĂ© (NotSupportedException) : une rotation « sur place » orphelinerait les donnĂ©es existantes — passer par IKeyRotationService.

Benchmarking d'évaluation — AddOrkeonBenchmarking()

  • RĂ´le : exĂ©cution rĂ©pĂ©tĂ©e d'une suite d'Ă©valuation par cas de test avec statistiques mean/stddev (IBenchmarkRunner).
  • Activation : services.AddOrkeonBenchmarking(); — Ă  coupler avec AddOrkeonEvaluation() (inclus dans le socle) pour construire les suites. L'IEvaluationSuite par dĂ©faut porte les juges LLM quand Evaluation:EnableLlmJudge vaut true — liĂ© par AddOrkeonInfrastructure(configuration).
  • Binaires livrĂ©s : les hĂ´tes runner (orkeon, orkeon-host) l'enregistrent et lient la section Evaluation avec AddOrkeonEvaluation(configuration) ; orkeon eval bench l'exĂ©cute (orkeon eval run note un jeu de donnĂ©es avec la suite par dĂ©faut).
  • DĂ©pendances : aucune (la suite d'Ă©valuation est fournie via BenchmarkConfig Ă  l'appel).

Contenu multi-modal (vision) — AddOrkeonMultiModal(...)

  • Binaires livrĂ©s : aucun ne l'active. orkeon run, orkeon-host et orkeon-repl ne lisent pas Orkeon:MultiModal, et le disent Ă  leur dĂ©marrage quand les rĂ©glages l'Ă©crivent.
  • Statut : rĂ©el — la vision est câblĂ©e de bout en bout : les contenus image circulent des abstractions MultiModalContent (Domain) aux payloads providers via LlmMessage.MultiModalContent. AnthropicLlmProvider Ă©met des blocs de contenu image conformes Ă  l'API Messages ({"type":"image","source":{"type":"base64"|"url",…}}) ; OpenAILlmProvider Ă©met des parts image_url conformes Ă  Chat Completions (URL http(s) ou data URL base64). Voir le guide multi-modal.
  • RĂ´le : validation des contenus multi-modaux (taille, format, durĂ©e) via IContentValidationService (options Orkeon:MultiModal) et chargement d'images depuis le système de fichiers virtuel via IMultiModalContentLoader (lecture VFS → bytes → base64, type MIME infĂ©rĂ© de l'extension, validation des contraintes configurĂ©es).
  • Activation :
    services.AddOrkeonMultiModal(configuration); // lie Orkeon:MultiModal
    services.AddOrkeonMultiModal();              // options par défaut
    
  • DĂ©pendances : IContentValidationService n'a besoin que des options ; IMultiModalContentLoader requiert un IFileSystemService rĂ©solvable (AddOrkeonFileSystem(configuration) dans les hĂ´tes rĂ©els).
  • Limites connues : la composition des payloads vision est pilotĂ©e par capacitĂ© (LlmProviderCapabilities.Vision, traduite une fois par OpenAICompatibleProviderBase) — les 16 providers la dĂ©clarent ; un provider sans la capacitĂ© dĂ©grade les messages multi-modaux vers leur repli texte (LlmMessage.Content). Formats image supportĂ©s : png, jpeg, gif, webp. Les parts audio/fichier ne sont envoyĂ©es par aucun provider et lèvent une NotSupportedException explicite si elles atteignent un payload vision.

Hooks de kickoff — AddOrkeonKickoffHooks()

  • RĂ´le : exĂ©cution de callbacks BeforeKickoffHook / AfterKickoffHook autour du kickoff d'un crew, par ordre de Priority croissante, avec sĂ©mantique ContinueOnError (les exceptions des hooks tolĂ©rants sont loguĂ©es puis ignorĂ©es).
  • Activation :
    services.AddOrkeonKickoffHooks(); // runner seul
    services.AddBeforeKickoffHook(new BeforeKickoffHook
    {
        Name = "audit",
        Priority = 1,
        Execute = crew => /* ... */ System.Threading.Tasks.Task.CompletedTask,
    }); // enregistre le hook ET le runner
    
  • DĂ©pendances : aucune (collections de hooks vides par dĂ©faut, logging optionnel).
  • Limites connues : l'orchestrateur n'invoque pas le runner : l'hĂ´te l'appelle lui-mĂŞme :
    var runner = provider.GetRequiredService<ICrewKickoffHookRunner>();
    await runner.RunBeforeKickoffAsync(crew, ct);
    var result = await orchestrator.KickoffAsync(crew.Id, input, ct);
    await runner.RunAfterKickoffAsync(crew, result, ct);
    

Contexte de codebase (RaggableTree) — AddRaggableTree(options)

  • RĂ´le : ICodebaseContextProvider produit des rĂ©sumĂ©s de codebase destinĂ©s Ă  ĂŞtre injectĂ©s dans le contexte des agents (fonctionnalitĂ© RaggableTree).
  • Activation : enregistrĂ© par AddRaggableTree(options) (projet Orkeon.Analysis). La bibliothèque cĹ“ur ne l'appelle jamais — mais le runner host, lui, l'appelle par dĂ©faut (orkeon run/orkeon-host ; opt-out via "RaggableTree:Enabled": false), en cohĂ©rence avec l'entrĂ©e de ce catalogue plus haut. Voir raggable-tree.md.
  • Limites connues : aucun composant du framework ne le consomme automatiquement — l'hĂ´te le rĂ©sout et injecte les rĂ©sumĂ©s lĂ  oĂą il le souhaite (prompt système, contexte de tâche…).

Sous-système RAG — AddOrkeonRag(configuration)

  • RĂ´le : gĂ©nĂ©ration augmentĂ©e par rĂ©cupĂ©ration — ingestion (loaders, chunking, validation, manifeste incrĂ©mental), pipeline de rĂ©cupĂ©ration Ă  Ă©tages (transform → retrieve → fuse (+ MMR opt-in) → rerank → assemble → generate → groundedness), graphe correctif CRAG, presets de profils et harnais d'Ă©valuation hors ligne. Guide complet : rag-pipeline.md, dĂ©cisions : ADR-006.
  • Activation :
    services.AddOrkeonRag(configuration);   // Orkeon.Rag.DependencyInjection
    services.AddOrkeonRagTools();           // Orkeon.Tools.Rag : rag_search / rag_ingest / rag_eval
    services.AddOrkeonOnnxReranker();       // opt-in — requis par balanced/quality/adaptive
    
    Tout hôte runner bâti sur RunnerHost (orkeon run, orkeon-host) fait lui-même les deux premiers appels, le REPL orkeon-repl aussi ; les trois binaires livrés — orkeon, orkeon-host, orkeon-repl — ajoutent le troisième (RunnerHost non : le paquet Orkeon.Hosting reste sans ONNX). AddOrkeonRag câble déjà les transformers de requête, le routage, l'hybride BM25+RRF, le graphe correctif et l'enregistrement du transport du repli web — appeler soi-même AddOrkeonRagWebFallback(configuration) est un no-op ; la fonctionnalité est gouvernée par les deux interrupteurs de configuration ci-dessous.
  • Profils (Orkeon:Rag:Profile, dĂ©faut fast ; les surcharges clĂ© par clĂ© s'appliquent par-dessus le preset) : fast (vectoriel seul) et corrective (graphe CRAG — boucle au lieu d'un Ă©tage de rerank linĂ©aire) fonctionnent sans les paquets ONNX ; balanced/quality activent l'Ă©tage de rerank cross-encoder et adaptive dĂ©lègue sa route SingleShot Ă  balanced, donc ces trois-lĂ  Ă©chouent explicitement Ă  la première requĂŞte (exception actionnable) tant qu'AddOrkeonOnnxReranker() (Orkeon.Rag.Onnx + Orkeon.Rag.Onnx.Model, poids int8 embarquĂ©s, hors-ligne) n'est pas enregistrĂ©.
  • Repli web (double opt-in, dĂ©sactivĂ© par dĂ©faut) : le nĹ“ud web_fallback du graphe correctif ne s'exĂ©cute que quand les deux Orkeon:Rag:Corrective:WebFallback:Enabled (politique) et Orkeon:Rag:WebFallback:Enabled + un Endpoint non vide (transport, SearxNG) sont posĂ©s. Chaque page tĂ©lĂ©chargĂ©e est filtrĂ©e par PromptInjectionDocumentValidator (Rejected n'entre jamais dans le working set ; Suspicious suit la politique configurĂ©e) — voir security.md.
  • Projets : Orkeon.Rag.Abstractions (contrats, dĂ©pendance Domain seule), Orkeon.Rag (implĂ©mentations), Orkeon.Tools.Rag (outils agents), Orkeon.Rag.Onnx + Orkeon.Rag.Onnx.Model (reranker opt-in + poids).
  • Limites connues : voir limitations.md — dĂ©gradation hors ligne des nĹ“uds dĂ©pendant d'un LLM (corrective/adaptive), classifieur heuristique par dĂ©faut, BM25 in-process non persistĂ©.

Persistance d'état d'exécution — AddCrewExecutionStatePersistence(...)

  • Binaires livrĂ©s : orkeon run et orkeon-host lisent Orkeon:Checkpointing (le magasin) et Orkeon:ExecutionState:Persistence (l'interrupteur). Orkeon:Checkpointing:Enabled=true avec Store json, sqlite ou postgres donne Ă  chaque run de l'hĂ´te une session de checkpoint durable, et Ă  la persistance des Ă©tats d'exĂ©cution le mĂŞme magasin. json et sqlite Ă©crivent sous ./.orkeon/state, montĂ© en /state comme montage interne. orkeon-repl ne lit ni l'une ni l'autre ; son dĂ©marrage ne les signale pas, puisque les deux autres binaires les lisent.
  • IdentitĂ© d'un run : un run a un seul identifiant, un ExecutionId : l'id de la session de checkpoint, le correlationId des Ă©vĂ©nements que orkeon run --events Ă©crit, et l'id que rend le kickoff sans attente. KickoffOptions.ExecutionId le transmet (reprise, hĂ´te) ; IRunScope.Current le montre Ă  chaque dĂ©corateur et observateur que le run atteint. La clĂ© de crew d'une session (SessionState.CrewKey) est le nom de la crew sauf si KickoffOptions.CrewKey la nomme ; orkeon run et orkeon-host la nomment avec le nom de la crew, le chemin virtuel de son fichier et une empreinte du chemin complet du fichier, pour qu'un nouveau processus retrouve une session quels que soient les ids de la crew et de ses tâches, rĂ©gĂ©nĂ©rĂ©s Ă  chaque chargement. L'id de tâche A2A et celui de l'API n'y sont pas unifiĂ©s. Un run lancĂ© dans un autre entre dans son propre scope : son identifiant remplace celui du run extĂ©rieur pendant sa durĂ©e.
  • Checkpoint par tâche et --resume : chaque tâche qu'un run de crew termine est Ă©crite dans la session de checkpoint Ă  sa fin, par un dĂ©corateur d'IAgentExecutionService que tous les modes d'orchestration traversent (sequential, parallel, hierarchical, graph, autonomous, consensual), sous la clĂ© "{TaskKey}#{n}" : TaskKey est le nom de la tâche dans la dĂ©finition de la crew, n l'ordinal de l'invocation de cette clĂ© dans le run (une rĂ©vision Hierarchical est #2 ; les tentatives du retry: d'une tâche partagent une clĂ©). Une tâche qui Ă©choue ou lève n'est pas checkpointĂ©e, et une tâche rĂ©essayĂ©e l'est une fois, pour la tentative rĂ©ussie (RetryCount note les retries) : un run arrĂŞtĂ© entre deux tentatives reprend cette tâche Ă  la tentative 1 ; un checkpoint impossible Ă  Ă©crire fait Ă©chouer la tâche. orkeon run <crew> --resume <id>|latest continue le run <id> (l'id qu'imprime un run Ă©chouĂ© : Run <id> did not complete. Resume it ...), ou le dernier run de ce fichier de crew qui n'est pas terminĂ© (et pas encore marquĂ© Running : latest ne reprend pas un run qui peut ĂŞtre vivant dans un autre processus, le magasin ne tient aucun bail ; nommer son id pour le reprendre) : le run garde son id, les tâches qu'il avait terminĂ©es reviennent du checkpoint (task.completed porte resumed: true, aucun modèle n'est interrogĂ© ; une tâche qui s'Ă©tait terminĂ©e sur son plafond d'itĂ©rations revient avec endedOnIterationCap: true, une tâche typĂ©e aussi, en TaskResult<TOutput>.EndedOnIterationCap, et celle qui s'Ă©tait terminĂ©e sans son livrable tool_call revient avec deliverableMissing: true, false depuis un checkpoint Ă©crit avant le drapeau ; le chemin du livrable revient aussi, rĂ©sultats typĂ©s compris, un livrable tool_call dont le fichier a disparu Ă  la reprise revient manquant, un livrable final_message ou structured_output perd seulement son chemin, et une tâche qui avait Ă©tĂ© rĂ©essayĂ©e rapporte attempt = ses retries + 1), les autres s'exĂ©cutent. Avec sa sortie, un checkpoint garde une empreinte de la tâche (description, sortie attendue, agent, dĂ©pendances) : une tâche modifiĂ©e depuis est rejouĂ©e avec chaque tâche qui la suit, et un avertissement la nomme. Il demande Orkeon:Checkpointing:Enabled=true et est refusĂ© avec --validate, avec --list-tools, sur un .ork.ts procĂ©dural et, avec --events, sans id de run explicite. Dans un hĂ´te Ă©crit en C#, passer KickoffOptions.Resume ("latest" ou l'id). Les noms de tâche sont uniques dans une crew.
  • RĂ´le : persistance durable des Ă©tats d'exĂ©cution de crew (ScopedCrewExecutionStateManager) dans un state store de checkpointing (IStateStore) : chaque transition (crĂ©ation, mise Ă  jour, complĂ©tion, archivage) est persistĂ©e, et au redĂ©marrage les Ă©tats sont rechargĂ©s — y compris la reprise via CreateStateAsync(crewId, executionId, input) quand un Ă©tat persistĂ© existe dĂ©jĂ  pour l'identifiant de reprise (crash recovery).
  • Activation (deux conditions — un store et l'option) :
    // 1. Un state store de checkpointing (in-memory, SQLite ou PostgreSQL)
    services.AddOrkeonSqliteCheckpointing("Data Source=/output/orkeon-state.db"); // chemin virtuel, montage en écriture
    // ou : services.AddOrkeonCheckpointing();              // in-memory
    // ou : services.AddOrkeonCheckpointing(configuration); // Orkeon:Checkpointing : Enabled, Store memory|json|sqlite|postgres
    // ou : services.AddOrkeonPostgresCheckpointing(configuration); // Orkeon:Checkpointing:*
    
    // 2. L'opt-in de persistance
    services.AddCrewExecutionStatePersistence();             // code-first
    services.AddCrewExecutionStatePersistence(configuration); // lie Orkeon:ExecutionState:Persistence
    
    Le store SQLite résout sa Data Source via le VFS comme le provider mémoire SQLite : il lui faut un IFileSystemService enregistré (AddOrkeonFileSystem(...)) et un chemin sur un montage accessible en écriture, sinon il lève FileAccessDeniedException. Avec la surcharge AddOrkeonInfrastructure(IConfiguration), la présence de la section Orkeon:ExecutionState:Persistence (Enabled, DeleteFromStoreOnArchive) suffit à lier les options.
  • DĂ©faut : sans activation, les Ă©tats restent in-memory only (aucune reprise après crash). Si l'option est activĂ©e sans store enregistrĂ©, le manager logue un avertissement et continue en mĂ©moire.
  • Cohabitation : les sessions d'Ă©tat d'exĂ©cution sont espacĂ©es de noms (prĂ©fixe crew-exec: sur l'id de session et l'id de crew) et ne polluent jamais les sessions de checkpointing de tâches (CheckpointManager/ResumeEngine) partageant le mĂŞme store.
  • Limites connues : les mĂ©tadonnĂ©es d'exĂ©cution sont persistĂ©es en chaĂ®nes invariantes (les lectures primitives restent converties via GetValue<T>) ; la tĂ©lĂ©mĂ©trie ToolsUsed des sorties de tâches n'est pas persistĂ©e (v1).

Barrière de permissions — AddOrkeonPermissionGate(configuration)

  • Activation : appelĂ©e par RunnerHost et le bootstrap de la ConsoleApp, mais n'enregistre rien tant que Orkeon:Security:PermissionGate:Enabled = true n'est pas posĂ©. Quand l'hĂ´te enregistre un IToolApprovalChannel (orkeon-repl le fait), la barrière lui soumet chaque demande et rend une autorisation ou un refus. Sans canal, Interactive (dĂ©faut false) dĂ©clare un appelant qui tranche lui-mĂŞme les demandes ; laissĂ© Ă  false, une demande vaut refus.
  • Effet : ModePermissionGate est consultĂ© par la boucle scriptĂ©e ctx.llm.act et par les appels d'outils des crews YAML (ToolInvocationPipeline) avant CHAQUE exĂ©cution d'outil. Modes : bypassPermissions → tout autoriser ; plan → refuser tout ce qui n'est pas une lecture ; dontAsk → autoriser les lectures, refuser le reste sans jamais demander ; acceptEdits → accepter d'office les lectures et les Ă©ditions (file_write, spawn_agent, les Ă©ditions du graphe de code, tout outil qui dĂ©clare ToolAccess.Edit comme rag_ingest), demander pour tout le reste (dont shell_command) ; default → accepter les lectures, demander pour tout le reste. Avec un canal d'approbation, une demande attend l'opĂ©rateur, et l'ExecutionTimeout du script comme le budget de temps mural de l'agent (.budget({ wallTime })) s'arrĂŞtent pendant ce temps ; un refus se lit DENIED: … The operator denied the call. En headless, chaque demande dĂ©grade en un DENIED: motivĂ© renvoyĂ© au modèle comme rĂ©sultat d'outil (pas d'exception). Les outils inconnus sont classĂ©s comme Ă©critures (fail-closed). Les règles de permission de la session (posĂ©es depuis un script par ctx.services.get("permissions"), voir la rĂ©fĂ©rence du CLI) sont vĂ©rifiĂ©es avant le mode : une règle de refus refuse dans tous les modes, une règle d'autorisation admet l'appel dans tous les modes sauf plan.
  • Classification dĂ©clarative : les outils peuvent auto-dĂ©clarer leur classe via IBaseTool.Access (ToolAccess.Read / Edit / Execute) — une dĂ©claration l'emporte sur les tables de noms de la barrière ; Unspecified (le dĂ©faut) se replie sur les tables. Un outil dont la classe dĂ©pend de l'opĂ©ration demandĂ©e surcharge IBaseTool.AccessFor(arguments) (dĂ©faut : Access), que la barrière lit Ă  chaque appel : github est Read pour list_issues, get_pr, search_repos et get_repo, Execute pour create_issue, create_pr et toute action inconnue ou absente ; http_api est Read pour GET, HEAD et OPTIONS (une mĂ©thode absente est son dĂ©faut GET) sans corps ni en-tĂŞte de substitution de mĂ©thode (X-HTTP-Method-Override, X-HTTP-Method, X-Method-Override, quelle que soit la casse), Execute pour toute autre mĂ©thode ou pour une mĂ©thode de lecture qui porte l'un ou l'autre. Leur Access statique reste Execute, la classe la plus restrictive qu'ils puissent prendre. Les outils de lecture intĂ©grĂ©s (file/directory/session/memory/analysis, web_scrape, scrape_element, rag_search, web_search), file_write, rag_ingest (Edit : il Ă©crit dans l'index de connaissances, jamais dans l'espace de travail) et rag_eval (Edit : il ingère le corpus du jeu de donnĂ©es dans la collection — reindex la reconstruit — et Ă©crit ses rapports par le VFS) et shell_command (Execute) se dĂ©clarent tous. Un outil MCP ne prend sa classe des annotations du serveur que si l'opĂ©rateur fait confiance Ă  ce serveur (MCP:Servers:<name>:TrustAnnotations = true : readOnlyHint: true → Read, d'autres annotations → Execute) ; les outils d'un serveur non fiable — le dĂ©faut — et d'un serveur qui n'envoie aucune annotation restent Unspecified, quoi que disent leurs indications. BuiltInToolAccessTests liste les outils intĂ©grĂ©s encore laissĂ©s Ă  Unspecified.
  • DĂ©faut : flag absent → aucune barrière enregistrĂ©e → act exĂ©cute ses appels d'outils sans contrĂ´le. Les scripts optent pour un mode Ă  l'appel via l'option d'act permissionMode. Un script lit si une barrière contrĂ´le ses appels avec ctx.llm.permissionGate.enabled ; un permissionMode passĂ© Ă  act sur un hĂ´te sans barrière journalise un avertissement (event id 2 de JsLlmFacade) au lieu d'ĂŞtre ignorĂ© en silence.

Shell : interpréteurs & git mutant — Orkeon:Tools:Shell:AllowInterpreters

  • Activation : config seule — AddOrkeonCodeTools() lit le flag et, quand il vaut true, construit ShellCommandTool avec allowInterpreters: true (rĂ©active node/dotnet/npm/find ET lève la restriction git lecture-seule, si bien que git add/commit/branch fonctionnent). L'outil journalise une ligne SECURITY par hĂ´te, au premier appel de shell_command, qui Ă©nonce le confinement en vigueur (le backend, ou none/unavailable avec sa raison, rĂ©seau on/off).
  • SĂ©curitĂ© : Ă©quivalent RCE sur l'hĂ´te — Ă  rĂ©server aux hĂ´tes coding-agent de confiance qui tournent dans un espace de travail confinĂ© (le REPL scripted-commands est le consommateur de rĂ©fĂ©rence — voir examples/cli-ts-commands/ ; une commande de commit ne peut pas marcher sans).
  • DĂ©faut : flag absent → allowlist stricte lecture-seule, comme sans l'option.
  • Allowlist personnalisĂ©e (deux clĂ©s tableau de chaĂ®nes, toutes deux lues par AddOrkeonCodeTools()) :
    • Orkeon:Tools:Shell:ExtraAllowedCommands — additive sur l'allowlist par dĂ©faut (ou sur une liste de remplacement) ; la voie recommandĂ©e pour autoriser make/cargo/etc. sur un hĂ´te de confiance. Compose avec AllowInterpreters.
    • Orkeon:Tools:Shell:AllowedCommands — remplacement intĂ©gral verbatim ; par contrat du ctor de ShellCommandTool, il annule AllowInterpreters et rĂ©active la restriction git lecture-seule.
    • Une section absente ou vide se lie Ă  null (dĂ©fauts) — jamais Ă  un tableau vide, qui bloquerait toute commande.
  • Réécriture de chemins VFS (toujours active, sans flag ; sous bubblewrap, le processus voit les chemins virtuels et rien n'est réécrit) : les arguments qui nomment un chemin virtuel prĂ©fixĂ© par un montage (y compris --out=/workspace/dist) sont rĂ©solus virtuel→physique avant le dĂ©marrage du processus — un chemin refusĂ© fait Ă©chouer l'appel avec la raison expurgĂ©e — et stdout/stderr sont réécrits physique→virtuel : le modèle ne voit jamais que des chemins virtuels. Montages AgentFacing, correspondance ordinale ; sans montage, les deux passes sont sans effet.
  • Le confinement n'est pas sur option (Orkeon:Tools:Shell:Confinement) : le processus tourne confinĂ© par dĂ©faut (Mode = Auto : bubblewrap sous Linux, Seatbelt sous macOS, un AppContainer sous Windows, coupĂ© dans un conteneur), et AllowInterpreters laisse passer plus de commandes, pas une vue plus large. Mode = None est la sortie — voir Confinement du shell.

Streaming console LLM natif — AddLlmConsoleStreaming(configuration, enabledByDefault)

  • Activation : appelĂ©e par le bootstrap de la ConsoleApp, qui l'active sauf Orkeon:Cli:ConsoleStreaming:Enabled = false ; enabledByDefault (false) est ce que veut dire une clĂ© absente, si bien qu'un hĂ´te de crew le laisse dĂ©sactivĂ© sauf clĂ© Ă  true.
  • Effet : enregistre ConsoleLlmDeltaSink comme ILlmDeltaSink. Quand un sink est prĂ©sent et que le provider LLM streame (IStreamingLlmProvider), la boucle scriptĂ©e ctx.llm.act bascule sur le chemin SSE et chaque delta de contenu atteint l'IConsoleAdapter de l'hĂ´te au fil de son arrivĂ©e — le REPL rend les tokens de l'act de premier plan Ă  mesure sans que le script passe onDelta. Tout autre tour (ILlmDeltaSink.BeginTurn) — un second act qui streame en mĂŞme temps, un act sous une instance de commande en arrière-plan, une tâche de crew — tient son propre tampon de ligne et Ă©crit une ligne entière Ă  la fois, prĂ©fixĂ©e du ticket de l'instance ([t2] ), comme les lignes de complĂ©tion, une tâche de crew ajoutant son id ([t2 task-1] ) — le prĂ©fixe reste en mode simple, alors que la console Ă  volets abandonne le prĂ©fixe, montre la ligne sur l'Ă©cran de la tâche et garde l'Ă©tiquette de crew ([task-1] ) ; une de leurs lignes qui arrive pendant que l'act de premier plan est au milieu d'une ligne attend la fin de celle-ci. Ainsi deux acts qui streament en mĂŞme temps — deux sous-exĂ©cutions runAgent en arrière-plan, les tâches d'une vague parallèle de crew — ne s'Ă©crivent jamais l'un dans l'autre et aucune ligne n'est coupĂ©e. Les tours qui ne streament aucun contenu visible (appels d'outils purs) n'Ă©mettent rien. Le sink compose avec un onDelta cĂ´tĂ© script (les deux reçoivent chaque delta).
  • Dire au script que la rĂ©ponse a dĂ©jĂ  Ă©tĂ© streamĂ©e : la CommandResponse que retourne un request() ou que reçoit un completed(result), et la CrewRunOutput de runCrew, portent streamed: boolean, vrai quand un tour quelconque de la requĂŞte a Ă©tĂ© Ă©crit sur la console au premier plan (en ligne, ou en lignes entières sans prĂ©fixe) ; un script n'imprime le payload que quand streamed est faux, et la rĂ©ponse s'affiche une fois. Une instance en arrière-plan (post, runCrewAsync) et une tâche de crew Ă©crivent des lignes entières prĂ©fixĂ©es et rapportent faux. Le dispatch ouvre un reçu par requĂŞte d'agent et par exĂ©cution de crew dans le flux asynchrone de ce travail ; les tours du sink y enregistrent, il ne repasse jamais Ă  faux au sein d'une requĂŞte, et des commandes qui tournent en mĂŞme temps lisent chacune le leur.
  • DĂ©faut : flag absent → aucun sink enregistrĂ© → act conserve son rendu bufferisĂ© (identique Ă  l'octet près), les scripts peuvent toujours streamer via onDelta.

Garanties de non-régression

Les tests d'enregistrement (tests/core/Orkeon.Infrastructure.Tests/DependencyInjection/OptInSubsystemsRegistrationTests.cs et tests/core/Orkeon.Application.Tests/DependencyInjection/KickoffHookExtensionsTests.cs) vérifient :

  1. qu'aucun port dormant du jeu opt-in d'origine n'est enregistré par AddOrkeonApplication() / AddOrkeonInfrastructure() (les deux surcharges) — les lignes ajoutées ensuite (plugins, embeddings locaux, providers de mémoire, mémoire cognitive, les enregistrements d'outils et de journalisation…) sont gardées par leurs propres suites, pas par ce test ;
  2. que chaque AddOrkeonXxx() produit un graphe résolvable seul (avec logging et, le cas échéant, une IConfiguration) ;
  3. que les opt-ins composent avec le socle (sémantique TryAdd, pas de doublons).

Historique de run : Orkeon:RunHistory

  • Binaires livrĂ©s : orkeon run, orkeon-host et orkeon runs lisent Orkeon:RunHistory. Il est Ă©teint dans la bibliothèque et dans orkeon run, allumĂ© dans orkeon-host et dans les rĂ©glages qu'Ă©crit orkeon init. Enabled=true garde les Ă©vĂ©nements de chaque run après sa fin, avec Store jsonl (dĂ©faut) ou sqlite, sous ./.orkeon/runs montĂ© en /runs comme montage interne ; orkeon runs list|show|tail les relit. Un run est enregistrĂ© avec ou sans --events (sans, rien n'est Ă©crit sur stdout). orkeon-repl ne publie pas d'Ă©vĂ©nements de run. Ce qui est gardĂ©, et masquĂ©, est dans orkeon runs ; le gabarit de orkeon init active l'historique et ajoute .orkeon/ au .gitignore du dossier courant.
  • Un hĂ´te Ă©crit en C# obtient l'historique par RunnerHost (Orkeon:RunHistory:Enabled, ou RunHistoryByDefault de son RunnerMountPlan), ou Ă©crit dans le SqliteRunEventSink public (expĂ©rimental ORKEXP007, voir les API expĂ©rimentales) et relit par IRunHistoryReader ; RunEventPublisher et JsonLinesFileRunEventSink sont internes.