π«π· Version franΓ§aise
Opt-in subsystems
The subsystems below are not registered by default:
AddOrkeonApplication()andAddOrkeonInfrastructure()(both overloads) leave them out unless a row says otherwise, and each one is enabled through its dedicatedAddOrkeonXxx()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 (MCPsection, via theIConfigurationoverload, or the runner host onceMCP:Serversdeclares 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:Enabledis 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-toolAddOrkeonWebSearchTool,AddOrkeonBraveSearchTool,AddOrkeonCacheSearchTool,AddOrkeonSlackTool,AddOrkeonSlackReadTool),AddOrkeonDataTools(plusAddRelationalDatabaseTools,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 checkpointingIStateStore(register one first), turningGET /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) exposingPOST /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);IA2AServeris only registered whenEnableServeris true, together with a hosted service: a generic host starts the server with itself and stops it on shutdown β no host code resolvesIA2AServeror callsStartAsync. 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'sskillId(theidthe card publishes) throughIAgentExecutionService, so the host also callsAddOrkeonApplication(); without it, a task answersFailedand says so. A host that routes differently registers its ownIA2ATaskRouterfirst: 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 (IAgentRegistrationStoresingleton +IAgentRepositoryscoped, see below) when the host has not already wired them viaAddOrkeonInfrastructure(). - Agent repository lifecycle (scoped per request):
IAgentRepositoryis scoped; the router (a singleton) never captures it β it opens a DI scope per A2A request (the card, each task) viaIServiceScopeFactoryand resolves the repository inside it. Resolution passes withValidateScopes = 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 theInMemoryAgentRepositorywith a per-scope store),AddOrkeonA2A(...)overrides this default implementation withSharedStoreAgentRepository(same scoped lifetime, shared data) β otherwise the router would never find the agents. Any otherIAgentRepositoryregistration (custom/DB repository, which already provides cross-request storage) is left intact. CallAddOrkeonA2A(...)afterAddOrkeonInfrastructure()and after any custom repository (recommended order, see Principle); a custom repository registered afterAddOrkeonA2A(...)wins (last registration).
- Shipped binaries:
orkeon-hostcallsAddOrkeonA2AwhenOrkeon:Host:A2A:Enabledis 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 runand 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
IAgentRepositorybacked by external shared storage (it will be respected as-is by the extension).
Monitoring backend β AddOrkeonMonitoring(...)
- Shipped binaries: none activates it.
orkeon run,orkeon-hostandorkeon-repldo not readOrkeon:Monitoring, and say so at their start when the settings write it. - Role: in-process aggregation of Orkeon metrics (
MeterListeneron the meterOrkeon) 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 theAddOrkeonInfrastructure(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 calledAddOrkeonInfrastructure(), the core's audit chain (structured + in-memory sinks,Security:Auditoptions) is used. - Known limits: the report reads the trail the agent turns write β a
ToolExecutionevent per tool call and aSecurityEventper 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-hostandorkeon-repldo not readOrkeon:Dlp, and say so at their start when the settings write it: DLP screens nothing there. What they do screen is set bySecurity:PromptandSecurity:ToolResults. - Role: data loss prevention β PII detection through regular
expressions (
IPiiDetector), per-channel policies (IDlpPolicyProvider,Orkeon:Dlpsection) and 5 channel interceptors (tool output, delegation, logs, memory, external output). - Activation:
services.AddOrkeonDlp(); - Dependencies: logging +
IConfiguration(bindsOrkeon: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 thePiiDetectionValidatorof 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-hostandorkeon-replread neitherToolRateLimitingnorTokenBudget, 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,ToolRateLimitingsection) and per-agent/crew token budget tracking (ITokenBudgetTracker,TokenBudgetsection). - Activation:
services.AddOrkeonToolRateLimiting(); - Dependencies: logging +
IConfiguration. IfAddOrkeonCostTracking()(included in the core) registeredIModelPricingRegistry, 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 inLlm:Providerβdeepseek,zai,kimi,qwen,gemini,mistral,grok,minimax,together,mammouth,ollamafor the providers with built-in rows of their own; case is ignored. The registry then picks the row as it does forOrkeon:CostTracking: aCustomPricingsrow 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 aCustomPricingsrow 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 viaProvisionNewKeyAsync(secretStore, secretName, keySizeInBits)(IWritableSecretProvider, implemented byDpapiSecretProvider). - 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 theorkeon-key-versionproperty. - 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
RotateAsyncwith 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.ContinueOnUnreadableEntriesallows skipping it (entry left as-is and reported inKeyRotationResult.Errors).
- Activation:
services.AddOrkeonKeyRotation();β to be paired withAddOrkeonEncryption()(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
EncryptedMemoryProviderDecoratordecorator, typeMemoryProviderBasefor key enumeration) and assumes no concurrent write occurs during the rotation window.AesEncryptionProvider.RotateKeyAsyncis neutralized (NotSupportedException): an "in-place" rotation would orphan the existing data β go throughIKeyRotationService.
Evaluation benchmarking β AddOrkeonBenchmarking()
- Role: repeated execution of an evaluation suite per test case with
mean/stddev statistics (
IBenchmarkRunner). - Activation:
services.AddOrkeonBenchmarking();β to be paired withAddOrkeonEvaluation()(included in the core) to build the suites. The defaultIEvaluationSuitecarries the LLM judges whenEvaluation:EnableLlmJudgeistrueβ bound byAddOrkeonInfrastructure(configuration). - Shipped binaries: the runner hosts (
orkeon,orkeon-host) register it and bind theEvaluationsection withAddOrkeonEvaluation(configuration);orkeon eval benchruns it (orkeon eval runscores a dataset with the default suite). - Dependencies: none (the evaluation suite is provided via
BenchmarkConfigat call time).
Multi-modal content (vision) β AddOrkeonMultiModal(...)
- Shipped binaries: none activates it.
orkeon run,orkeon-hostandorkeon-repldo not readOrkeon: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
MultiModalContentabstractions (Domain) to provider payloads viaLlmMessage.MultiModalContent.AnthropicLlmProvideremits image content blocks conforming to the Messages API ({"type":"image","source":{"type":"base64"|"url",β¦}});OpenAILlmProvideremitsimage_urlparts 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:MultiModaloptions) and image loading from the virtual file system viaIMultiModalContentLoader(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:
IContentValidationServiceonly needs the options;IMultiModalContentLoaderrequires a resolvableIFileSystemService(AddOrkeonFileSystem(configuration)in real hosts). - Known limits: vision payload composition is capability-driven
(
LlmProviderCapabilities.Vision, translated once byOpenAICompatibleProviderBase) β 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 explicitNotSupportedExceptionif they reach a vision payload.
Kickoff hooks β AddOrkeonKickoffHooks()
- Role: execution of
BeforeKickoffHook/AfterKickoffHookcallbacks around a crew's kickoff, in increasingPriorityorder, withContinueOnErrorsemantics (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:
ICodebaseContextProviderproduces codebase summaries meant to be injected into the agents' context (RaggableTree feature). - Activation: registered by
AddRaggableTree(options)(Orkeon.Analysisproject). 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:
Every runner host built onservices.AddOrkeonRag(configuration); // Orkeon.Rag.DependencyInjection services.AddOrkeonRagTools(); // Orkeon.Tools.Rag: rag_search / rag_ingest / rag_eval services.AddOrkeonOnnxReranker(); // opt-in β required by balanced/quality/adaptiveRunnerHost(orkeon run,orkeon-host) makes the first two calls itself, and so does theorkeon-replREPL; the three shipped binaries βorkeon,orkeon-host,orkeon-replβ add the third (RunnerHostdoes not: theOrkeon.Hostingpackage stays free of ONNX).AddOrkeonRagalready wires the query transformers, routing, hybrid BM25+RRF, the corrective graph and the web-fallback transport registration β callingAddOrkeonRagWebFallback(configuration)yourself is a no-op; the feature is governed by the two config switches below. - Profiles (
Orkeon:Rag:Profile, defaultfast; per-key overrides apply on top of the preset):fast(vector only) andcorrective(CRAG graph β loops instead of a linear rerank stage) run without the ONNX packages;balanced/qualityenable the cross-encoder rerank stage andadaptivedelegates itsSingleShotroute tobalanced, so those three fail fast at the first query (actionable exception) unlessAddOrkeonOnnxReranker()(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_fallbacknode runs only when bothOrkeon:Rag:Corrective:WebFallback:Enabled(policy) andOrkeon:Rag:WebFallback:Enabled+ a non-emptyEndpoint(transport, SearxNG) are set. Every fetched page is screened byPromptInjectionDocumentValidator(Rejectednever enters the working set;Suspiciousfollows 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 runandorkeon-hostreadOrkeon:Checkpointing(the store) andOrkeon:ExecutionState:Persistence(the switch).Orkeon:Checkpointing:Enabled=truewithStorejson,sqliteorpostgresgives every run of the host a durable checkpoint session, and the persistence of execution states the same store.jsonandsqlitewrite under./.orkeon/state, mounted at/stateas an internal mount.orkeon-replreads 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, thecorrelationIdof the eventsorkeon run --eventswrites, and the id the no-wait kickoff returns.KickoffOptions.ExecutionIdhands it in (resume, host);IRunScope.Currentshows it to every decorator and observer the run reaches. The crew key of a session (SessionState.CrewKey) is the crew's name unlessKickoffOptions.CrewKeynames it;orkeon runandorkeon-hostname 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 ofIAgentExecutionServicethat every orchestration mode goes through (sequential, parallel, hierarchical, graph, autonomous, consensual), under the key"{TaskKey}#{n}":TaskKeyis the task's name in the crew definition,nthe ordinal of that key's invocation in the run (a Hierarchical revision is#2; the attempts of a task'sretry:share one key). A task that fails or throws is not checkpointed, and a retried task is checkpointed once, for the attempt that succeeded (RetryCountrecords 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>|latestcontinues 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 markedRunning:latestdoes 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.completedcarriesresumed: true, and no model is asked; a task that had ended on its iteration cap comes back withendedOnIterationCap: true, a typed one too, asTaskResult<TOutput>.EndedOnIterationCap, and one that ended without itstool_calldeliverable comes back withdeliverableMissing: true,falsefrom a checkpoint written before the flag; the deliverable path comes back too, typed results included, atool_calldeliverable whose file is gone at resume comes back missing, afinal_messageorstructured_outputone only loses its path, and a task that had retried reportsattempt= 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 needsOrkeon:Checkpointing:Enabled=trueand is refused with--validate, with--list-tools, on a procedural.ork.tsand, with--events, without an explicit run id. In a host written in C#, passKickoffOptions.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 viaCreateStateAsync(crewId, executionId, input)when a persisted state already exists for the resume identifier (crash recovery). - Activation (two conditions β a store and the option):
The SQLite store resolves its// 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:PersistenceData Sourcethrough the VFS like the SQLite memory provider: it needs a registeredIFileSystemService(AddOrkeonFileSystem(...)) and a path on a writable mount, otherwise it throwsFileAccessDeniedException. With theAddOrkeonInfrastructure(IConfiguration)overload, the presence of theOrkeon:ExecutionState:Persistencesection (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>); theToolsUsedtelemetry of task outputs is not persisted (v1).
Permission gate β AddOrkeonPermissionGate(configuration)
- Activation: called by
RunnerHostand the ConsoleApp bootstrap, but registers nothing unlessOrkeon:Security:PermissionGate:Enabled = true. When the host registers anIToolApprovalChannel(orkeon-repldoes), the gate puts every ask to it and returns allow or deny. Without a channel,Interactive(defaultfalse) declares a caller that resolves asks itself; leftfalse, an ask is a refusal. - Effect:
ModePermissionGateis consulted by the scriptedctx.llm.actloop 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 declaringToolAccess.Editsuch asrag_ingest), ask for everything else (shell_commandamong them);defaultβ auto-accept reads, ask for everything else. With an approval channel, an ask waits for the operator, and the script'sExecutionTimeoutand the agent's wall-time budget (.budget({ wallTime })) stop meanwhile; a refusal readsDENIED: β¦ The operator denied the call.Headless, every ask degrades to a motivatedDENIED: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 withctx.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 butplan. - 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 overridesIBaseTool.AccessFor(arguments)(default:Access), which the gate reads for each call:githubisReadforlist_issues,get_pr,search_reposandget_repo,Executeforcreate_issue,create_prand any unknown or missing action;http_apiisReadforGET,HEADandOPTIONS(a missing method is its defaultGET) without a body or a method-override header (X-HTTP-Method-Override,X-HTTP-Method,X-Method-Override, any case),Executefor any other method or for a read method that carries either. Their staticAccessstaysExecute, 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) andrag_eval(Edit: it ingests the dataset's corpus into the collection βreindexrebuilds it β and writes its reports through the VFS) andshell_command(Execute) all declare themselves. An MCP tool takes its class from the server'sannotationsonly 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 stayUnspecified, whatever their hints say.BuiltInToolAccessTestslists the built-in tools still left atUnspecified. - Default: flag absent β no gate registered β
actruns its tool calls unchecked. Scripts opt into a mode per call via thepermissionModeact option. A script reads whether a gate checks its calls withctx.llm.permissionGate.enabled; apermissionModepassed toacton a host without a gate logs one warning (event id2ofJsLlmFacade) instead of being dropped in silence.
Shell interpreters & mutating git β Orkeon:Tools:Shell:AllowInterpreters
- Activation: config only β
AddOrkeonCodeTools()reads the flag and, whentrue, constructsShellCommandToolwithallowInterpreters: true(re-enablesnode/dotnet/npm/findAND lifts the read-only git subcommand restriction sogit add/commit/branchwork). The tool logs oneSECURITYline per host, at the firstshell_commandcall, stating the confinement in force (the backend, ornone/unavailablewith 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 allowmake/cargo/etc. for a trusted host. Composes withAllowInterpreters.Orkeon:Tools:Shell:AllowedCommandsβ full verbatim replacement; per theShellCommandToolctor contract it cancelsAllowInterpretersand 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.AgentFacingmounts, 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), andAllowInterpreterslets in more commands, not a wider view.Mode = Noneis 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 istrue. - Effect: registers
ConsoleLlmDeltaSinkas theILlmDeltaSink. When a sink is present and the LLM provider streams (IStreamingLlmProvider), the scriptedctx.llm.actloop switches to the SSE path and every content delta reaches the hostIConsoleAdapteras it arrives β the REPL renders the foreground act's tokens as they arrive without the script passingonDelta. 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 backgroundrunAgentsub-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-sideonDelta(both receive every delta). - Telling the script it already streamed: the
CommandResponsearequest()returns or acompleted(result)receives, and theCrewRunOutputofrunCrew, carrystreamed: 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 whenstreamedis 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 β
actkeeps its buffered rendering (byte-identical), scripts can still stream viaonDelta.
Non-regression guarantees
The registration tests
(tests/core/Orkeon.Infrastructure.Tests/DependencyInjection/OptInSubsystemsRegistrationTests.cs
and tests/core/Orkeon.Application.Tests/DependencyInjection/KickoffHookExtensionsTests.cs)
verify:
- 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; - that each
AddOrkeonXxx()produces a graph that is resolvable on its own (with logging and, where applicable, anIConfiguration); - that the opt-ins compose with the core (
TryAddsemantics, no duplicates).
Run history: Orkeon:RunHistory
- Shipped binaries:
orkeon run,orkeon-hostandorkeon runsreadOrkeon:RunHistory. It is off in the library and inorkeon run, on inorkeon-hostand in the settingsorkeon initwrites.Enabled=truekeeps the events of every run after it ended, withStorejsonl(default) orsqlite, under./.orkeon/runsmounted at/runsas an internal mount;orkeon runs list|show|tailreads them back. A run is recorded with or without--events(without it, nothing is written to stdout).orkeon-repldoes not publish run events. What is stored, and masked, is inorkeon runs; theorkeon inittemplate turns the history on and adds.orkeon/to the.gitignoreof the current folder. - A host written in C# gets the history from
RunnerHost(Orkeon:RunHistory:Enabled, orRunHistoryByDefaultof itsRunnerMountPlan), or writes to the publicSqliteRunEventSink(experimentalORKEXP007, see experimental APIs) and reads back throughIRunHistoryReader;RunEventPublisherandJsonLinesFileRunEventSinkare internal.