Table of Contents

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

See also: Back to index

Known limitations and constraints

  • InMemoryUnitOfWork has, by design, no durable persistence step: aggregates live in the in-memory repositories and SaveChangesAsync boils down to the (real and ordered) dispatch of domain events. A durable adapter would replace this adapter as a whole; the code carries no EF migration.
  • Execution state persistence: by default, crew execution states (ICrewExecutionStateManager) are in-memory only (no recovery after a crash). Durable persistence is opt-in: choose a checkpointing state store β€” the Orkeon:Checkpointing section (Enabled, Store json, sqlite or postgres), read by orkeon run and orkeon-host, or AddOrkeonCheckpointing(configuration) / AddOrkeonSqliteCheckpointing / AddOrkeonPostgresCheckpointing in a host written in C# β€” and enable AddCrewExecutionStatePersistence(...) (or the Orkeon:ExecutionState:Persistence section). A failed or killed run is resumed with orkeon run --resume <id>|latest at the granularity of the task: every task a run completes is checkpointed as it ends, and a resumed run answers those from the checkpoint without calling the model. The decisions of the manager of a Hierarchical or Autonomous crew are replayed live on a resume (only the tasks are kept: the manager is asked again to assign and review), a decision task (decision:) is asked again in Sequential and Parallel (Graph checkpoints the route a decision took and replays it), and a task still running when the process died runs again from its start. A task edited between the runs (its description or expected output as the run's variables fill them, so a changed --var counts, its agent or its dependencies) is run again, and so is every task that runs after it, since what they would read of its output is stale; the host logs one warning naming it. --resume latest takes the most recent run of the crew that is not completed (a newer completed run does not hide an older failed one); a run still marked Running is not taken over by latest, since the store holds no lease and it may be alive in another process: the refusal names its id, and --resume <id> takes it over. A session waiting for an answer, or marked failed, is refused by latest, and by its id, only when the run history proves its owner alive (recorded as running with a live process on this host, or run on another host); with no history record of it, it is resumed. Without a lease, nothing else stops two processes from resuming the same run by its id at once. A run is resumable from the place it was started from: moving or renaming the checkout (or the crew file) changes the crew key and orphans its earlier runs. Two limits of the run identity: the A2A task id and the API's are not unified with the run id (StateStoreA2ATaskStore stays on its own __a2a__ key and task ids). The crew key of a session is the crew's name, the virtual path of its file and a short digest of that file's full path (two folders both read /crew to the virtual file system), so two crews of one name never share a session. Orkeon:Checkpointing:Store without Enabled: true is ignored and the host says so at its start. Once enabled, states are persisted at every transition and reloaded/reused after a restart β€” see Opt-in subsystems. v1 limits: metadata persisted as invariant strings, ToolsUsed not persisted.
  • The framework targets .NET 10 β€” its version is defined in src/Directory.Build.props. .NET 11 is not a target: ci.yml builds and tests the solution with the 11.x SDK (job build-test-net11) as an early warning, and both dotnet tools (orkeon, orkeon-repl) roll forward to a newer major runtime (RollForward=Major) so a machine with only .NET 11 installed can run them. Moving the target framework, global.json and the container base images to .NET 11 is planned; the CHANGELOG records it when it happens.
  • The functional scope is frozen at 16 LLM providers (fourteen vendors and two aggregators β€” OpenRouter and Mammouth AI, the first motivated exception to the freeze, integrated documentation-first and campaigned on 2026-10-07), 124 built-in tools (the e-mail family is the second motivated exception; Gmail and Hotmail through Graph are campaigned, Outlook over IMAP and SMTP has not been run; the drive family β€” Google Drive and OneDrive β€” is the third, campaigned on personal accounts; the firefox tool is the fourth) and 6 memory stores until real users ask for more: a single maintainer carries the whole surface, and every addition is a permanent cost. No 17th provider: endpoints that speak the OpenAI dialect need no provider (point Llm:BaseUrl at them); tools are written in .ork.ts scripts or plugins. The rule and what remains welcome are in CONTRIBUTING.md.
  • No batch API: the providers' asynchronous batch endpoints (Anthropic Message Batches, OpenAI Batch, and the like) are not driven. A batch answers within hours and takes no interactive tool calling, so it cannot carry the agentic loop (call, tool result, call), and serving it would need a deferred execution mode that does not exist. A run that wants the cheaper batch price has no path to it; a profile's fallback does not use it either.
  • An LLM key is the key, never a secret name. LlmConfig carries the API key itself (LlmConfig.ApiKey); nothing in the framework reads an LLM key from a secret store. A host that keeps its keys in one resolves the key itself and assigns it to ApiKey; the supported paths for supplying it are the settings file (Llm:ApiKey), the environment (ORKEON_Llm__ApiKey), and β€” to keep the key out of the file β€” the variable the file names (Llm:ApiKeyEnvVar, and per profile Llm:Profiles:<name>:ApiKeyEnvVar, read in the process environment and then the Windows user scope; see configuration).
  • LLM streaming is uniform at the framework boundary: all 16 providers inherit the SSE/NDJSON streaming reader from HttpLlmProviderBase (IStreamingLlmProvider). SupportsStreaming is not an unconditional true: it follows whether the provider is actually usable (an API key when the vendor needs one, plus the resource endpoint for Azure), so an unconfigured provider declares false and every caller branching on the capability takes the buffered path β€” which returns the explicit "API key is required" answer β€” instead of an SSE branch that would end without a single chunk. The remaining per-provider exception is Ollama's /api/chat (see the Ollama entry below). A streamed call runs whole under Llm:TimeoutSeconds and, when set, under Llm:StreamIdleSeconds between two chunks; two edges remain: on the headers phase the same timeout runs twice (HttpClient.Timeout and the stream budget, started a moment apart), so an elapsed one may cost one extra connection attempt before the failure is reported; and the text-only streams (GenerateStreamingAsync), which carry no metadata, cannot flag a stream closed without its finish marker after some text β€” they end normally, where the chat stream carries stream_truncated.
  • The mock provider streams in one chunk: Provider: mock (orkeon run --llm-mock) emulates streaming by sending the whole answer as a single content event before the completed response, and declares no native streaming; it matches the last user message of a call, not the whole conversation, and it has no capability flag for native tool calling to declare β€” the framework has none: its tool calls are an OpenAI-shaped response body (choices[0].message.tool_calls), which the host's default tool-calling strategy reads, as it reads Ollama's, and a crew with a real tool runs through it end to end. A host that registers another strategy reads that body with it, and so a mock tool call may not parse there. The folder of its responses file is an internal mount: it may hold neither the crew nor the script.
  • A cassette freezes the model's answers, not the run: --llm-record and --llm-replay (guide) file each call under a hash of the profile, the messages, the system message, the tools and the tool mode, the response format and the grammar, so any change of a prompt, a tool or the format is a replay miss (ReplayMissException, never a network call) until the cassette is recorded again. Tools run again on a replay, and embeddings and memory are not recorded. The key also holds the model and the sampling options (temperature, top-p, seed, penalties, stop sequences, max tokens, thinking), so changing one is a miss too. A cassette is redacted only for the configured key and the listed patterns (in a streamed call, over the deltas joined, so a secret cut between two deltas is masked too), and the key is computed over the redacted form; a secret that matches no pattern is neither masked nor mirrored in the key: check a cassette before committing it. Two agents asking the same key at the same moment take the recorded answers in the order they ask, so a run whose identical parallel calls differ in order may swap them.
  • The token meter counts generation calls β€” every one, and only those. cost.updated and run.finished sum the calls of a run through the one metering decorator every provider is wrapped in: agent turns and their retries, the hierarchical manager, the planner, the RAG pipelines, the memory services, LLM judges and ctx.llm.* calls. Embedding calls are not counted β€” the vectors of RAG ingestion and retrieval, of semantic_search, of RaggableTree indexing and of a crew's memory (what it stores and what it recalls) come from the embedding ports, which the ↑/↓ figure does not see. Two consequences of where the meter sits: a provider a host registers by hand is metered only through AddOrkeonLlmProvider or AddOrkeonLlmProfile, or handed to a crew's manager with CrewBuilder.WithManagerLlm or to its planner with CrewBuilder.WithPlanningLlm (an IChatClient that is not built on an Orkeon ILlmProvider is not metered at all), and a text-only stream, which carries no usage, is counted at its end as an estimate β€” reported under estimatedTokens, never priced.
  • A2A in the shipped binaries: orkeon-host serves the crews Orkeon:Host:A2A exposes β€” one skill per crew, a task being a run of that crew through the runner a chat message goes through (its mounts, its concurrency bound, the host's deadline), the start refused when the listener would reach beyond the loopback without authentication β€” see Service host; it keeps no task records (GET /a2a/tasks/{id} answers 501). The run API and the health probes are a separate listener, off unless Orkeon:Host:Api:Enabled β€” see the host API: POST /runs/{id}/input answers a run's pending human-input question (200 delivered to a held run, 202 recorded for a suspended one), and its idempotency keys survive a restart only through the run history. orkeon run and the REPL serve no A2A: a single run has nothing to listen for. orkeon-host also connects the MCP:Servers at startup, like orkeon run and orkeon-repl β€” see MCP integration. A C# host that calls AddOrkeonA2A gets a server started with the generic host (EnableServer) whose router runs the agent a task names β€” see A2A conformance.
  • Deliberately-minimal DI defaults β€” IKnowledgeStore (in-memory, non-persistent; its SearchAsync ignores the query) and IAgentExecutionService are stand-ins that each announce themselves with a one-time Warning naming the remediation; nothing calls an LLM or persists implicitly. Full inventory and replacement gestures: Default behaviors
  • Custom tools must implement IBaseTool or inherit from ToolBase<TReq,TRes>. Runtime plugin loading exists (opt-in AddOrkeonPlugins(...) β€” a plugin.json manifest per plugin folder, isolated collectible AssemblyLoadContexts, see Plugins); v1 limits: loaded assemblies run with full trust (no sandbox), and there is no hot-reload
  • Several subsystems (A2A, monitoring backend, NIST, DLP, tool rate-limiting, key rotation, benchmarking, multi-modal validation, kickoff hooks, the RAG subsystem β€” AddOrkeonRag + AddOrkeonRagTools, plus the opt-in AddOrkeonOnnxReranker; the web-fallback transport is wired by AddOrkeonRag itself and governed by configuration) are opt-in: AddOrkeonInfrastructure()/AddOrkeonApplication() do not register them, and each is enabled through its dedicated extension β€” see Opt-in subsystems.
  • A2A β€” task persistence is opt-in: register a checkpointing state store plus AddOrkeonA2ATaskPersistence(), and GET /a2a/tasks/{id} answers 200 with the recorded lifecycle (404 for unknown ids) while DELETE interrupts a task the agent is still working on (it ends Cancelled), answers 409 for a finished one and 404 for unknown ids. Without the opt-in, GET keeps returning an explicit 501 rather than fabricating state. The broader v1.0 spec gaps (bindings, push notifications, 9-state lifecycle, A2A-Version) are inventoried in the A2A conformance matrix.
  • A2A mTLS β€” A2AClient loads the client certificate (A2ASecurityOptions.ClientCertificatePath) and always applies full server-certificate validation β€” there is deliberately no accept-any-certificate opt-out; a self-signed or local-dev server pins its CA via TrustedCertificateAuthorities. Server side, when RequireMutualTls = true, A2AServer only accepts client certificates that chain to one of the TrustedCertificateAuthorities or match a pinned TrustedClientCertificateThumbprints entry (403 otherwise) and refuses to start when no trust anchor is configured (fail-closed). Certificate revocation is not checked (private CAs without CRL/OCSP endpoints are assumed). Client-side CA pinning only vouches for an unknown chain β€” a host-name mismatch is never bypassed. When AllowedAuthSchemes is set, a request is accepted only with a credential its scheme's validator accepts (401 otherwise): a Bearer token validated by a registered IAuthenticationProvider (A2A:Security:AzureAD / A2A:Security:Oidc), an ApiKey matching a secret named in ApiKeySecretNames; the server refuses to start when a declared scheme has no validator. A2AClient sends Authorization: <ClientAuthScheme> <secret> when ClientAuthScheme and ClientCredentialSecretName are set, the secret read through ISecretProvider on every call. Real mutual TLS termination requires an HTTPS binding of HttpListener (HTTP.sys reservation / server certificate) configured at the host level; the discovery endpoint /.well-known/agent.json remains public.
  • Semantic agent selection (OrkeonApplicationOptions.AgentSelectionStrategy = Embedding) inherits the real embedding resolution chain: the default IEmbeddingService adapts the IEmbeddingProvider port (local BGE when AddOrkeonLocalEmbeddings() is registered β†’ remote provider from Orkeon:Embeddings β†’ fail-fast InvalidOperationException at first use with an actionable message). There is no silent non-semantic fallback: without any embedding provider the Embedding strategy fails loudly β€” either configure one, or prefer the Skill strategy (lexical matching, no dependency) or the FirstFit default (first available agent).
  • The RAG path does not degrade silently β€” the ingestion pipeline (Orkeon.Rag) embeds chunks at ingestion and the document store searches by scored vector similarity (similarity scores survive end-to-end to ScoredChunk), and the IEmbeddingProvider port resolves as local BGE provider (when AddOrkeonLocalEmbeddings() is registered) β†’ remote provider from Orkeon:Embeddings β†’ fail-fast (InvalidOperationException on first use with an actionable message). HashBasedEmbeddingProvider is a test double only β€” it is never resolved implicitly.
  • Native tool calling β€” Ollama: OllamaLlmProvider reaches /api/chat β€” and is wired with the native OpenAI strategy β€” whenever the conversation declares tools, replays tool calls, or carries a non-text part (an audio or file part is then refused with NotSupportedException, as on Anthropic, and on OpenAI for a model without audio input). It reshapes Ollama's response (message.tool_calls with arguments as a JSON object, no choices array) into the OpenAI body the framework's single parser reads (choices[0].message.tool_calls, arguments as a JSON string), and assigns positional call ids since Ollama issues none. Remaining limits: everything else β€” plain conversations, single-prompt generation β€” still uses /api/generate, so the text fallback protocol stays in charge for models without tool support (a streamed call takes the same endpoint the buffered one would); and images must be supplied as bytes, since Ollama takes bare base64 payloads and never fetches a remote URL.
  • RAG adaptive/corrective profiles β€” the LLM-dependent nodes degrade offline: the Adaptive-RAG Iterative route delegates to the corrective graph pipeline (the route step traces delegate=corrective and RagTrace.Route carries the decision). Remaining honest limits: the default complexity classifier is the deterministic heuristic; the llm classifier requires a registered IChatClient (without one it falls back to the heuristic with a warning); and without a real LLM the corrective graph cannot bridge a vocabulary gap β€” in --offline evaluation the extractive stub feeds rewrite_query/evaluate/check_groundedness: the grader's tolerant parser fishes grade words out of the echoed passages (deterministic verdicts driven by the one grade word the golden corpus happens to contain; the groundedness fallback stays safely grounded), and a triggered rewrite degenerates to the stub's fixed prefix β€” one meaningless probe shared by every case β€” so the offline corrective numbers measure the loop's guard rails plus that degradation, not rewrite quality, and can land below quality (measured table and analysis in examples/rag/eval/README.md; the end-to-end mechanism β€” evaluator verdict β†’ rewrite β†’ recovered citation on the seeded q-007 case β€” is proven by CorrectiveRagMechanismSlowTests with a scripted LLM, labelled as such). The same offline note holds for the LLM-backed query transformers (multi-query/rag-fusion/hyde): the measured offline path is QueryTransform.Mode=none + heuristic routing.
  • RAG profiles balanced/quality/adaptive require the ONNX reranker packages: their presets enable the cross-encoder rerank stage. The three shipped binaries β€” orkeon, orkeon-host and orkeon-repl β€” register it. A C# host of its own that does not reference Orkeon.Rag.Onnx + Orkeon.Rag.Onnx.Model and call AddOrkeonOnnxReranker() refuses to start under those profiles, naming onnx and the rerankers it knows. fast (the default) and corrective (the graph corrects by looping, no linear rerank stage) work without the ONNX packages. adaptive needs them because its SingleShot route delegates to balanced.
  • ONNX native runtime β€” the suites that load it: two test suites load the ONNX Runtime native library β€” tests/tools/Orkeon.Tools.Embeddings.Local.Tests (local BGE-micro-v2 embeddings) and tests/rag/Orkeon.Rag.Onnx.Tests (ms-marco cross-encoder reranker) β€” so they need a platform where that library loads; both run as plain dotnet test steps in CI and inside a container. A disposed LocalEmbeddingProvider throws ObjectDisposedException from EmbedBatchAsync and Dimensions.
  • The local embedding model reads English. BGE-micro-v2 β€” the on-device model of Orkeon.Tools.Embeddings.Local, behind local semantic search, RAG retrieval with local embeddings, semantic agent selection and orkeon usecases search β€” was trained on English. Its WordPiece vocabulary (30,522 tokens) holds no accented letter and 244 Chinese characters: "matin", "chaque" or "rΓ©sumΓ©" reach it cut into fragments, while "morning" and "report" are whole words. A French, Spanish, German or Chinese text still gets a vector, but one much closer to noise than to meaning, so expect semantic search, and retrieval or agent selection by embeddings, to be markedly weaker outside English. orkeon usecases search is built around it: BM25 carries the five languages, the sheets are embedded from their English text, and meaning is fused in only for the languages where its golden set measured a gain (CLI reference). For semantic search in other languages, configure a multilingual remote embedding provider (Orkeon:Embeddings).
  • Embedding providers: five, and a changed model is refused where a mount holds the fingerprint β€” Orkeon:Embeddings:Provider takes openai (any M.E.AI generator), ollama, mistral, azure-openai and gemini (providers). Cohere, Voyage and pgvector are not shipped. Vectors depend on the model that made them. Where a mount covers Orkeon:Embeddings:FingerprintPath, the host compares the provider, model and dimensions with the fingerprint recorded there at start and refuses to start when they differ: nothing is migrated, you re-embed and clear the stored vectors, then delete the fingerprint file. The guard sees the embedding settings, not the vector stores: a store that was filled by another host, or by code that built its own provider, is not checked. A host with an embedding provider is guarded with or without an Orkeon:Embeddings section, so a host that embedded under the on-device default and then names another provider is refused (a host with no embedding provider writes nothing). It does not guard everywhere: orkeon forge records its fingerprint per session under /forge, so it guards nothing across sessions; orkeon rag uses no host fingerprint, and the manifest of each collection refuses a model change on ingest without --reindex, on search, on eval rag --no-ingest -c and on eval rag -c with its ingest pre-pass and no --reindex (orkeon rag ingest --reindex rebuilds the collection); a host whose FingerprintPath lies under no mount (no /workspace) skips the guard at Debug; on a mount with no Write or Create on the file and no Create on its folder an existing fingerprint is still checked and a changed model still refused, a missing one is not recorded (Debug, no Warning); an empty FingerprintPath turns the guard off, with no log. The default MinScore (0.6) was measured on the local model only; no remote embedding model has a measure yet.
  • Orkeon.Tools.Embeddings.Local rests on a pre-release of an archived upstream β€” the local on-device embeddings opt-in is built on SmartComponents.LocalEmbeddings 0.1.0-preview10148 (pinned in Directory.Packages.props), which is the only version that exists: upstream has never cut a stable release, and the repository the package's projectUrl points at (dotnet-smartcomponents/smartcomponents) is archived β€” the code moved to dotnet/smartcomponents, which still ships no 1.0. Waiting for a stable upstream is not a plan. The licence side is settled and documented (MIT for both the wrapper and the bundled BGE-micro-v2 weights, provenance established by hand in THIRD-PARTY-NOTICES.md sections 1-2); what remains is a packaging constraint: NuGet refuses to pack a stable package that depends on a pre-release (NU5104). So a stable release of Orkeon cannot carry this dependency inside its main package β€” which is precisely why this opt-in ships as its own Orkeon.Tools.Embeddings.Local package instead of being folded into the Orkeon umbrella. The consequence for a consumer: referencing this opt-in pulls a prerelease dependency into your own graph, and if you then publish a stable package of your own that depends on it, you hit NU5104 in turn. Escape hatches, cheapest first: (a) do not reference the opt-in β€” the IEmbeddingProvider port then resolves a remote provider from Orkeon:Embeddings (see the semantic agent-selection entry above); (b) implement IEmbeddingProvider over your own embedding stack; (c) vendor the upstream inference wrapper (MIT, so this is allowed) into an assembly you control and drop the package reference. The orkeon / orkeon-repl dotnet tools and the installers are not affected by NU5104 β€” a tool package is self-contained and its own version is what NuGet checks. They do carry the BGE-micro-v2 weights (about 17 MB, under LocalEmbeddingsModel/), redistributed under MIT with the notices of THIRD-PARTY-NOTICES.md; the Orkeon.Tools.Embeddings.Local package itself strips them, since its consumer gets them another way. The SmartComponents.LocalEmbeddings package (~40 KB) carries no weights: its build/ target downloads model.onnx and vocab.txt from huggingface.co on the first build of a project that references Orkeon.Tools.Embeddings.Local or Orkeon.Scripting (both let that target flow) and copies them to LocalEmbeddingsModel/default/ in its output. An offline first build fails in the upstream DownloadFile task; later builds reuse the copy cached next to the package. To skip the download, put ExcludeAssets="build" on every PackageReference that reaches the package, Orkeon.Scripting and Orkeon.Tools.Embeddings.Local alike: NuGet unions the flags, so one reference without it keeps the download. The project then builds offline, without the model. The local embedder is built at the first embedding, not at start, so a host built that way starts, and its first local embedding fails with an InvalidOperationException that names LocalEmbeddingsModel/default/model.onnx and the exclusion, and every reference that can carry it (Orkeon.Scripting, Orkeon.Tools.Embeddings.Local, SmartComponents.LocalEmbeddings); a host that embeds through a remote provider never reaches it. The pre-release is assumed, not vendored. A stable Orkeon.Tools.Embeddings.Local depends on SmartComponents.LocalEmbeddings 0.1.0-preview10148; NU5104 is silenced in that one packaging project (the umbrella, Orkeon.Tools and the CLI never declare the dependency), a stable pack of the whole line succeeds, and the README says in one line which opt-in stays on a pre-release and why. Vendoring the inference wrapper (escape hatch (c)) remains possible for a consumer who needs a fully stable graph; it is not worth a second copy of an MIT wrapper for the framework itself.
  • RAG web fallback is double opt-in and off by default: the corrective graph's web_fallback node runs only when both switches are enabled β€” Orkeon:Rag:Corrective:WebFallback (policy: may the graph leave the local store) and Orkeon:Rag:WebFallback (transport: SearxNG endpoint β€” AddOrkeonRag wires the transport, whose corrective-graph adapter IWebDocumentRetriever is registered only when enabled with a non-empty endpoint). Every fetched page is screened by PromptInjectionDocumentValidator before entering the working set (Rejected pages never enter; Suspicious follows the configured policy) β€” see Security
  • E-mail tools β€” protocol limits (Orkeon.Tools.Email, see the guide): Gmail was campaigned against a real account on 2026-10-04 (app password) and 2026-10-05 (OAuth2) β€” what it established; Hotmail through Microsoft Graph on 2026-10-12. Outlook over IMAP and SMTP has not been run against a real account. A search page holds about ten messages whatever limit asks, being cut to a tool result: only a null next_cursor ends a folder. No tool returns a message's Gmail labels. POP3 reads the inbox only β€” no folders, marks, drafts or trash; a delete is permanent and needs the Purge right; a search filters on sender, the To header, subject and dates, over at most 200 messages per call. Microsoft Graph accepts 4 MB per request, about 3 MB of attachments (no upload session), and a text search goes through KQL with the marks and dates applied client-side, so a page may hold fewer messages than asked. On a custom IMAP server raw_query is refused (it needs Gmail or Graph), and without UIDPLUS a moved message or a saved draft comes back without its new id. Outlook over IMAP inherits Microsoft's consumer OAuth regression of 2026-09-24, which is why Graph is the default. Send:MaxPerHour is counted per process, a refused attempt included. The prompt-injection screen sees hidden content through a short list of inline declarations (display:none, visibility:hidden, opacity:0, font-size:0, max-height:0, width:0, height:0, mso-hide:all) and the hidden attribute only β€” text hidden by a CSS class in a <style> block, a 1-pixel font or white on white is neither left out nor flagged, and a plain-text part, which the agent reads when there is one, is not compared with the HTML; a body nesting elements more than 5000 levels deep is replaced by a one-line notice. OAuth token files are plain JSON β€” shielded from the VFS tools, not from a shell or code tool running as the same operating-system user β€” and orkeon-repl keeps no token store, so OAuth accounts work under the orkeon CLI and the orkeon-host daemon only. Not in this version: deleting folders, copying a message or giving it several Gmail labels, interactive approval of a send (email_draft is the review path).
  • Drive tools β€” scope and provider limits (Orkeon.Tools.Drive, see the guide): the campaign against a real Google Drive and OneDrive was closed on 2026-11-17. Its recorded pass, on 2026-10-24, ran on one personal Google account and one personal Microsoft account and led to the drive_search fixes; a work or school OneDrive account was not run, and no campaign report is written. An account sees its own "My Drive" or OneDrive only: Google shared drives and SharePoint libraries are not reached. A search on Google Drive cannot be bounded to a subtree, so its results outside the account's Root are dropped and a page may hold fewer items than limit; on OneDrive a search takes words only (text or name_contains), the other criteria being applied to what it returns, and raw_query is refused. An account on the consumers tenant (personal Microsoft accounts) deletes nothing for good on OneDrive. Google documents are read through their text export (plain text, or CSV for a sheet β€” its first sheet) and downloaded by export; drive_read fetches at most 2 MB, a larger or binary file going through drive_download and the file tools. The root check climbs 32 parent levels at most. Uploads stop at MaxUploadMegabytes (100 by default), sent in a resumable session to Google (in 8 MiB chunks above 8 MiB) and in 10 MiB chunks to OneDrive above 4 MiB. Token files are plain JSON β€” shielded from the VFS tools, not from a shell or code tool running as the same user β€” and orkeon-repl keeps no token store, so drive accounts work under the orkeon CLI and the orkeon-host daemon only. One credentials directory per run: when Orkeon:Tools:Email:CredentialsDirectory and Orkeon:Tools:Drive:CredentialsDirectory differ, the e-mail one is used. Not in this version: copying, revisions, comments, removing a share, a trial drive for the forge, a drive mounted in the VFS.
  • MCP β€” dual-era client/server: the client probes with server/discover and speaks the modern stateless revision (2026-07-28 β€” per-request _meta, version renegotiation on UnsupportedProtocolVersionError) or falls back to the legacy initialize handshake (2025-11-25, 2025-06-18, 2024-11-05; 2025-03-26 is deliberately excluded β€” it is the only revision mandating JSON-RPC batching, which this implementation does not speak); the server serves both eras concurrently β€” over stdio only, started by orkeon mcp serve (no HTTP transport for the server), each tools/call through the guarded invocation point of the agent turns, requests running at once up to --max-concurrency (4) and cancellable with notifications/cancelled, and /output served as read-only resources under --expose-output (no resources/subscribe, /workspace never), and prompts only for the tasks of the crews named by --crew. Honest gaps of the modern surface: subscriptions/listen over HTTP only (stdio notifications are heard on their own, and tools/list_changed re-synchronises the registered tools), crews served as tools (orkeon mcp serve --crew: run_crew_<name>, progress per task, tasks as prompts) recorded in the run history when it is on, but no sampling, roots or elicitation (a server request for them is answered -32601: sampling would call an LLM outside the run's budget, guard and cost, roots would expose physical paths, elicitation waits for durable human-in-the-loop), no multi-round-trip requests (an input_required result surfaces as a tool error), an OAuth client for the server (client credentials, device flow: Auth:Type oauth2-client-credentials or oauth2-device) but no authorization-code flow, no protected-resource discovery (RFC 9728) and no dynamic client registration (DCR), and the device flow is refused in orkeon-host (no terminal) β€” a server behind a static credential is reached through MCP:Servers:<id>:Auth (bearer or basic, read from the environment) and Headers; the HTTP transport is Streamable HTTP (session id, 404 re-initialisation, SSE answers read event by event, the GET stream with Last-Event-ID; the 2024-11-05 HTTP+SSE transport with a separate endpoint is not supported). Client side, a remote tool's schema is kept whole at any depth (properties, items, bounds, anyOf / oneOf, additionalProperties, an allOf of objects merged, local $ref resolved, the root read like any schema); it still loses, among others, an allOf with a member that is no object, not, if / then / else, patternProperties, uniqueItems, multipleOf, dependentRequired, additionalItems, title, minProperties / maxProperties, propertyNames, contains, an enum member that is null or no scalar, the position of a tuple's items (read as their alternatives), an anchor, a reference to another document and a reference cut at a cycle (any JSON value), what lies more than 32 levels deep, and at the root an additionalProperties other than false (the MCP integration lists what is kept); a tool whose inputSchema expands to more than 4096 schemas, or copies more than 1 MiB of text, each use of a $ref counted (a definition used many times counts each time), is set aside with a warning written once per distinct tool definition; a type array that names only "null", or no type, is read as no type ("type": "null" stays null), an integer no 64-bit integer holds is read as a double, and an array whose items are not known - no items, items with no single type - is shown with items: {}, any JSON value; tools/list, prompts/list and resources/list are read entry by entry: a tool, a prompt or a resource that cannot be read is set aside alone with a warning; a tools/list answer of the wrong shape (a tools that is neither null nor an array, a nextCursor that is no string) still fails the listing, and so the connection, with a message that names the server, where a prompts/list or resources/list of the wrong shape lists what could be read. Server side, a C# host that deserializes a message itself and hands it to ProcessRequestAsync loses a null id (the message is taken for a notification and gets no answer, where the stdio loop of orkeon mcp serve answers -32600) and an absent jsonrpc (it defaults to "2.0", so the message is obeyed where the loop refuses it), and a response it hands over is answered -32600 where the loop drops it. Interop against the reference server (server-everything) runs nightly, and by hand with the MCP Inspector β€” MCP interop.
  • LanceDB β€” LanceDbMemoryProvider targets a remote LanceDB Cloud/Enterprise server (Lance REST Namespace protocol, Arrow IPC payloads); there is no local store. Remote API limits (details in Memory system): SearchAsync requires an FTS index on content (created automatically at table creation, otherwise the server error is propagated β€” never simulated locally); HybridSearchAsync issues two server requests (_distance/_score rankings server-side) and merges the two ranked lists locally, like the official SDKs' rerankers; since the delete API does not return a counter, DeleteAsync/UpdateAsync perform a prior existence request to preserve their boolean contract; the score conversion = 1 βˆ’ _distance is only meaningful for the cosine metric (default)
  • The Guardian's detection is heuristic β€” the input phase and the tool-result sanitizer match phrasings (ignore previous instructions, chat-template tokens, …): a rephrased attack passes, and an honest prompt can match β€” under the default Security:Prompt:Policy = Block it then fails its task with the pattern named (Warn lets it through with a warning). Tool results are tagged as data, never cleaned. Only hosts that compose AddOrkeonApplication() with AddOrkeonInfrastructure() get the guardian; an ExecutionOrchestrator built by hand runs unguarded unless its Guardian and ToolInvocation are set. See Security.
  • Decision models: one judge per phase β€” TypeSafe, Liquid and Kev are Decision providers behind IDecisionModel, not 17th LLM providers: an agent cannot take one as its llm. The LLM judge of the guardian (Orkeon:Guardian:Llm, off by default) judges agent input and a task's output through the one IDecisionModel, with no profile of its own, and adds a model call per phase, delays a task's streaming until its output is judged, judges a long text whole in chunks of MaxContentChars overlapping by a quarter under FailMode: Closed (32 chunks at most, then the text is refused) but only the first and last half of MaxContentChars under Open (the middle is not judged), and covers crew tasks only (a scripted ctx.llm.act answer is not judged); a response inside a call is judged by a response stage of a decision profile (Orkeon:Decision:Profiles). The request stages ask about the last user message only, a re-call after the response happens once per call, and neither the stages nor the decision reranker set LongContext: a long state or many passages may exceed the provider's per-request context and fail with its limit error, a 400 max_tokens_exceeded (Decision models). Kev's extra operations (permute, separate, model list) are not wired. No cost is computed for a decision, only its usage tokens. The open d1 weights are not served by Orkeon: Liquid is reached through its hosted API.
  • A crew's memory keeps everything, recalls by vector unless the cognitive memory is enabled, and persists only in a durable store β€” with memory: true, a crew stores the result of each task that succeeds and recalls the closest ones before each task (Memory system). What it does not do: there is no retention and no reset β€” the memory grows by one entry per successful task, run after run, and IMemoryService.ClearMemoryAsync clears only the current run's entries; on In-Memory it lives in RAM for the life of the process, so orkeon run remembers across processes only with a durable store (memoryProvider: sqlite, a vector database, or a durable Memory:Provider); the recall is a vector search, with no LLM fact extraction and no recency or importance score (CrewAI's) β€” unless Orkeon:CognitiveMemory:Enabled is true, which recalls by composite score and analyses what is stored at an LLM cost (Memory system); MinScore (0.6) is on the local English model's scale, where French text scores high whatever it says, and a long input variable that shares a memory's subject can lift an unrelated task over it.
  • A crew's plan is advice, made on the default profile β€” with planning: true, a planner writes a step-by-step plan for each task before the first one, and each task reads its own plan in its prompt, in all six modes; the plan changes neither the order nor the agents (Process types). What it does not do: it plans on the crew's planning provider (C# WithPlanningLlm) or on the host's default profile β€” a YAML or .ork.ts crew cannot name another; it shows the planner neither the agents' backstories nor their knowledge nor the crew's memory, and cuts what it shows (PlanningDefaults); a reply it cannot read twice leaves the crew without a plan β€” a warning, not a failure; and on the echo provider (no Llm section) it skips the plan, with a warning.
  • spawn_agent β€” the script host offers it, the C# tool is host-registered β€” a script's act is offered spawn_agent (SpawnAgentScriptTool): it runs a named crew agent as a child under the delegation-depth and spawn budgets of the crew run (see Scripting). The C# SpawnAgentTool (budget-controlled self-spawn of the autonomous mode, in Orkeon.Infrastructure) is a different class and stays host-registered: no shipped composition root β€” neither orkeon run nor the REPL β€” puts it in the tool registry, and a C# host that wants self-spawn registers it explicitly with an IAgentFactory. See docs/tools/inventory.md and docs/orchestration/autonomous.md.
  • Per-execution mount namespaces are entered by orkeon-host and the forge's trial only β€” IFileSystemScope / AsyncLocalFileSystemScope (Domain) hand one execution flow its own FileSystemRegistry, and FileSystemService consults that ambient override on every operation, so two crews running in the same process can each address their own /output over different physical folders β€” the registry's duplicate-virtual-path rejection is per instance, never global. orkeon-host enters a namespace per hosted crew, from Orkeon:Host:Crews:*:Mounts (CrewRunner), and the forge's trial enters one made of the folders its session confirmed (ForgeTrialScope). Every other entry point β€” orkeon run, the rest of orkeon forge, orkeon rag, orkeon-repl β€” runs against the boot registry, one flat mount set per process whose virtual paths must be globally unique, which is why they reserve their roots against the settings β€” the file and the environment β€” rather than scoping them, and why the host still renames the crews it grants no mounts to (/crews, /crews-1, …). A host that wants its own namespace composes it with ScopedMountComposition.ForExecution: entering a scope replaces the boot set rather than merging with it, so the composition carries the boot mounts forward and lets the execution's own mounts shadow them at the paths they claim β€” dropping them takes /llm-logs and /sandbox down with the run, and takes the root the runner loads the crew from. A folder granted to a crew is an entry of the daemon, readable wherever it lies, without --allow-external-mounts. The forge's folders are inputs too: forge resume builds its host with the confirmed folders mounted and allowed, and a run about to try the team in its own process refuses, at folders.confirmed, an input bound to a directory its validator does not allow (FORGE-FOLDERS-INVALID). See VFS compliance.
  • A tool-call approval in orkeon-repl is read between two commands, or by a waiting runCrew β€” the question a crew asks waits for the read loop, which reads only when no command runs in the foreground, or for a command waiting in runCrew (synchronous), which reads the answer itself. Any other command that holds the loop leaves the question waiting until it ends. A command's ctx.prompt reading while a question waits takes the operator's line in its place. In the plain console on a terminal, a question written while a line is being edited moves the editor's anchor, as a ticket's completion line already does. The pause of the script's clock while the gate decides holds for the whole engine: every agent of the crew, every run sharing a command file's engine. The REPL registers its approval channel directly (CompositeLineInterceptor), without the SerializingToolApprovalChannel decorator the other hosts get: should two read-class calls of one turn (which run concurrently) both ask, their questions are not queued one at a time. An act in ask mode with no permission gate fails closed (the call is denied). During a replay (orkeon-repl --replay, /replay), the next line of the file answers a question the moment it waits: a line written for the next command answers an approval the replay did not expect; one line answers one approval, but a session-wide answer (s) also settles every queued approval of the same tool, so the file must carry no line for those; and an approval still waiting when the file ends stops the replay (replay ended with an approval waiting: <tool>, exit code 1). A background instance launched by a completed() callback is charged to the replay line in flight when it starts, not to the line that launched its parent. A human_input question raises no signal: the replay sees it within a quarter of a second, by looking again.
  • No shipped host activates an agent on the scripted-command dispatch bus β€” an agent declares .onCommand(...) handlers and a .cmd.ts command reaches it with commands.request / commands.post, but nothing connects the two: orkeon-repl loads *.cmd.ts files only and registers no agent, and the registrar that does it is internal. Until a host registers one, request and post throw commands: unknown agent '<name>'. Registered: (none). β€” see Scripted CLI commands.
  • A tool call of a crew agent that the permission gate asks about is refused when the host has no approval channel β€” the gate is consulted by ToolInvocationPipeline for scripts and YAML crews alike (permissionMode: of an agent, else Orkeon:Security:PermissionGate:DefaultMode); an ask goes to the host's IToolApprovalChannel, and with none (the Discord bot) the call is denied and the model reads the reason. With Orkeon:Checkpointing:Enabled the question is durable: the daemon and orkeon run persist it and stop the run on it (waiting_for_input, exit 75) instead of refusing; the Discord bot keeps no path to answer one (a forge session in pause is not a run: it stays at 0).
  • The daemon does not resume a suspended run by itself β€” a run whose human-input question outlived Orkeon:HumanInput:HoldTimeout (or Pause: Suspend) ends waiting_for_input; POST /runs/{id}/input records the answer and orkeon run <crew> --resume <id> resumes it. Each question a parallel task asks is persisted under its own id; the run stops on one of them (the one its exit and pending_input show), the others are answered by their request_id, and one left unanswered is asked again when the run resumes. A question is replayed at the grain of the task: the task that asked runs again from its start (its tool calls are made again), and the Hierarchical and Autonomous managers' own decisions are not checkpointed.
  • The answer to a human-input question is stored in plaintext β€” the checkpoint session keeps the answers (SessionState.AnsweredInputs) as they were given, because the resumed task needs them: a store on disk (json, sqlite) or in Postgres holds them readable, as it holds the task outputs. What is printed or read back of a question - the prompt on the orkeon run stderr line and in GET /runs/{id} - goes through the masking of the run history (RedactingRunEventSink.Redact); the stored prompt is not masked. An answer given without a request id (--resume <id> --input "...", or a POST /runs/{id}/input with no request_id) goes to the question the run stopped on; with several open and none of them the one it stopped on, it is refused (409 request_id_required). A stored tool approval is reused on a resume only for the same tool and the same arguments: another call is asked again.
  • shell_command's confinement: what each backend holds, and where it is checked β€” the process is confined by default (Shell confinement): bubblewrap on Linux, Seatbelt on macOS, an AppContainer inside a Job Object on Windows 10 and later; inside a container, or with Mode = None, it runs on the host as the host's user and the VFS checks only the paths its command line names. Where it is checked: the pure parts (the bwrap arguments, the Seatbelt profile, the ACL plan, the Windows command lines, the shell protocol, the choice of Auto) are unit tests every CI run executes on Linux; a real bwrap, a real sandbox-exec and a real AppContainer run only in the nightly integration.yml jobs (ubuntu-latest, macos-latest, windows-latest), which fail rather than skip when the backend cannot confine; only the Linux job opens the nightly tracking issue, a red macOS or Windows job shows on the workflow alone. What a view does not carry: a sub-path override on a path that does not exist when the session starts (a writable parent lets the process create it; bubblewrap and AppContainer), an internal mount whose folder lies inside an agent-facing mount (reachable through that mount), and a program outside the system directories (/opt, a .dotnet or nvm folder under the home on Linux; /opt/homebrew on macOS; anything under the user profile on Windows) until its folder is listed in Confinement:ReadOnlyPaths. An agent root that is a linked git worktree gets the repository's common dir bound read-only and, over it, its objects, refs, logs and the worktree's own git dir read-write: the agent can rewrite every branch's refs and the shared objects, but not the common dir's config, hooks, info, modules or the other worktrees' git dirs, nor any working tree outside its root; a repository without logs/ cannot record reflogs from the agent; a layout that fails a check (commondir or back-link not naming the expected dirs, a symlink on the path) binds nothing; git run on the host inside the agent's worktree still trusts what the agent wrote there, and git run on the host anywhere in the repository follows a link the agent created inside objects, refs or logs; a gitdir written as a virtual path works under bubblewrap only (Seatbelt and AppContainer show the physical paths). No network unless Confinement:AllowNetwork: a package manager or git fetch fails until then. A timeout returns no partial output on Linux and macOS (the session is killed before the command's output is read back; Windows returns what was captured), and it resets the session: the next command starts in a new one, without what the previous one left in its /tmp. Windows: each session grants its mounts by ACE and takes the grant back at its end, and Windows propagates an inheritable ACE to every object below the mount's root, so a session costs one security-descriptor write per file of its mounts, each way (a node_modules of 100 000 files is 100 000 writes when the session opens and as many when it closes); the DACL is read, changed and written back, which another process changing the same DACL at that moment can undo. A hidden sub path, or a read-only one inside a writable mount, has its DACL protected for the session and written back as it was at the end (the container's access check skips a deny ACE), so a change another tool makes to that DACL meanwhile is lost. cmd's dir, vol, attrib and where /r query the drive's root, which a standard ACL does not open to an AppContainer: they answer "Access is denied." in a confined session. A batch file (.bat, .cmd, hence npm.cmd) is refused in an AppContainer session and runs with Mode = None only, and a program is looked up on PATH only. After a host crash: bubblewrap and the Job Object leave no process (the kernel kills the tree), but the ACEs an AppContainer session granted stay on the mounts until the next host's first session takes them back (they are recorded under %LOCALAPPDATA%\Orkeon\shell-sessions\); under Seatbelt and unconfined on Linux and macOS a watchdog polling every second kills the session's process tree, which a process that left the tree (a double fork) escapes. The scripted runtime ends an agent's scope without awaiting it, so a session's teardown can finish after the agent body returned. On Linux the session's environment keeps the host's PATH, with HOME and TMPDIR on the view's own /tmp; Ubuntu 24.04's AppArmor restriction on user namespaces makes bwrap fail unless a profile grants it userns. The session bus reaches a confined session only with Orkeon:Tools:Shell:Environment:SessionBus = true, which lets a command leave the sandbox (systemd-run --user) and read the keyring; a unix:abstract= bus stays reachable under bubblewrap with AllowNetwork, since an abstract socket follows the shared network namespace. Background jobs: a run holds 16 live jobs at most, a job id is valid only in the run that started it, and the run's end kills the jobs still running.
  • An agent's file-system scope judges virtual paths (agent file-system scope): a symbolic link inside an entry that points elsewhere in the same mount is followed by the VFS tools (the path validator holds links to the mounts, not to the scope); shell_command under bubblewrap binds the entries alone, so the link leads nowhere there. An unconfined shell (Mode = None, or inside a container) holds the scope only for the paths its command line names and its working directory, as it holds the mounts. An rwnd entry withholds Delete, yet a move can still take a file out of it: the VFS asks only Read and Write of a move's source. A mount's sub-path overrides still compare case-sensitively, and the scope folds neither Windows 8.3 short names nor NTFS alternate data streams. In hierarchical mode the workers the manager assigns run as top-level runs under their own scopes: a scope declared on the manager agent does not bound them. Only the agent's tool calls are held: what the framework reads or writes for the run (memory, knowledge, output files) keeps the mounts' rights.
  • Per-tool result cut β€” Orkeon:Tools:ResultLimits (Limits:<tool>, MaxParallelToolCalls, default 4) is bound by AddOrkeonInfrastructure and read by the C# agent loops through ExecutionOrchestrator.ToolLimits. The scripted act reads it too, through ScriptingHostPorts.ToolLimits, which orkeon run, the runner hosts (orkeon-host among them), the REPL's scripting commands and the forge's crew assistant all set; a script host built without that port cuts and fans out with the built-in defaults. The shell's default cut in the pipeline is 10000 characters; a result a tool already bounded (ToolCallResponse.AlreadyBounded) is not cut a second time. The text-fallback loop (LegacyTextAgentLoop) and the dispatcher's text path do not fan out.
  • Agent instances: one memory per agent name β€” the durable ctx.memory.agent store (FileScriptAgentMemoryStore) lives under Orkeon:Scripting:AgentMemory:RootDirectory (default /workspace/.orkeon/agent-memory, see the configuration reference); the key is the agent name, so two agents of that name share it. Without a budget(...), MaxSpawnedAgents counts per agent run, not per crew run.
  • RAG ingestion lock is in-process β€” ingests of one collection are serialised by a per-collection SemaphoreSlim of the process; two processes sharing a persistent store are not coordinated (a cross-process lock needs provider support). Prune removes only the sources of the manifest absent from the requested globs; a failed delete is recorded in the report's errors and keeps its manifest entry. See RAG pipeline.
  • Markdown in the RaggableTree β€” no parse validation β€” Edits to a .md file (node_replace, node_insert, edit_batch, ensure_section, insert_under_heading, replace_mermaid) are not parse-validated: Markdown has no syntax error to refuse. On an unclosed top-level fence, replace_mermaid replaces the body to the end of the file without closing it.
  • Incremental reindex: stated bounds β€” incremental_reindex re-parses the changed files and patches the store per file; calls from unchanged files and Markdown links into a name added or removed by the changed files are relinked without reading the unchanged files. The dirty-set paths do not apply .gitignore. A tests edge to an overloaded member links every overload (the FQN is name-only). See RaggableTree.
  • Dev-workflow queries: stated bounds β€” affected_tests takes project_depends from csproj files only, unions base..HEAD with the working-tree changes (untracked included), and answers all when a project query fills its 1000-row page or an expansion is truncated; symbols below a changed module are read three levels deep. documents_of reads a file's sections through a query capped at 1000 sections by the store. access_cost counts a write behind ConfigureAwait as a read, as access-cost.py does.
  • Intent operations β€” a closed grammar β€” ensure_import does not see a // comment inside multi-line import braces (the next binding is hidden), nor import React, { … } (default plus named). Structural rewrites and edit_batch are best-effort atomic: files are written one by one with a backup or an in-memory original and restored on a failure; if the restore itself fails, the journal is kept and an AggregateException is thrown, and the files already written stay changed until the journal is replayed (structural_rewrite $$ in a pattern stays two dollars, one in a fix).
  • Decision tasks run in three processes only. A task with a decision: block or a when condition is accepted in Sequential, Parallel and Graph; in Hierarchical, Consensual and Autonomous the load is refused (DecisionTaskRules.Check), never ignored, and a crew built in C# that reaches one of them fails before its first task.
  • Decision tasks: what the second iteration leaves out. No decision node before or after a task (a guard on a task's input or final answer), no go-to outcome, loop or decision journal; no retry (a decision task cannot declare retry:, and the graph has no retry loop of its own) and no fallback when a request to the decision model fails (the task fails, the fallback serves an off circuit only); no image and no box question in a crew (the IDecisionModel port takes both, TypeSafe's opt-in "danger zone" features since Jev 1.13 and 1.14, but a crew's decision task sends text only); the decision reranker sends its passages in one request, without batching.
  • A task's retry: replays the whole task, and nothing more. Every mode retries a failed task (retry: {attempts, backoffMs, backoff}), tool calls that already succeeded included: no mechanism deduplicates them, and a task whose tools write must be safe to run twice. A failed attempt's tool calls, memory written by tools, metered cost and events stay, and the task callbacks fire once per attempt. A cancellation, a guardian refusal and an exhausted budget are never retried; a timeout and an exhausted failover chain are. There is no scheduler and no message queue: a retry is immediate (or after its backoff), inside the run.
  • The REPL transcript shows no decision detail for crew tasks. The run's JSONL carries a skipped task's reason and a decision task's answers; the REPL transcript renders no skip reason and no decision label for a crew task.
  • The YAML graph: block runs on the Domain engine only. A graph: outside process: graph is refused at load, and a handoff between agents is not a graph edge. A .ork.ts crew builder has no graph: surface: process("graph") there runs one node per task, and a graph drawn with stateGraph(...) runs on JsStateGraph when the script calls .run().
  • ChatOptionsComposer translates only part of an agent's LlmConfig. It carries over the model, the sampling and penalty fields, the output cap, the seed, the stop sequences, Thinking, the response format and the cache; fields such as TimeoutSeconds, CustomParameters or SystemMessage set on an agent's own LlmConfig are not translated into the chat options (the text-fallback loop honours them).
  • Two spellings of the same API-key variable. Under Linux and macOS, when both ORKEON_Llm__ApiKey and ORKEON_LLM__APIKEY are set with different values, the run takes either one, and the runtime does not arbitrate between them.
  • Windows: a refused connection may come back slowly (unverified). The LLM endpoint probe of a run and that of orkeon doctor give 2 s each and read a timeout as reachable. If the Windows stack retries the SYN after the reset, as expected, the refusal of an unreachable localhost can arrive after the timeout, and the fast failure of orkeon run does not trigger. Not observed on Windows yet.
  • Thinking and effort are judged against a table that is a snapshot. Every provider judges LlmConfig.Thinking against the per-model table (IModelCapabilityRegistry, ORKEXP005): an effort a listed model does not take is lowered, a switch it cannot honour is dropped, each with a warning, and an unlisted model gets the options as asked, with a warning that nothing was checked. The table holds what the vendors documented and the provider campaign measured on the day: a model released or changed since answers with its own error until Llm:ModelCapabilities:<id> declares it. Azure OpenAI is named by deployment, so its deployments are unlisted until declared. A model id containing : (Ollama's llama3:8b) cannot be a key of Llm:ModelCapabilities, since .NET configuration has no escape for :: key its prefix (llama3). Haiku 5.5 above 100K prompt tokens bills more (0.50 / 2.50 $/M); ModelPricingRegistry prices the tier up to 100K only, so a long Haiku 5.5 prompt is underestimated and a budget can be exceeded without an alert.
  • Thinking and effort: what the table leaves unmeasured. Anthropic's "on" sends adaptive to every Claude model, Claude 4.5 and earlier included, where no campaign measured it. The claude-opus-4 entry (low to high) also covers Opus 4.6 and 4.7, and the gpt-5 entry (minimal to high) GPT-5.1 to 5.5, unmeasured. OpenRouter's dotted Claude ids (anthropic/claude-opus-5.5) do not match the dashed entries (claude-opus-5-5) and fall to a shorter one (claude-). An entry that lists no efforts (claude-, gemini-) leaves them unchecked and gives no "nothing was checked" warning, since the model is known. kimi-k3, kimi-k3.1-pro, DeepSeek and the qwen3.8 models have no entry: they take the provider's levels, with that warning. In the OpenAI dialect, "off" and an effort asked together are both written (thinking: {type: disabled} beside reasoning_effort), for the vendor to judge. Azure OpenAI keeps the three default levels, unmeasured. The provider campaign checks the table against what it measures (orkeon llm probe, M15–M17 against M18), but only on the day it runs: a vendor that changes a model's values in between shows up as that model's own error until an entry or Llm:ModelCapabilities:<id> follows.
  • context N% in the split-pane console reads one call against one setting. It follows the latest model call of the prompt's turn, so a task launched in that turn shows its own figure until the main command calls again. It is absent for a crew run synchronously through runCrew, whose calls no command instance is credited with, and its window comes from Orkeon:Cli:Session:ContextWindowTokens alone (200000 when unset), so it does not follow /model.
  • Console palettes are named, not detected. The palette never comes from the terminal, ctx.setTheme lasts for the session, and a selector cannot preview one live: nothing calls a script back from the UI thread.
  • ? alone cannot start a message on an empty prompt of the split-pane console. It lists the keys there; while a script's ctx.prompt reads, it is text.
  • The prompt recalled on a scrolled transcript hides the row under it. Scrolling one row further shows that row.
  • Tool-call deltas stop at the sinks that read them. The reasoning deltas are not forwarded to ILlmDeltaSink, and the mock provider emits no tool-call delta.
  • Streaming in the split-pane console. It is on in the REPL and off for a crew run unless Orkeon:Cli:ConsoleStreaming:Enabled says otherwise, and an intermediate assistant text does not show in a crew that does not stream. The rows of a table stay hidden until the table ends, and a closing fence adds a blank row.
  • Diffs and code in the split-pane console have no syntax colouring, which would need a package.
  • A command's wrapped output starts again at column 0. The next rows of a plain line that wraps do not align under the elbow.
  • Prompts of a split-pane script. A ctx.prompt the script does not await leaves a read open, and the next read of the loop can fail with A ReadLineAsync is already in progress. A line typed at the prompt for an approval, buffered and then withdrawn with its question, can reach the loop as a line of its own (rare).
  • The run history of a hosted run is partial. orkeon-host records run.started, the task events, error and run.finished of each run (Orkeon:RunHistory, on by default there); the tool.*, llm.call.* and cost.updated events are not published for a hosted run, because the tool, usage and call observers are process-wide services and a daemon runs several crews at once: they stay on orkeon run --events. The history of a run keeps no llm.delta unless IncludeDeltas is set. A run whose host cannot be built (a refused setting, an unreadable crew) leaves no history, and neither does --resume latest, whose run the runner names only after looking in the store. The events a run writes before the history can join (run.started and what the host build emits) are kept in a buffer of 128; past it they stay on the stream and are not in the history (a warning says how many). A run killed before run.finished is orphaned only for a reader on the same host: on another host (a shared folder) it stays running, and MaxRuns and the purge keep counting it as in flight. Two processes may write one history folder: the Sqlite store is in WAL mode with a busy timeout, the JSONL store appends to its index and never rewrites it; a run resumed under its own id (--resume <id>) continues the sequence the history holds for it, its second run.started carries resumed: true, so what orkeon runs show prints is not line for line the stream of either process. The daemon's own run id is the run's ExecutionId, the key of its history; hostRunId in run.started repeats it.
  • firefox β€” stated bounds (see the guide). The URL policy checks the pages the tab shows, before the browser starts and after every action that may navigate; the sub-resources a page loads (images, scripts, frames, XHR) are fetched by Firefox itself and are not checked β€” keep the browser on an isolated network when the policy matters. The text of a page is not screened for prompt injection. search sends the text of the page's sections to the embedding provider, as one ephemeral collection per page visited (prefix firefox), never deleted: the RAG subsystem has no API to drop a collection. The text of type is a tool argument the model writes and the transcript keeps: never a secret. One tab is driven at a time β€” a link that opens a tab moves the session to it, and the tab left behind is read again only after switch_tab; the tabs the user or another agent opened in a shared browser are never seen. A named profile is used as it is: the tabs Firefox restores at start are the user's, not the agent's, and what the profile holds (cookies, sessions, extensions) is neither filtered nor removed β€” an agent on the operator's own profile acts in the operator's name. The lock check before start recognises a profile held by a Firefox of this machine only; one open on another machine through a shared folder is not seen, and Firefox refuses it at start. screenshot writes a PNG to a virtual path and returns nothing else: the model does not see the image. A page restored from the history cache (back) is recognised by its address: back between two history entries of the same address waits for the command timeout (CommandTimeoutSeconds, 30 s) before the page is read. Verified on Firefox 159 under Linux; Windows and macOS launch paths are written, not campaigned.
  • orkeon eval scores what the suite can score. eval run --crew hands the crew one prompt per case (task_description, as the initial context and {input}) and scores its final output only: the intermediate task outputs and the events of the run are not in the report. eval bench scores recorded outputs and takes no --crew; its repeated runs only differ with the LLM judges. --offline with --crew refuses a crew in which any agent (or the manager) would answer through a provider other than the mock - its own profile, its own provider or the host default - and names the agent and the profile; it does not look at tools that reach the network on their own.
  • dotnet new templates: three starting points, no more β€” Orkeon.Templates ships orkeon-host, orkeon-plugin and orkeon-tool. The host template runs a crew.ork.ts through ICrewScriptRunner (so it needs esbuild on the machine, and pulls Orkeon.Tools and the local embeddings through Orkeon.Scripting); it is shaped like the orkeon-host daemon (generic host, appsettings.json) but is not the daemon: no crew registry, no chat gateway, no channels. The plugin template references Orkeon at compile time only (ExcludeAssets="runtime") and starts with the manifest of the sample plugin; a plugin is loaded from a folder, nothing publishes it. Every generated project pins the Orkeon packages to the version the template package was packed at, so a template installed from an older package generates a project on that older line. Hot reload and an IDE extension are not part of it.
  • The permission gate decides after a script's tool hooks. A script's onToolCall callback runs before the gate, which judges the input it returns (one consultation per call, inside the invocation with the tool-invocation pipeline): a call the gate denies has still run the callback. The tool budget is charged only once the guardian and the gate admit the call.
  • A bounded read of a JSONL run history reads the whole file. IRunHistoryReader.ReadEventsAsync(runId, fromSeq, limit, ct) applies the limit in SQL on the Sqlite store; the JSONL store reads the run's file and stops after the limit.
  • The permission gate is off unless a host turns it on. Orkeon:Security:PermissionGate:Enabled defaults to false: no tool call of a script or a YAML crew is gated, and an agent's permissionMode: is read by nothing until the gate is enabled (configuration). What still bounds a tool without it is the VFS rights of the mounts, the Guardian and the tool's own confinement (shell_command).
  • A crew's budget: block caps the autonomous mode only. Its tokens, wallTimeSeconds, toolCalls, delegationDepth and spawnedAgents are read by process: autonomous; a crew that declares it on another mode is refused at load. The cap every mode honours is the host's Orkeon:CostTracking:DefaultCrewBudget (MaxTokens, MaxCostUsd), summed per crew id β€” per run for a YAML or C# crew, which takes a new id at each load, while a script's own ctx.llm calls are summed under the crew's name for the life of the process, apart from its orchestrated tasks: the call that crosses it completes, the next one is refused with BudgetExhaustedException (configuration).
  • Security:Audit:RetentionDays is read by no purger. The key is declared (default 90) but nothing deletes old audit events: the in-memory sink lives as long as the process, and the files a JsonFileAuditSink writes under AuditDirectory stay until the host removes them.
  • Three paths load a crew without the deliverable check. The check that warns, at load, about a tool_call deliverable no agent can write (deliverables checked at load) runs in CrewFactory: a crew built in C# with CrewBuilder is not checked (the host calls DeliverableToolCheck.Check itself), a procedural .ork.ts under --validate is bundled, never loaded as a crew, and an agent whose model runs its own tools (a Microsoft Agent Framework agent) counts as able to write. On these paths the run still flags a file that was not written (deliverableMissing).
  • The iteration-cap and missing-deliverable flags are best-effort. Only the main agent loop (ChatClientAgentLoop) takes the tool-free turn after the iteration cap and sets endedOnIterationCap: the two fallback loops, the native tool-calling one and the legacy text one, end on the cap without the note and without the flag. A channel answered by a script's agent-command handler (AgentCommandRegistrar) answers false to both flags. deliverableMissing comes from a probe of the virtual file system after the task: without a file system, or when the probe fails, the flag stays false.