Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

Opt-in subsystems

The subsystems below are not registered by default: AddOrkeonApplication() and AddOrkeonInfrastructure() (both overloads) leave them out unless a row says otherwise, and each one is enabled through its dedicated AddOrkeonXxx() extension.

Principle

Some of these subsystems are consumed by no production execution path β€” the host invokes the service itself (Preview below); others are wired by the shipped binaries, as the Activation column says. Registering all of them by default would bloat the DI container and mask their status: the opt-in makes their activation intentional, documented and verifiable.

Six sections no shipped binary reads. orkeon run, orkeon-host and orkeon-repl call none of the extensions that read ToolRateLimiting, TokenBudget, Orkeon:Dlp, Orkeon:Monitoring, Orkeon:MultiModal and Orkeon:VectorSearch. Written in the settings of one of those binaries, such a section is read by nothing: the run starts without the limit, the budget or the screening it describes. The binary says so at its start β€” one line on stderr per section, naming the extension a host written in C# reads it through β€” and orkeon doctor reports it as a warn line of runner-settings. It starts all the same: a settings file shared with a C# host is a legitimate one. See When a setting is refused.

Each activation extension is self-contained: it registers (via TryAdd*) all the dependencies the subsystem needs that are not already provided by the host. Prerequisites common to all of them: logging (services.AddLogging()) and, for the subsystems that bind configuration options, a registered IConfiguration (always present in an application based on Host/WebApplication).

The recommended order is to call the extension after AddOrkeonInfrastructure(): the TryAdd* calls then leave priority to the services already wired by the core.

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

// Explicit activations (examples)
services.AddOrkeonMonitoring(configuration);
services.AddOrkeonDlp();
services.AddOrkeonA2A(options => options.EnableServer = true);

Catalog

