🇬🇧 English version
Sous-systèmes opt-in
Les sous-systèmes ci-dessous ne sont pas enregistrés par défaut :
AddOrkeonApplication()etAddOrkeonInfrastructure()(les deux surcharges) les laissent de côté sauf mention contraire d'une ligne, et chacun s'active par son extension dédiéeAddOrkeonXxx().
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 (sectionMCP, via la surchargeIConfiguration, ou l'hôte des runners dès queMCP:Serversdé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:Enableden 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 uniqueAddOrkeonWebSearchTool,AddOrkeonBraveSearchTool,AddOrkeonCacheSearchTool,AddOrkeonSlackTool,AddOrkeonSlackReadTool),AddOrkeonDataTools(plusAddRelationalDatabaseTools,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'IStateStorede checkpointing opt-in (à enregistrer d'abord), transformantGET /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) exposantPOST /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);IA2AServern'est enregistré que siEnableServerest 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ésoutIA2AServerni n'appelleStartAsync. 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 leskillIdde la requête (l'idque publie la carte) viaIAgentExecutionService; l'hôte appelle donc aussiAddOrkeonApplication()— sans lui, une tâche répondFailedet le dit. Un hôte qui route autrement enregistre d'abord son propreIA2ATaskRouter: 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 (IAgentRegistrationStoresingleton +IAgentRepositoryscoped, voir ci-dessous) lorsque l'hôte ne les a pas déjà câblés viaAddOrkeonInfrastructure(). - Cycle de vie du dépôt d'agents (scoped par requête) :
IAgentRepositoryest scoped ; le routeur (un singleton) ne le capture jamais — il ouvre un scope DI par requête A2A (la carte, chaque tâche) viaIServiceScopeFactoryet résout le dépôt dedans. La résolution passe avecValidateScopes = 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 leInMemoryAgentRepositoryà store par scope),AddOrkeonA2A(...)surclasse cette implémentation par défaut versSharedStoreAgentRepository(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. AppelerAddOrkeonA2A(...)aprèsAddOrkeonInfrastructure()et après un éventuel dépôt custom (ordre recommandé, cf. Principe) ; un dépôt custom enregistré aprèsAddOrkeonA2A(...)gagne (dernier enregistrement).
- Binaires livrés :
orkeon-hostappelleAddOrkeonA2AquandOrkeon:Host:A2A:Enabledest 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 runet 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
IAgentRepositorycustom 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-hostetorkeon-replne lisent pasOrkeon:Monitoring, et le disent à leur démarrage quand les réglages l'écrivent. - Rôle : agrégation in-process des métriques Orkeon (
MeterListenersur le meterOrkeon) 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 surchargeAddOrkeonInfrastructure(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, optionsSecurity:Audit) est utilisée. - Limites connues : le rapport lit la piste qu'écrivent les tours d'agent — un
événement
ToolExecutionpar appel d'outil et unSecurityEventpar 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-hostetorkeon-replne lisent pasOrkeon: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 parSecurity:PromptetSecurity:ToolResults. - Rôle : prévention de fuite de données — détection de PII par expressions
régulières (
IPiiDetector), politiques par canal (IDlpPolicyProvider, sectionOrkeon:Dlp) et 5 intercepteurs de canaux (sortie d'outil, délégation, logs, mémoire, sortie externe). - Activation :
services.AddOrkeonDlp(); - Dépendances : logging +
IConfiguration(liaisonOrkeon: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 lePiiDetectionValidatordu 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-hostetorkeon-replne lisent niToolRateLimitingniTokenBudget, 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, sectionToolRateLimiting) et suivi de budget de tokens par agent/crew (ITokenBudgetTracker, sectionTokenBudget). - Activation :
services.AddOrkeonToolRateLimiting(); - Dépendances : logging +
IConfiguration. SiAddOrkeonCostTracking()(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 dansLlm:Provider—deepseek,zai,kimi,qwen,gemini,mistral,grok,minimax,together,mammouth,ollamapour les fournisseurs qui ont leurs propres lignes intégrées ; la casse est ignorée. Le registre choisit alors la ligne comme pourOrkeon:CostTracking: une ligneCustomPricingsl'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 ligneCustomPricingsle 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é viaProvisionNewKeyAsync(secretStore, secretName, keySizeInBits)(IWritableSecretProvider, implémenté parDpapiSecretProvider). - 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
RotateAsyncavec 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.ContinueOnUnreadableEntriespermet de l'ignorer (entrée laissée telle quelle et signalée dansKeyRotationResult.Errors).
- Activation :
services.AddOrkeonKeyRotation();— à coupler avecAddOrkeonEncryption()(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, typeMemoryProviderBasepour l'énumération des clés) et suppose qu'aucune écriture concurrente n'a lieu pendant la fenêtre de rotation.AesEncryptionProvider.RotateKeyAsyncest neutralisé (NotSupportedException) : une rotation « sur place » orphelinerait les données existantes — passer parIKeyRotationService.
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 avecAddOrkeonEvaluation()(inclus dans le socle) pour construire les suites. L'IEvaluationSuitepar défaut porte les juges LLM quandEvaluation:EnableLlmJudgevauttrue— lié parAddOrkeonInfrastructure(configuration). - Binaires livrés : les hôtes runner (
orkeon,orkeon-host) l'enregistrent et lient la sectionEvaluationavecAddOrkeonEvaluation(configuration);orkeon eval benchl'exécute (orkeon eval runnote 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-hostetorkeon-replne lisent pasOrkeon: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 viaLlmMessage.MultiModalContent.AnthropicLlmProviderémet des blocs de contenu image conformes à l'API Messages ({"type":"image","source":{"type":"base64"|"url",…}}) ;OpenAILlmProviderémet des partsimage_urlconformes à 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(optionsOrkeon:MultiModal) et chargement d'images depuis le système de fichiers virtuel viaIMultiModalContentLoader(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 :
IContentValidationServicen'a besoin que des options ;IMultiModalContentLoaderrequiert unIFileSystemServiceré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 parOpenAICompatibleProviderBase) — 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 uneNotSupportedExceptionexplicite si elles atteignent un payload vision.
Hooks de kickoff — AddOrkeonKickoffHooks()
- Rôle : exécution de callbacks
BeforeKickoffHook/AfterKickoffHookautour du kickoff d'un crew, par ordre dePrioritycroissante, avec sémantiqueContinueOnError(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 :
ICodebaseContextProviderproduit des résumés de codebase destinés à être injectés dans le contexte des agents (fonctionnalité RaggableTree). - Activation : enregistré par
AddRaggableTree(options)(projetOrkeon.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 :
Tout hôte runner bâti surservices.AddOrkeonRag(configuration); // Orkeon.Rag.DependencyInjection services.AddOrkeonRagTools(); // Orkeon.Tools.Rag : rag_search / rag_ingest / rag_eval services.AddOrkeonOnnxReranker(); // opt-in — requis par balanced/quality/adaptiveRunnerHost(orkeon run,orkeon-host) fait lui-même les deux premiers appels, le REPLorkeon-replaussi ; les trois binaires livrés —orkeon,orkeon-host,orkeon-repl— ajoutent le troisième (RunnerHostnon : le paquetOrkeon.Hostingreste sans ONNX).AddOrkeonRagcâ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êmeAddOrkeonRagWebFallback(configuration)est un no-op ; la fonctionnalité est gouvernée par les deux interrupteurs de configuration ci-dessous. - Profils (
Orkeon:Rag:Profile, dĂ©fautfast; les surcharges clĂ© par clĂ© s'appliquent par-dessus le preset) :fast(vectoriel seul) etcorrective(graphe CRAG — boucle au lieu d'un Ă©tage de rerank linĂ©aire) fonctionnent sans les paquets ONNX ;balanced/qualityactivent l'Ă©tage de rerank cross-encoder etadaptivedĂ©lègue sa routeSingleShotĂ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_fallbackdu graphe correctif ne s'exécute que quand les deuxOrkeon:Rag:Corrective:WebFallback:Enabled(politique) etOrkeon:Rag:WebFallback:Enabled+ unEndpointnon vide (transport, SearxNG) sont posés. Chaque page téléchargée est filtrée parPromptInjectionDocumentValidator(Rejectedn'entre jamais dans le working set ;Suspicioussuit 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 runetorkeon-hostlisentOrkeon:Checkpointing(le magasin) etOrkeon:ExecutionState:Persistence(l'interrupteur).Orkeon:Checkpointing:Enabled=trueavecStorejson,sqliteoupostgresdonne à chaque run de l'hôte une session de checkpoint durable, et à la persistance des états d'exécution le même magasin.jsonetsqliteécrivent sous./.orkeon/state, monté en/statecomme montage interne.orkeon-replne 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, lecorrelationIddes événements queorkeon run --eventsécrit, et l'id que rend le kickoff sans attente.KickoffOptions.ExecutionIdle transmet (reprise, hôte) ;IRunScope.Currentle 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 siKickoffOptions.CrewKeyla nomme ;orkeon runetorkeon-hostla 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'IAgentExecutionServiceque tous les modes d'orchestration traversent (sequential, parallel, hierarchical, graph, autonomous, consensual), sous la clé"{TaskKey}#{n}":TaskKeyest le nom de la tâche dans la définition de la crew,nl'ordinal de l'invocation de cette clé dans le run (une révision Hierarchical est#2; les tentatives duretry: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 (RetryCountnote 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>|latestcontinue 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:latestne 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.completedporteresumed: true, aucun modèle n'est interrogé ; une tâche qui s'était terminée sur son plafond d'itérations revient avecendedOnIterationCap: true, une tâche typée aussi, enTaskResult<TOutput>.EndedOnIterationCap, et celle qui s'était terminée sans son livrabletool_callrevient avecdeliverableMissing: true,falsedepuis un checkpoint écrit avant le drapeau ; le chemin du livrable revient aussi, résultats typés compris, un livrabletool_calldont le fichier a disparu à la reprise revient manquant, un livrablefinal_messageoustructured_outputperd seulement son chemin, et une tâche qui avait été réessayée rapporteattempt= 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 demandeOrkeon:Checkpointing:Enabled=trueet est refusé avec--validate, avec--list-tools, sur un.ork.tsprocédural et, avec--events, sans id de run explicite. Dans un hôte écrit en C#, passerKickoffOptions.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 viaCreateStateAsync(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) :
Le store SQLite résout sa// 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:PersistenceData Sourcevia le VFS comme le provider mémoire SQLite : il lui faut unIFileSystemServiceenregistré (AddOrkeonFileSystem(...)) et un chemin sur un montage accessible en écriture, sinon il lèveFileAccessDeniedException. Avec la surchargeAddOrkeonInfrastructure(IConfiguration), la présence de la sectionOrkeon: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étrieToolsUseddes sorties de tâches n'est pas persistée (v1).
Barrière de permissions — AddOrkeonPermissionGate(configuration)
- Activation : appelée par
RunnerHostet le bootstrap de la ConsoleApp, mais n'enregistre rien tant queOrkeon:Security:PermissionGate:Enabled = truen'est pas posĂ©. Quand l'hĂ´te enregistre unIToolApprovalChannel(orkeon-replle fait), la barrière lui soumet chaque demande et rend une autorisation ou un refus. Sans canal,Interactive(dĂ©fautfalse) dĂ©clare un appelant qui tranche lui-mĂŞme les demandes ; laissĂ© Ăfalse, une demande vaut refus. - Effet :
ModePermissionGateest consulté par la boucle scriptéectx.llm.actet 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éclareToolAccess.Editcommerag_ingest), demander pour tout le reste (dontshell_command) ;default→ accepter les lectures, demander pour tout le reste. Avec un canal d'approbation, une demande attend l'opérateur, et l'ExecutionTimeoutdu script comme le budget de temps mural de l'agent (.budget({ wallTime })) s'arrêtent pendant ce temps ; un refus se litDENIED: … The operator denied the call.En headless, chaque demande dégrade en unDENIED: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 parctx.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 saufplan. - 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 surchargeIBaseTool.AccessFor(arguments)(dĂ©faut :Access), que la barrière lit Ă chaque appel :githubestReadpourlist_issues,get_pr,search_reposetget_repo,Executepourcreate_issue,create_pret toute action inconnue ou absente ;http_apiestReadpourGET,HEADetOPTIONS(une mĂ©thode absente est son dĂ©fautGET) 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),Executepour toute autre mĂ©thode ou pour une mĂ©thode de lecture qui porte l'un ou l'autre. LeurAccessstatique resteExecute, 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) etrag_eval(Edit : il ingère le corpus du jeu de donnĂ©es dans la collection —reindexla reconstruit — et Ă©crit ses rapports par le VFS) etshell_command(Execute) se dĂ©clarent tous. Un outil MCP ne prend sa classe desannotationsdu 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 restentUnspecified, quoi que disent leurs indications.BuiltInToolAccessTestsliste les outils intĂ©grĂ©s encore laissĂ©s ĂUnspecified. - DĂ©faut : flag absent → aucune barrière enregistrĂ©e →
actexĂ©cute ses appels d'outils sans contrĂ´le. Les scripts optent pour un mode Ă l'appel via l'option d'actpermissionMode. Un script lit si une barrière contrĂ´le ses appels avecctx.llm.permissionGate.enabled; unpermissionModepassĂ© Ăactsur un hĂ´te sans barrière journalise un avertissement (event id2deJsLlmFacade) 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 vauttrue, construitShellCommandToolavecallowInterpreters: true(réactivenode/dotnet/npm/findET lève la restriction git lecture-seule, si bien quegit add/commit/branchfonctionnent). L'outil journalise une ligneSECURITYpar hôte, au premier appel deshell_command, qui énonce le confinement en vigueur (le backend, ounone/unavailableavec 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 autorisermake/cargo/etc. sur un hĂ´te de confiance. Compose avecAllowInterpreters.Orkeon:Tools:Shell:AllowedCommands— remplacement intĂ©gral verbatim ; par contrat du ctor deShellCommandTool, il annuleAllowInterpreterset 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. MontagesAgentFacing, 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), etAllowInterpreterslaisse passer plus de commandes, pas une vue plus large.Mode = Noneest 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
ConsoleLlmDeltaSinkcommeILlmDeltaSink. Quand un sink est présent et que le provider LLM streame (IStreamingLlmProvider), la boucle scriptéectx.llm.actbascule sur le chemin SSE et chaque delta de contenu atteint l'IConsoleAdapterde 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 passeonDelta. 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écutionsrunAgenten 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 unonDeltacôté script (les deux reçoivent chaque delta). - Dire au script que la réponse a déjà été streamée : la
CommandResponseque retourne unrequest()ou que reçoit uncompleted(result), et laCrewRunOutputderunCrew, portentstreamed: 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 quandstreamedest 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é →
actconserve son rendu bufferisé (identique à l'octet près), les scripts peuvent toujours streamer viaonDelta.
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 :
- 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 ; - que chaque
AddOrkeonXxx()produit un graphe résolvable seul (avec logging et, le cas échéant, uneIConfiguration) ; - 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-hostetorkeon runslisentOrkeon:RunHistory. Il est éteint dans la bibliothèque et dansorkeon run, allumé dansorkeon-hostet dans les réglages qu'écritorkeon init.Enabled=truegarde les événements de chaque run après sa fin, avecStorejsonl(défaut) ousqlite, sous./.orkeon/runsmonté en/runscomme montage interne ;orkeon runs list|show|tailles relit. Un run est enregistré avec ou sans--events(sans, rien n'est écrit sur stdout).orkeon-replne publie pas d'événements de run. Ce qui est gardé, et masqué, est dansorkeon runs; le gabarit deorkeon initactive l'historique et ajoute.orkeon/au.gitignoredu dossier courant. - Un hôte écrit en C# obtient l'historique par
RunnerHost(Orkeon:RunHistory:Enabled, ouRunHistoryByDefaultde sonRunnerMountPlan), ou écrit dans leSqliteRunEventSinkpublic (expérimentalORKEXP007, voir les API expérimentales) et relit parIRunHistoryReader;RunEventPublisheretJsonLinesFileRunEventSinksont internes.