Subsystem Activation Project Exposed ports Maturity
A2A server/protocol AddOrkeonA2A(...) Infrastructure IA2AServer, IA2AClient, IA2AAgentDiscovery, IA2ATaskRouter Experimental (ORKEXP001)
Monitoring backend AddOrkeonMonitoring(...) Infrastructure IMetricsAggregation, ITraceExplorer Stable
NIST compliance AddOrkeonNistCompliance() Infrastructure INistComplianceReporter Preview
DLP (Data Loss Prevention) AddOrkeonDlp() Infrastructure IDlpPolicyProvider, IPiiDetector, IDlpInterceptor (Γ—5) Preview
Tool rate-limiting & token budget AddOrkeonToolRateLimiting() Infrastructure IToolRateLimiter, ITokenBudgetTracker Preview
Key rotation AddOrkeonKeyRotation() Infrastructure IKeyRotationService Stable
Evaluation benchmarking AddOrkeonBenchmarking() β€” runner hosts register it Infrastructure IBenchmarkRunner Stable
Multi-modal content (vision) AddOrkeonMultiModal(...) Infrastructure IContentValidationService, IMultiModalContentLoader Stable
Kickoff hooks AddOrkeonKickoffHooks() Application ICrewKickoffHookRunner Preview
Codebase context (RaggableTree) AddRaggableTree(options) β€” ⚠️ runner hosts opt out instead: RunnerHost registers it by default and RaggableTree:Enabled = false disables it Analysis ICodebaseContextProvider Stable
RAG subsystem AddOrkeonRag(config) (namespace Orkeon.Rag.DependencyInjection) + AddOrkeonRagTools() (Orkeon.Tools.Rag); profiles fast/balanced/quality/adaptive/corrective via Orkeon:Rag:Profile (default fast); balanced/quality/adaptive need the ONNX cross-encoder β€” AddOrkeonOnnxReranker() (Orkeon.Rag.Onnx + Orkeon.Rag.Onnx.Model, embedded weights, offline β€” registered by the three shipped binaries, orkeon, orkeon-host and the REPL, not by RunnerHost); corrective does not (the graph loops instead of reranking); the corrective web fallback is config-only β€” AddOrkeonRag already wires the transport, the two Enabled switches govern (Orkeon:Rag:Corrective:WebFallback policy, Orkeon:Rag:WebFallback transport) β€” see the detailed section below Orkeon.Rag.Abstractions / Orkeon.Rag / Orkeon.Tools.Rag / Orkeon.Rag.Onnx / Orkeon.Rag.Onnx.Model IRagPipeline (staged / corrective graph), IRagProfileResolver, IIngestionPipeline, IDocumentStore, IRagEvalHarness, rag_search/rag_ingest/rag_eval (IBaseTool) Stable
Decision models (TypeSafe, Liquid, Kev) AddOrkeonDecisionProvider(configuration) (the active provider, named by Orkeon:Decision:Provider or deduced from the sections Orkeon:TypeSafe / Orkeon:Liquid and the keys TYPESAFE_API_KEY / LIQUID_API_KEY; Kev is only ever named, its KEV_API_KEY is optional; also the model behind the guardian's LLM judge (Orkeon:Guardian:Llm, off by default), and system_one_decide) Β· AddOrkeonDecisionProfiles(configuration) (Orkeon:Decision:Profiles) β€” the three shipped binaries call both: the provider when one is named or deduced, the profiles always Β· rerank.kind: decision β€” see Decision models Infrastructure / Orkeon.Rag IDecisionModel (SystemOneDecisionModel, one client for the three providers), DecisionLlmProvider with the route/guard/verify stages, DecisionInputGuard, DecisionModelReranker, system_one_decide (IBaseTool) Preview
EventHub middleware stages AddOrkeonEventHubObservability() (logging + telemetry) Β· AddOrkeonEventHubAcl(policy?) (enforces the crews' links: blocks β€” already wired by the runner host and orkeon-host, with the permissive default: a crew that declares no links behaves as before, one that declares is held to them; only the closed policy is an opt-in) Β· AddOrkeonEventHubIdempotency(capacity?) (point-to-point only, in-memory, does not survive the process) Β· AddOrkeonEventHubValidation() (a declared SchemaId must be registered β€” the contract's existence, not the payload's conformance). Each is independent; registration order is the pipeline order β€” see EventHub Β§12 Infrastructure IEventHubMiddleware, ICrewLinkProvider/ICrewLinkRegistry, IEventSchemaRegistry Stable
Execution state persistence AddCrewExecutionStatePersistence(...) Infrastructure ICrewExecutionStateManager (durable via IStateStore) Stable
Permission gate (per tool call) AddOrkeonPermissionGate(config) + Orkeon:Security:PermissionGate:Enabled = true Infrastructure IPermissionGate (ModePermissionGate) β€” consumed by the scripted ctx.llm.act loop and by YAML crews' tool calls (ToolInvocationPipeline) Stable
Shell interpreters & mutating git config only: Orkeon:Tools:Shell:AllowInterpreters = true Tools.Code (re-registers ShellCommandTool with allowInterpreters: true β€” RCE-equivalent, a SECURITY line logged at the first call) Stable
Shell allowlist customization config only: Orkeon:Tools:Shell:ExtraAllowedCommands (additive) / Orkeon:Tools:Shell:AllowedCommands (full replacement β€” cancels AllowInterpreters) Tools.Code (shapes the ShellCommandTool executable allowlist; absent/empty section = defaults) Stable
Native LLM console streaming AddLlmConsoleStreaming(config, enabledByDefault) (the REPL: on unless Orkeon:Cli:ConsoleStreaming:Enabled = false) Cli.Commands.Scripting ILlmDeltaSink (ConsoleLlmDeltaSink) β€” streamed ctx.llm.act deltas rendered on the REPL console, the foreground act as it arrives, every other turn whole line by whole line Stable
Plugin system AddOrkeonPlugins(...) (never registered implicitly; orkeon-repl calls it when its settings carry a Plugins section, no other shipped binary does) Orkeon.Plugins IOrkeonPlugin, IPluginRegistry β€” directory discovery, isolated collectible AssemblyLoadContexts; ⚠️ loaded assemblies run with full trust β€” see Plugins Stable
Local on-device embeddings AddOrkeonLocalEmbeddings() Tools.Embeddings.Local IEmbeddingProvider (BGE-micro-v2 ONNX, 384 dims, CPU, no API key) β€” first link of the embedding resolution chain Stable
External memory providers (Redis, SQLite, ChromaDB, Pinecone, LanceDB) + migration A type β€” Memory:Provider, a crew's memoryProvider:, Orkeon:Rag:Provider β€” plus that provider's host section (Orkeon:Redis, Orkeon:Sqlite, Orkeon:ChromaDb, Orkeon:Pinecone, Orkeon:LanceDb), all bound by AddOrkeonInfrastructure(); MemoryProviderFactory hands out one shared instance per type, which connects on first use. AddOrkeonRedisMemory(configuration) makes Redis the application-wide IMemoryProvider; AddOrkeonLanceDb/AddOrkeonChromaDb/AddOrkeonPinecone(configuration) expose the shared provider by its class (the last two are called by AddOrkeonInfrastructure(configuration) when their section exists) Β· AddOrkeonMemoryMigration() Infrastructure RedisMemoryProvider, LanceDbMemoryProvider (+ LanceDbMigrationService), MemoryMigrationService β€” see Memory system Stable
Cognitive memory AddOrkeonCognitiveMemory(configuration) (Orkeon:CognitiveMemory; the runners call it when Orkeon:CognitiveMemory:Enabled is true) Infrastructure ICognitiveMemoryService β€” LLM analysis, contradiction detection, consolidation, composite recall scoring; needs an LLM provider (the profile Orkeon:CognitiveMemory:Profile) and an IEmbeddingProvider; wired into runs with memory: true β€” see Memory system Preview
LLM exchange logging AddLlmExchangeLogging(logDirectory, options?) (full JSONL capture + structured summary, handler injected into every IHttpClientFactory client but those a tool family excludes with LlmExchangeLogExclusion β€” the drive and e-mail clients; the clients of the web tools and of the RAG web fallback are still captured, so with --llm-log the pages they fetch land in the JSONL as LLM exchanges) β€” wired by RunnerHost only when a run passes --llm-log (LlmLogging section) Infrastructure ILlmExchangeLogger, LlmLoggingDelegatingHandler β€” see LLM providers Stable
Human input tool AddOrkeonHumanInput() (auto-approve fallback provider) / AddOrkeonHumanInput<TProvider>() β€” wired by the runner execution path Infrastructure human_input (IBaseTool), IHumanInputProvider Stable
Session tools AddOrkeonSessionTools(configuration?) (Llm:AvailableModels, Orkeon:Cli:Session, Orkeon:Cli:Memory) β€” wired by RunnerHost and the REPL Infrastructure session_store, session_snip, token_budget, memory_store, session_cost, session_stats; ISessionBufferService, ICategoryMemoryStore (file-backed per project when Orkeon:Cli:Memory:Persist is on, the REPL's default) β€” see Coding agent (TS) Stable
Semantic search tool AddSemanticSearchTool() (Orkeon.Hosting) β€” wired by orkeon run Hosting semantic_search (SearchTool) + IEmbeddingService adapter over IEmbeddingProvider + in-memory IVectorMemoryStore Stable
EventHub core + agent tools AddOrkeonInMemoryEventHub() Β· AddOrkeonEventHubTools() β€” both wired by RunnerHost (hence orkeon run and orkeon-host) Infrastructure / Tools.EventHub IEventHub (in-process), the seven EventHub tools β€” see EventHub Stable
E-mail tools AddOrkeonEmailTools(configuration) (Orkeon:Tools:Email, inert until an account is declared) Β· AddOrkeonEmailTokenStore(fileSystem, virtualDirectory) (OAuth token store) β€” both wired by RunnerHost; the REPL wires the tools only Tools.Email the 13 email_* tools β€” see E-mail tools Stable
Drive tools AddOrkeonDriveTools(configuration) (Orkeon:Tools:Drive, inert until an account is declared) Β· AddOrkeonDriveTokenStore(fileSystem, virtualDirectory) (OAuth token store) β€” both wired by RunnerHost; the REPL wires the tools only Tools.Drive the 11 drive_* tools β€” see Drive tools Stable
Microsoft Agent Framework bridge AddOrkeonAgentFramework() Interop.AgentFramework ICrewAgentFactory (a crew as an AIAgent, loaded and run in a scope of its own every turn) β€” see ADR-010 Stable

Not in this catalog β€” registered by AddOrkeonInfrastructure() and gated by configuration, not by a registration gesture: MCP (MCP section, via the IConfiguration overload, or the runner host once MCP:Servers declares a server), telemetry and vector search (same overload), the parameterless checkpointing store (AddOrkeonCheckpointing(); the SQLite/Postgres variants stay explicit), Evaluation, Consensus, CostTracking, YAML, Encryption and CodeSandbox. The Guardian pipeline, the prompt/tool-result sanitizers and the tool-invocation point are registered too, and every agent turn runs through them (Orkeon:Guardian:Enabled is the switch β€” see Security). Their configuration sections are mapped in the Configuration reference.

Tool families are registered by their own extensions, which the runner host and the REPL call: AddOrkeonFileSystemTools, AddOrkeonWebTools (plus the single-tool AddOrkeonWebSearchTool, AddOrkeonBraveSearchTool, AddOrkeonCacheSearchTool, AddOrkeonSlackTool, AddOrkeonSlackReadTool), AddOrkeonDataTools (plus AddRelationalDatabaseTools, AddMongoDbTools, AddGraphDatabaseTools), AddOrkeonCodeTools, AddOrkeonDriveTools, AddOrkeonAbstractionTools, AddRaggableTreeTools β€” see the tool inventory.

Building blocks registered by AddOrkeonInfrastructure()

Not opt-ins, but public extensions a host meets when it composes its own container: each is called by AddOrkeonInfrastructure() (every one uses TryAdd*, so calling it again is harmless), and each is also callable alone when a host builds a minimal container without the full infrastructure.

Extension Registers Consumed by Call it yourself when
AddOrkeonYaml() CrewFactoryOptions (plain options, lenient tool resolution), ICrewDefinitionLoader β†’ YamlCrewDefinitionLoader, ICrewFactory β†’ CrewFactory (scoped), YamlCrewExporter the runners' crew loading; orkeon forge you load or export YAML crews without AddOrkeonInfrastructure(). Strict tool resolution is Orkeon:CrewFactory:StrictTools, which RunnerHost reads (default true there)
AddOrkeonGuardian() GuardianOptions (Orkeon:Guardian), GuardianPolicyEngine, InputGuard/ToolGuard/DelegationGuard, GuardianPipeline (also as IGuardianPipeline) with the three guards wired to their phases β€” none when Enabled = false the execution orchestrator (input phase), the streaming service, and IToolInvocationPipeline (tool and delegation phases) β€” registered by AddOrkeonApplication() you compose a container without AddOrkeonInfrastructure() and still want the guards β€” see Security

The memory migration service is the one data-moving extension that is not registered by default: AddOrkeonMemoryMigration() β€” see Memory system.

Maturity β€” Stable: tested implementation whose API is covered by the 1.x stability commitment, except the members marked [Experimental] (the corrective RAG pipeline inside the RAG subsystem: see Experimental APIs); what it does not do yet, or what has not been run against a real service, is listed in Known limitations. Preview: functional implementation but not wired into the execution pipeline (the host invokes the service itself) or behaviour still partial (flagged case by case below). The label speaks of the behaviour, not of the API: the API of a Preview subsystem is frozen by the same 1.x commitment as a Stable one; only its wiring and behaviour may still grow. Experimental: reserved for an API marked [Experimental] (A2A, ORKEXP001), which is outside that commitment β€” see Experimental APIs. Neither label says whether the shipped binaries activate a subsystem: the Shipped binaries line of its section does.


A2A server/protocol β€” AddOrkeonA2A(...)

Task persistence add-on: AddOrkeonA2ATaskPersistence() stores A2A task lifecycles over the opt-in checkpointing IStateStore (register one first), turning GET /a2a/tasks/{id} into a real 200/404 endpoint instead of the explicit 501.

  • Role: inter-process agent-to-agent communication (A2A protocol): agent discovery (/.well-known/agent.json), HTTP client, task routing and, optionally, an HTTP server (HttpListener) exposing POST /a2a/tasks/send, sendSubscribe (SSE), GET/DELETE /a2a/tasks/{id}.
  • Activation:
    // By configuration (section "A2A"; "A2A:Security" for mTLS/auth)
    services.AddOrkeonA2A(configuration);
    
    // Or by delegate, without IConfiguration
    services.AddOrkeonA2A(options => options.EnableServer = true);
    
    IA2AServer is only registered when EnableServer is true, together with a hosted service: a generic host starts the server with itself and stops it on shutdown β€” no host code resolves IA2AServer or calls StartAsync. A process that never runs the host never starts it.
  • Execution: the card lists the skills of the registered router (IA2ATaskRouter.GetSkillsAsync) β€” the default one, one skill per available agent β€” and the router runs the agent whose id equals the request's skillId (the id the card publishes) through IAgentExecutionService, so the host also calls AddOrkeonApplication(); without it, a task answers Failed and says so. A host that routes differently registers its own IA2ATaskRouter first: the default router, and the agent directory below, are registered only when no router is.
  • Dependencies: the extension itself registers (TryAdd) IHttpClientFactory, IDomainEventDispatcher, IUnitOfWork, as well as β€” with the default router β€” the A2A agent directory (IAgentRegistrationStore singleton + IAgentRepository scoped, see below) when the host has not already wired them via AddOrkeonInfrastructure().
  • Agent repository lifecycle (scoped per request):
    • IAgentRepository is scoped; the router (a singleton) never captures it β€” it opens a DI scope per A2A request (the card, each task) via IServiceScopeFactory and resolves the repository inside it. Resolution passes with ValidateScopes = true (default in Development).
    • A scoped repository keeps nothing between two requests: registrations live in IAgentRegistrationStore, a thread-safe singleton backing store (InMemoryAgentRegistrationStore, ConcurrentDictionary) from which the scoped repository (SharedStoreAgentRepository) hydrates itself on every call. Agents registered by the pipeline (in its own scopes) are therefore visible to the A2A router, and vice versa.
    • Composition: if the host called AddOrkeonInfrastructure() (which registers the InMemoryAgentRepository with a per-scope store), AddOrkeonA2A(...) overrides this default implementation with SharedStoreAgentRepository (same scoped lifetime, shared data) β€” otherwise the router would never find the agents. Any other IAgentRepository registration (custom/DB repository, which already provides cross-request storage) is left intact. Call AddOrkeonA2A(...) after AddOrkeonInfrastructure() and after any custom repository (recommended order, see Principle); a custom repository registered after AddOrkeonA2A(...) wins (last registration).
  • Shipped binaries: orkeon-host calls AddOrkeonA2A when Orkeon:Host:A2A:Enabled is set, after registering its own router β€” one skill per crew the section exposes, a task being a run of that crew β€” so its runs keep their per-scope agent repository (see Service host); orkeon run and the REPL do not call it. See A2A conformance β€” Task execution and Activation.
  • Known limits: the in-memory store is local to the process β€” for a multi-instance agent directory, provide a custom IAgentRepository backed by external shared storage (it will be respected as-is by the extension).

Monitoring backend β€” AddOrkeonMonitoring(...)

  • Shipped binaries: none activates it. orkeon run, orkeon-host and orkeon-repl do not read Orkeon:Monitoring, and say so at their start when the settings write it.
  • Role: in-process aggregation of Orkeon metrics (MeterListener on the meter Orkeon) and exploration of recent traces (circular buffer) for exposure through a host endpoint (dashboard, diagnostic API).
  • Activation:
    services.AddOrkeonMonitoring(configuration); // binds Orkeon:Monitoring
    services.AddOrkeonMonitoring();              // default options
    
  • Dependencies: logging only (default options are registered when no configuration is passed).
  • Note: does not replace OpenTelemetry telemetry (AddOrkeonTelemetry), which remains wired by the AddOrkeonInfrastructure(IConfiguration) overload.

Traces and metrics follow the OpenTelemetry GenAI conventions

Not an opt-in β€” every run emits them, and the runners (orkeon run, orkeon-host) export them wherever the standard OTEL_EXPORTER_OTLP_ENDPOINT points (a .NET Aspire AppHost sets it β€” see ADR-011) or the Telemetry section of the settings says (Telemetry:OtlpEndpoint). The execution path itself carries the spans, named and attributed by the OpenTelemetry generative-AI semantic conventions so Langfuse, Honeycomb, Application Insights or the Aspire dashboard read them without a mapping. The names are the constants of Orkeon.Constants.Llm.GenAiAttributes.

Span (ActivitySource) Name Attributes
Agent turn (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
Model call (Orkeon.Llm, kind Client) chat {model} gen_ai.operation.name=chat, gen_ai.provider.name (lower-case), 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 on failure; outside an agent turn (the manager, the planner, a host's own call) the providers' entrance opens it, with orkeon.llm.operation, gen_ai.agent.name and orkeon.task.id when known β€” one per call, never a second one inside a current chat
Embedding (Orkeon.Llm) embeddings {model} gen_ai.operation.name=embeddings, gen_ai.provider.name, gen_ai.request.model, orkeon.embeddings.text_count, error.type on failure; one per call to the embedding model β€” an embedding served by the cache has none
Tool execution (Orkeon.Tool) execute_tool {tool} gen_ai.operation.name=execute_tool, gen_ai.tool.name, gen_ai.tool.call.id (the model's own id), gen_ai.agent.name, error.type on failure
Crew run (Orkeon.Crew) crew.run orkeon.crew.id, orkeon.crew.name, orkeon.crew.process, orkeon.crew.task_count; in error when the run fails or is cancelled
Task (Orkeon.Task) task.run one per task, orkeon.task.id; in error when the task fails or is cancelled
Memory (Orkeon.Memory) memory.recall, memory.store under the task that recalls or stores
Scripting runtime (Orkeon.Scripting) the same three, plus crew.run same attributes; orkeon.llm.method (complete/act), orkeon.crew.name, orkeon.crew.process; the source is listed in OrkeonActivitySources.AllNames, so the script's spans are exported

A run is a trace: crew.run > task.run > invoke_agent and memory.*; the manager's and the planner's chat sit under crew.run, a memory's embeddings under its memory.* span.

Metrics (meter Orkeon, OrkeonMeter; the MeterListener listens to it): gen_ai.client.token.usage (histogram, tokens, gen_ai.token.type = input | output) and gen_ai.client.operation.duration (histogram, seconds), both tagged with gen_ai.provider.name and gen_ai.request.model; the orkeon.* counters (calls, tool executions, cost) keep their names. What has no convention keeps the orkeon. prefix β€” the crew, the task, the estimated cost.

Instrument Kind, unit Attributes Measured
orkeon.llm.calls counter, {call} operation, provider, model every model call, once
gen_ai.client.operation.duration histogram, s operation, provider, model, error.type on a failure every model call
gen_ai.client.token.usage histogram, {token} operation, provider, model, gen_ai.token.type usage the vendor reported; unreported usage is not recorded
orkeon.cost.total_usd observable gauge, USD none process-wide total of the USD costs reported since the process started; a cost in another currency does not enter it
orkeon.crew.executions counter, {execution} orkeon.crew.name, orkeon.crew.process, orkeon.outcome (completed, failed, cancelled) every crew run, once, at its end β€” with or without a span listener
orkeon.crew.duration histogram, s same as orkeon.crew.executions every crew run, at its end
orkeon.crew.active up-down counter, {crew} orkeon.crew.name, orkeon.crew.process +1 when a run starts, -1 when it ends
orkeon.task.executions counter, {execution} orkeon.crew.name, orkeon.agent.role when the task has one agent, orkeon.outcome (completed, failed, cancelled) every task, once, at its end; a task skipped because a dependency failed, or still open when the run ends, counts cancelled
orkeon.task.duration histogram, s same as orkeon.task.executions every task, at its end
orkeon.task.active up-down counter, {task} orkeon.crew.name, orkeon.agent.role when the task has one agent +1 when a task starts, -1 when it ends
orkeon.tool.executions counter, {execution} orkeon.tool.name, orkeon.outcome (success, failure, blocked, cancelled) every call through the tool pipeline, once, with or without an audit logger; a response with Success=false counts failure
orkeon.tool.duration histogram, s orkeon.tool.name, orkeon.outcome every call that ran; a blocked call has no duration
orkeon.security.events counter, {event} orkeon.security.kind (block, warn, injection), orkeon.tool.name when known one per call the Guardian blocks (a guard that throws counts block), one per Warn result, one per tool result where an injection pattern is detected (not one per pattern)
orkeon.llm.active up-down counter, {call} none declared, not yet fed

No attribute carries an id of a crew, task or agent.

NIST compliance β€” AddOrkeonNistCompliance()

  • Role: generation of NIST SP 800-53 compliance reports from the audit trail (IAuditLogger).
  • Activation: services.AddOrkeonNistCompliance();
  • Dependencies: the extension TryAdds a fallback audit chain (StructuredLogAuditSink + AuditLogger); when the host has called AddOrkeonInfrastructure(), the core's audit chain (structured + in-memory sinks, Security:Audit options) is used.
  • Known limits: the report reads the trail the agent turns write β€” a ToolExecution event per tool call and a SecurityEvent per Guardian block or warning and per injection pattern found in a tool result; LLM calls, file accesses and HTTP requests are not audited events; no automated control is executed.

DLP β€” AddOrkeonDlp()

  • Shipped binaries: none activates it. orkeon run, orkeon-host and orkeon-repl do not read Orkeon:Dlp, and say so at their start when the settings write it: DLP screens nothing there. What they do screen is set by Security:Prompt and Security:ToolResults.
  • Role: data loss prevention β€” PII detection through regular expressions (IPiiDetector), per-channel policies (IDlpPolicyProvider, Orkeon:Dlp section) and 5 channel interceptors (tool output, delegation, logs, memory, external output).
  • Activation: services.AddOrkeonDlp();
  • Dependencies: logging + IConfiguration (binds Orkeon:Dlp). Self-contained for the rest.
  • Known limits: the interceptors are not invoked automatically by the execution pipeline β€” the host resolves them (GetServices<IDlpInterceptor>()) and applies them to the channels it wants to protect. One exception: the external-output interceptor of a host that registered DLP is applied to the arguments of a streamed tool call, held until the call ends and emitted as one redacted delta. Not to be confused with the PiiDetectionValidator of the output validation pipeline, which remains registered by default and is independent.

Tool rate-limiting & token budget β€” AddOrkeonToolRateLimiting()

  • Shipped binaries: none activates it. orkeon run, orkeon-host and orkeon-repl read neither ToolRateLimiting nor TokenBudget, and say so at their start when the settings write one. The limits they apply are those of the model calls: RateLimiting.
  • Role: per-tool rate limiting (IToolRateLimiter, ToolRateLimiting section) and per-agent/crew token budget tracking (ITokenBudgetTracker, TokenBudget section).
  • Activation: services.AddOrkeonToolRateLimiting();
  • Dependencies: logging + IConfiguration. If AddOrkeonCostTracking() (included in the core) registered IModelPricingRegistry, the tracker uses it for the tokens β†’ cost conversion. Its cost estimate reads the price rows scoped to a provider when the host passes the provider's id (RecordUsage(crewId, agentRole, promptTokens, completionTokens, model, provider)). The id is the provider's name as Orkeon writes it in Llm:Provider β€” deepseek, zai, kimi, qwen, gemini, mistral, grok, minimax, together, mammouth, ollama for the providers with built-in rows of their own; case is ignored. The registry then picks the row as it does for Orkeon:CostTracking: a CustomPricings row beats a built-in one, and within each the rows scoped to the provider come before the rows that name none β€” an Ollama model costs 0 unless a CustomPricings row prices it. Called without the provider, or with an id no row names, the tracker reads only the rows that name no provider. A model no row prices is counted at the tracker's own approximate rates, with or without the provider.
  • Known limits: not wired into tool execution β€” the host queries the limiter/tracker around its tool calls. LLM rate-limiting (ILlmRateLimiter), for its part, remains registered by default because it is applied at the entrance of every provider the host builds or registers β€” each model call takes one lease there, an agent's turn or not.

Key rotation β€” AddOrkeonKeyRotation()

  • Role: real re-encryption of an encrypted memory store's entries during a key rotation β€” IKeyRotationService.RotateAsync(store, oldProvider, newProvider, options?) β€” plus the generation and persistence of a new key via ProvisionNewKeyAsync(secretStore, secretName, keySizeInBits) (IWritableSecretProvider, implemented by DpapiSecretProvider).
  • How it works: two-phase traversal. Staging: each entry is decrypted with the old key, re-encrypted with the new one and written under a staging key (<key>::rotation-staging) β€” the originals remain intact. Switchover: each re-encrypted copy replaces its original, then the staging is deleted. A state marker (__orkeon.key-rotation.state, plain JSON) persists the key version and the phase; each re-encrypted entry carries the orkeon-key-version property.
  • Failures and recovery:
    • failure during staging β†’ automatic rollback of the staging copies: the store remains fully readable with the old key;
    • failure during switchover β†’ roll-forward: re-running RotateAsync with the same providers resumes the rotation where it stopped. Classification through authenticated decryption (AES-GCM) guarantees idempotence: no entry lost, none double-encrypted;
    • entry unreadable with both keys β†’ fail-closed failure by default (rollback); KeyRotationOptions.ContinueOnUnreadableEntries allows skipping it (entry left as-is and reported in KeyRotationResult.Errors).
  • Activation: services.AddOrkeonKeyRotation(); β€” to be paired with AddOrkeonEncryption() (the AES-256-GCM provider itself stays in the core).
  • Dependencies: logging only (the store and the providers are passed as method arguments).
  • How to proceed:
    var rotation = provider.GetRequiredService<IKeyRotationService>();
    
    // 1. Generate and persist the new key under a versioned secret name
    //    (refuses to overwrite an existing secret β€” fail-closed)
    await rotation.ProvisionNewKeyAsync(writableSecrets, "orkeon-encryption-key-v2");
    
    // 2. Re-encrypt the raw store (under the decorator) from the old key to the new one
    var result = await rotation.RotateAsync(rawStore, oldProvider, newProvider);
    
    // 3. Switch the host configuration over to the new secret name
    
  • Known limits: the rotation runs on the raw memory provider (under the EncryptedMemoryProviderDecorator decorator, type MemoryProviderBase for key enumeration) and assumes no concurrent write occurs during the rotation window. AesEncryptionProvider.RotateKeyAsync is neutralized (NotSupportedException): an "in-place" rotation would orphan the existing data β€” go through IKeyRotationService.

Evaluation benchmarking β€” AddOrkeonBenchmarking()

  • Role: repeated execution of an evaluation suite per test case with mean/stddev statistics (IBenchmarkRunner).
  • Activation: services.AddOrkeonBenchmarking(); β€” to be paired with AddOrkeonEvaluation() (included in the core) to build the suites. The default IEvaluationSuite carries the LLM judges when Evaluation:EnableLlmJudge is true β€” bound by AddOrkeonInfrastructure(configuration).
  • Shipped binaries: the runner hosts (orkeon, orkeon-host) register it and bind the Evaluation section with AddOrkeonEvaluation(configuration); orkeon eval bench runs it (orkeon eval run scores a dataset with the default suite).
  • Dependencies: none (the evaluation suite is provided via BenchmarkConfig at call time).

Multi-modal content (vision) β€” AddOrkeonMultiModal(...)

  • Shipped binaries: none activates it. orkeon run, orkeon-host and orkeon-repl do not read Orkeon:MultiModal, and say so at their start when the settings write it.
  • Status: real β€” vision is wired end to end: image contents flow from the MultiModalContent abstractions (Domain) to provider payloads via LlmMessage.MultiModalContent. AnthropicLlmProvider emits image content blocks conforming to the Messages API ({"type":"image","source":{"type":"base64"|"url",…}}); OpenAILlmProvider emits image_url parts conforming to Chat Completions (http(s) URL or base64 data URL). See the multi-modal guide.
  • Role: validation of multi-modal contents (size, format, duration) via IContentValidationService (Orkeon:MultiModal options) and image loading from the virtual file system via IMultiModalContentLoader (VFS read β†’ bytes β†’ base64, MIME type inferred from the extension, validation of the configured constraints).
  • Activation:
    services.AddOrkeonMultiModal(configuration); // binds Orkeon:MultiModal
    services.AddOrkeonMultiModal();              // default options
    
  • Dependencies: IContentValidationService only needs the options; IMultiModalContentLoader requires a resolvable IFileSystemService (AddOrkeonFileSystem(configuration) in real hosts).
  • Known limits: vision payload composition is capability-driven (LlmProviderCapabilities.Vision, translated once by OpenAICompatibleProviderBase) β€” all 16 providers declare it; a provider without the capability degrades multi-modal messages to their text fallback (LlmMessage.Content). Supported image formats: png, jpeg, gif, webp. Audio/file parts are not sent by any provider and throw an explicit NotSupportedException if they reach a vision payload.

Kickoff hooks β€” AddOrkeonKickoffHooks()

  • Role: execution of BeforeKickoffHook / AfterKickoffHook callbacks around a crew's kickoff, in increasing Priority order, with ContinueOnError semantics (exceptions from tolerant hooks are logged then ignored).
  • Activation:
    services.AddOrkeonKickoffHooks(); // the runner alone
    services.AddBeforeKickoffHook(new BeforeKickoffHook
    {
        Name = "audit",
        Priority = 1,
        Execute = crew => /* ... */ System.Threading.Tasks.Task.CompletedTask,
    }); // registers the hook AND the runner
    
  • Dependencies: none (hook collections empty by default, optional logging).
  • Known limits: the orchestrator does not invoke the runner: the host calls it itself:
    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);
    

Codebase context (RaggableTree) β€” AddRaggableTree(options)

  • Role: ICodebaseContextProvider produces codebase summaries meant to be injected into the agents' context (RaggableTree feature).
  • Activation: registered by AddRaggableTree(options) (Orkeon.Analysis project). The core library never calls it β€” but the runner host does, by default (orkeon run/orkeon-host; opt out with "RaggableTree:Enabled": false), consistent with this catalog's own entry above. See raggable-tree.md.
  • Known limits: no framework component consumes it automatically β€” the host resolves it and injects the summaries wherever it wishes (system prompt, task context…).

RAG subsystem β€” AddOrkeonRag(configuration)

  • Role: retrieval-augmented generation β€” ingestion (loaders, chunking, validation, incremental manifest), staged retrieval pipeline (transform β†’ retrieve β†’ fuse (+ opt-in MMR) β†’ rerank β†’ assemble β†’ generate β†’ groundedness), the corrective CRAG graph, profile presets and the offline eval harness. Full guide: rag-pipeline.md, decisions: ADR-006.
  • Activation:
    services.AddOrkeonRag(configuration);   // Orkeon.Rag.DependencyInjection
    services.AddOrkeonRagTools();           // Orkeon.Tools.Rag: rag_search / rag_ingest / rag_eval
    services.AddOrkeonOnnxReranker();       // opt-in β€” required by balanced/quality/adaptive
    
    Every runner host built on RunnerHost (orkeon run, orkeon-host) makes the first two calls itself, and so does the orkeon-repl REPL; the three shipped binaries β€” orkeon, orkeon-host, orkeon-repl β€” add the third (RunnerHost does not: the Orkeon.Hosting package stays free of ONNX). AddOrkeonRag already wires the query transformers, routing, hybrid BM25+RRF, the corrective graph and the web-fallback transport registration β€” calling AddOrkeonRagWebFallback(configuration) yourself is a no-op; the feature is governed by the two config switches below.
  • Profiles (Orkeon:Rag:Profile, default fast; per-key overrides apply on top of the preset): fast (vector only) and corrective (CRAG graph β€” loops instead of a linear rerank stage) run without the ONNX packages; balanced/quality enable the cross-encoder rerank stage and adaptive delegates its SingleShot route to balanced, so those three fail fast at the first query (actionable exception) unless AddOrkeonOnnxReranker() (Orkeon.Rag.Onnx + Orkeon.Rag.Onnx.Model, int8 weights embedded, offline) is registered.
  • Web fallback (double opt-in, off by default): the corrective graph's web_fallback node runs only when both Orkeon:Rag:Corrective:WebFallback:Enabled (policy) and Orkeon:Rag:WebFallback:Enabled + a non-empty Endpoint (transport, SearxNG) are set. Every fetched page is screened by PromptInjectionDocumentValidator (Rejected never enters the working set; Suspicious follows the configured policy) β€” see security.md.
  • Projects: Orkeon.Rag.Abstractions (contracts, Domain-only), Orkeon.Rag (implementations), Orkeon.Tools.Rag (agent tools), Orkeon.Rag.Onnx + Orkeon.Rag.Onnx.Model (opt-in reranker + weights).
  • Known limits: see limitations.md β€” offline degradation of the LLM-dependent nodes (corrective/adaptive), heuristic classifier by default, in-process BM25 unpersisted.

Execution state persistence β€” AddCrewExecutionStatePersistence(...)

  • Shipped binaries: orkeon run and orkeon-host read Orkeon:Checkpointing (the store) and Orkeon:ExecutionState:Persistence (the switch). Orkeon:Checkpointing:Enabled=true with Store json, sqlite or postgres gives every run of the host a durable checkpoint session, and the persistence of execution states the same store. json and sqlite write under ./.orkeon/state, mounted at /state as an internal mount. orkeon-repl reads neither; its start does not report them, since the other two binaries read them.
  • Run identity: one run has one identifier, an ExecutionId: the checkpoint session id, the correlationId of the events orkeon run --events writes, and the id the no-wait kickoff returns. KickoffOptions.ExecutionId hands it in (resume, host); IRunScope.Current shows it to every decorator and observer the run reaches. The crew key of a session (SessionState.CrewKey) is the crew's name unless KickoffOptions.CrewKey names it; orkeon run and orkeon-host name it with the crew's name, the virtual path of its file and a digest of the file's full path, so that a session can be found again by a new process whatever the ids of the crew and its tasks, regenerated at each load. The A2A task id and the API's are not unified with it. A run kicked off inside another one enters its own scope: its identifier overrides the outer one for its length.
  • Checkpoint per task and --resume: each task a crew run completes is written to the checkpoint session as it ends, by a decorator of IAgentExecutionService that every orchestration mode goes through (sequential, parallel, hierarchical, graph, autonomous, consensual), under the key "{TaskKey}#{n}": TaskKey is the task's name in the crew definition, n the ordinal of that key's invocation in the run (a Hierarchical revision is #2; the attempts of a task's retry: share one key). A task that fails or throws is not checkpointed, and a retried task is checkpointed once, for the attempt that succeeded (RetryCount records the retries): a run stopped between two attempts resumes that task from attempt 1; a checkpoint that cannot be written fails the task. orkeon run <crew> --resume <id>|latest continues the run <id> (the id a failed run prints: Run <id> did not complete. Resume it ...), or the latest run of that crew file that is not completed (and not still marked Running: latest does not take over a run that may be alive in another process, the store holds no lease; name its id to take it over): the run keeps its id, the tasks it had completed come back from the checkpoint (task.completed carries resumed: true, and no model is asked; a task that had ended on its iteration cap comes back with endedOnIterationCap: true, a typed one too, as TaskResult<TOutput>.EndedOnIterationCap, and one that ended without its tool_call deliverable comes back with deliverableMissing: true, false from a checkpoint written before the flag; the deliverable path comes back too, typed results included, a tool_call deliverable whose file is gone at resume comes back missing, a final_message or structured_output one only loses its path, and a task that had retried reports attempt = its retries + 1), the others run. Next to its output a checkpoint keeps a fingerprint of the task (description, expected output, agent, dependencies): a task edited since is run again with every task after it, and one warning names it. It needs Orkeon:Checkpointing:Enabled=true and is refused with --validate, with --list-tools, on a procedural .ork.ts and, with --events, without an explicit run id. In a host written in C#, pass KickoffOptions.Resume ("latest" or the id). Task names are unique in a crew.
  • Role: durable persistence of crew execution states (ScopedCrewExecutionStateManager) in a checkpointing state store (IStateStore): every transition (creation, update, completion, archiving) is persisted, and on restart the states are reloaded β€” including resumption via CreateStateAsync(crewId, executionId, input) when a persisted state already exists for the resume identifier (crash recovery).
  • Activation (two conditions β€” a store and the option):
    // 1. A checkpointing state store (in-memory, SQLite or PostgreSQL)
    services.AddOrkeonSqliteCheckpointing("Data Source=/output/orkeon-state.db"); // virtual path, writable mount
    // or: services.AddOrkeonCheckpointing();              // in-memory
    // or: services.AddOrkeonCheckpointing(configuration); // Orkeon:Checkpointing: Enabled, Store memory|json|sqlite|postgres
    // or: services.AddOrkeonPostgresCheckpointing(configuration); // Orkeon:Checkpointing:*
    
    // 2. The persistence opt-in
    services.AddCrewExecutionStatePersistence();             // code-first
    services.AddCrewExecutionStatePersistence(configuration); // binds Orkeon:ExecutionState:Persistence
    
    The SQLite store resolves its Data Source through the VFS like the SQLite memory provider: it needs a registered IFileSystemService (AddOrkeonFileSystem(...)) and a path on a writable mount, otherwise it throws FileAccessDeniedException. With the AddOrkeonInfrastructure(IConfiguration) overload, the presence of the Orkeon:ExecutionState:Persistence section (Enabled, DeleteFromStoreOnArchive) is enough to bind the options.
  • Default: without activation, states remain in-memory only (no recovery after a crash). If the option is enabled without a registered store, the manager logs a warning and continues in memory.
  • Cohabitation: execution state sessions are namespaced (crew-exec: prefix on the session id and the crew id) and never pollute the task checkpointing sessions (CheckpointManager/ResumeEngine) sharing the same store.
  • Known limits: execution metadata is persisted as invariant strings (primitive reads are still converted via GetValue<T>); the ToolsUsed telemetry of task outputs is not persisted (v1).

Permission gate β€” AddOrkeonPermissionGate(configuration)

  • Activation: called by RunnerHost and the ConsoleApp bootstrap, but registers nothing unless Orkeon:Security:PermissionGate:Enabled = true. When the host registers an IToolApprovalChannel (orkeon-repl does), the gate puts every ask to it and returns allow or deny. Without a channel, Interactive (default false) declares a caller that resolves asks itself; left false, an ask is a refusal.
  • Effect: ModePermissionGate is consulted by the scripted ctx.llm.act loop and by YAML crews' tool calls (ToolInvocationPipeline) before EACH tool execution. Modes: bypassPermissions β†’ allow all; plan β†’ deny non-reads; dontAsk β†’ allow reads, deny the rest without ever asking; acceptEdits β†’ auto-accept reads and edits (file_write, spawn_agent, the code-graph edits, any tool declaring ToolAccess.Edit such as rag_ingest), ask for everything else (shell_command among them); default β†’ auto-accept reads, ask for everything else. With an approval channel, an ask waits for the operator, and the script's ExecutionTimeout and the agent's wall-time budget (.budget({ wallTime })) stop meanwhile; a refusal reads DENIED: … The operator denied the call. Headless, every ask degrades to a motivated DENIED: fed back to the model as the tool result (no exception). Unknown tools are classified as writes (fail-closed). The session's permission rules (set from a script with ctx.services.get("permissions"), see the CLI reference) are checked before the mode: a deny rule refuses in every mode, an allow rule admits the call in every mode but plan.
  • Declarative classification: tools can self-declare their class via IBaseTool.Access (ToolAccess.Read / Edit / Execute) β€” a declaration wins over the gate's name tables; Unspecified (the default) falls back to the tables. A tool whose class depends on the operation asked overrides IBaseTool.AccessFor(arguments) (default: Access), which the gate reads for each call: github is Read for list_issues, get_pr, search_repos and get_repo, Execute for create_issue, create_pr and any unknown or missing action; http_api is Read for GET, HEAD and OPTIONS (a missing method is its default GET) without a body or a method-override header (X-HTTP-Method-Override, X-HTTP-Method, X-Method-Override, any case), Execute for any other method or for a read method that carries either. Their static Access stays Execute, the most restrictive class they can take. The built-in read tools (file/directory/session/memory/analysis, web_scrape, scrape_element, rag_search, web_search), file_write, rag_ingest (Edit: it writes into the knowledge index, never into the workspace) and rag_eval (Edit: it ingests the dataset's corpus into the collection β€” reindex rebuilds it β€” and writes its reports through the VFS) and shell_command (Execute) all declare themselves. An MCP tool takes its class from the server's annotations only when the operator trusts that server (MCP:Servers:<name>:TrustAnnotations = true: readOnlyHint: true β†’ Read, other annotations β†’ Execute); an untrusted server's tools β€” the default β€” and a server that sends no annotations stay Unspecified, whatever their hints say. BuiltInToolAccessTests lists the built-in tools still left at Unspecified.
  • Default: flag absent β†’ no gate registered β†’ act runs its tool calls unchecked. Scripts opt into a mode per call via the permissionMode act option. A script reads whether a gate checks its calls with ctx.llm.permissionGate.enabled; a permissionMode passed to act on a host without a gate logs one warning (event id 2 of JsLlmFacade) instead of being dropped in silence.

Shell interpreters & mutating git β€” Orkeon:Tools:Shell:AllowInterpreters

  • Activation: config only β€” AddOrkeonCodeTools() reads the flag and, when true, constructs ShellCommandTool with allowInterpreters: true (re-enables node/dotnet/npm/find AND lifts the read-only git subcommand restriction so git add/commit/branch work). The tool logs one SECURITY line per host, at the first shell_command call, stating the confinement in force (the backend, or none/unavailable with its reason, network on/off).
  • Security: RCE-equivalent on the host β€” reserve it for trusted coding-agent hosts running inside a confined workspace (the scripted-commands REPL is the reference consumer β€” see examples/cli-ts-commands/; a commit command cannot work without it).
  • Default: flag absent β†’ strict read-only allowlist, as without the option.
  • Allowlist customization (two string-array keys, both read by AddOrkeonCodeTools()):
    • Orkeon:Tools:Shell:ExtraAllowedCommands β€” additive on top of the default allowlist (or of a replacement list); the recommended way to allow make/cargo/etc. for a trusted host. Composes with AllowInterpreters.
    • Orkeon:Tools:Shell:AllowedCommands β€” full verbatim replacement; per the ShellCommandTool ctor contract it cancels AllowInterpreters and re-enables the read-only git subcommand restriction.
    • An absent or empty section binds to null (defaults) β€” never to an empty array, which would block every command.
  • VFS path rewriting (always on, no flag; under bubblewrap the process sees the virtual paths and nothing is rewritten): arguments naming a mount-prefixed virtual path (incl. --out=/workspace/dist) are resolved virtualβ†’physical before the process starts β€” a denied path fails the call with the redacted reason β€” and stdout/stderr are rewritten physicalβ†’virtual, so the model only ever sees virtual paths. AgentFacing mounts, ordinal matching; without mounts both passes are no-ops.
  • Confinement is not opt-in (Orkeon:Tools:Shell:Confinement): the process runs confined by default (Mode = Auto: bubblewrap on Linux, Seatbelt on macOS, an AppContainer on Windows, off in a container), and AllowInterpreters lets in more commands, not a wider view. Mode = None is the opt-out β€” see Shell confinement.

Native LLM console streaming β€” AddLlmConsoleStreaming(configuration, enabledByDefault)

  • Activation: called by the ConsoleApp bootstrap, which turns it on unless Orkeon:Cli:ConsoleStreaming:Enabled = false; enabledByDefault (false) is what an unset key means, so a crew host keeps it off unless the key is true.
  • Effect: registers ConsoleLlmDeltaSink as the ILlmDeltaSink. When a sink is present and the LLM provider streams (IStreamingLlmProvider), the scripted ctx.llm.act loop switches to the SSE path and every content delta reaches the host IConsoleAdapter as it arrives β€” the REPL renders the foreground act's tokens as they arrive without the script passing onDelta. Every other turn (ILlmDeltaSink.BeginTurn) β€” a second act streaming at once, an act under a background command instance, a crew task β€” holds its own line buffer and writes one whole line at a time, prefixed with the instance's ticket ([t2] ), as the completion lines are, a crew task adding its id ([t2 task-1] ) β€” the prefix stays in plain mode, while the split-pane console drops the prefix, shows the line on the task's screen and keeps the crew label ([task-1] ); a line of theirs that arrives while the foreground act is inside a line waits for that line's end. So two acts streaming at once β€” two background runAgent sub-runs, the tasks of a parallel crew wave β€” never write into one another and no line is cut. Turns that stream no visible content (pure tool calls) emit nothing. The sink composes with a script-side onDelta (both receive every delta).
  • Telling the script it already streamed: the CommandResponse a request() returns or a completed(result) receives, and the CrewRunOutput of runCrew, carry streamed: boolean, true when any turn of the request was written to the console in the foreground (inline, or as whole unprefixed lines); a script prints the payload only when streamed is false, so the answer shows once. A background instance (post, runCrewAsync) and a crew task write whole prefixed lines and report false. The dispatch opens one receipt per agent request and per crew run in that work's async flow; the sink's turns record into it, it never goes back to false within a request, and commands running at once each read their own.
  • Default: flag absent β†’ no sink registered β†’ act keeps its buffered rendering (byte-identical), scripts can still stream via onDelta.

Non-regression guarantees

The registration tests (tests/core/Orkeon.Infrastructure.Tests/DependencyInjection/OptInSubsystemsRegistrationTests.cs and tests/core/Orkeon.Application.Tests/DependencyInjection/KickoffHookExtensionsTests.cs) verify:

  1. that no dormant port of the original opt-in set is registered by AddOrkeonApplication() / AddOrkeonInfrastructure() (both overloads) β€” the rows added later (plugins, local embeddings, memory providers, cognitive memory, the tool and logging registrations…) are guarded by their own suites, not by this test;
  2. that each AddOrkeonXxx() produces a graph that is resolvable on its own (with logging and, where applicable, an IConfiguration);
  3. that the opt-ins compose with the core (TryAdd semantics, no duplicates).

Run history: Orkeon:RunHistory

  • Shipped binaries: orkeon run, orkeon-host and orkeon runs read Orkeon:RunHistory. It is off in the library and in orkeon run, on in orkeon-host and in the settings orkeon init writes. Enabled=true keeps the events of every run after it ended, with Store jsonl (default) or sqlite, under ./.orkeon/runs mounted at /runs as an internal mount; orkeon runs list|show|tail reads them back. A run is recorded with or without --events (without it, nothing is written to stdout). orkeon-repl does not publish run events. What is stored, and masked, is in orkeon runs; the orkeon init template turns the history on and adds .orkeon/ to the .gitignore of the current folder.
  • A host written in C# gets the history from RunnerHost (Orkeon:RunHistory:Enabled, or RunHistoryByDefault of its RunnerMountPlan), or writes to the public SqliteRunEventSink (experimental ORKEXP007, see experimental APIs) and reads back through IRunHistoryReader; RunEventPublisher and JsonLinesFileRunEventSink are internal.