Table of Contents

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

Scripting DSL β€” architecture

The Orkeon scripting DSL is a TypeScript-syntax language embedded in the runtime, implemented by the Orkeon.Scripting project (and exposed via the orkeon CLI). It is the recommended way to author crews when you don't want to write C#.

Why a DSL

Authors familiar with frontend tooling get a single-file authoring experience (.ork.ts) without a compilation step on their side: the runtime hands the file to esbuild β€” which strips the types and, when the file is on disk, bundles its relative imports β€” and runs the resulting JavaScript inside Jint with sandbox limits. The DSL surfaces the full Orkeon surface β€” agents, crews, tasks, custom tools, state machines, graphs, events, locks, lifecycle hooks β€” through fluent builders and literal declarations.

Where it lives in Clean Architecture

Orkeon.Scripting depends on Orkeon.Domain, Orkeon.Application, Orkeon.Infrastructure and Orkeon.Rag.Abstractions (the rag.* namespace). It does not modify those layers: it is an opt-in adapter that translates JS-side calls into existing domain invocations. It registers nothing in DI of its own β€” there is no AddOrkeon* extension: the CLI, the shared runner and the REPL (AddScriptCommands, see CLI TypeScript commands) construct the ScriptHost themselves.

src/
└── scripting/
    β”œβ”€β”€ Orkeon.Scripting/         ← this layer (Jint runtime + bindings)
    β”‚   β”œβ”€β”€ ScriptHost.cs
    β”‚   β”œβ”€β”€ JsEngineFactory.cs
    β”‚   β”œβ”€β”€ ScriptingHostPorts.cs ← permission gate + delta sink handed in by the host
    β”‚   β”œβ”€β”€ Adapters/             ← JsCrewConfigurationAdapter (the declarative handoff β†’ CrewConfiguration)
    β”‚   β”œβ”€β”€ Builders/             ← JsAgentBuilder, JsCrewBuilder, JsTaskBuilder, JsToolBuilder
    β”‚   β”œβ”€β”€ Bindings/             ← global registrations (agentBuilder, crewBuilder, llm, tools, rag, …)
    β”‚   β”œβ”€β”€ Runtime/              ← JsCrew, JsExecutionContext, JsAgentContext, JsLlmFacade, …
    β”‚   β”œβ”€β”€ Orchestration/        ← JsStateMachine, JsStateGraph
    β”‚   β”œβ”€β”€ ErrorPolicy/          ← JsErrorAction, ErrorCodeMapper
    β”‚   β”œβ”€β”€ Exceptions/           ← the typed runtime exceptions (StateMutationOutsideWithException, …)
    β”‚   β”œβ”€β”€ Internal/             ← JsHostError, JS trampoline factories
    β”‚   β”œβ”€β”€ Configuration/        ← ScriptingLimitsOptions, ScriptingToolchainOptions
    β”‚   β”œβ”€β”€ Versioning/           ← the version directive (`/// <reference orkeon-script="1.0" />` or `// @orkeon-script 1.0`)
    β”‚   β”œβ”€β”€ Telemetry/            ← ScriptingActivitySource
    β”‚   β”œβ”€β”€ Testing/              ← mock LLM / mock tool doubles (not exposed to scripts)
    β”‚   β”œβ”€β”€ Toolchain/            ← IScriptTranspiler, PassThroughTranspiler (esbuild behind them, internal)
    β”‚   └── Typings/              ← the *.d.ts declarations
    └── Orkeon.Scripting.Cli/     ← the `orkeon` tool: `run`, `quickstart`, `init`, `doctor`, `settings`, `llm`, `rag`, `eval`, `forge`, `usecases`, `email`, `drive`, `typings`, `mcp`, `runs`

Quick start

The runnable tutorials live in examples/scripting/ (hello world through FSM/graph literals and RAG). End-to-end:

dotnet build src/scripting/Orkeon.Scripting.Cli/Orkeon.Scripting.Cli.csproj
dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run examples/scripting/01-hello-world.ork.ts

The CLI emits the script result as JSON on stdout; exit codes follow the usual convention (0 ok, 1 script error, 2 runtime error, 130 cancelled; 75 when a crew run stops on a durable human-input question).

The same run verb also accepts a YAML crew β€” the target selects the path (.yaml/.yml or a directory holding a multi-file crew β†’ the shared crew runner; any other file β†’ Scripting DSL). A script that assigns globalThis.crew is a declarative crew definition and goes to the shared runner too, like YAML; the others run on the scripting host (the two shapes):

dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run examples/09-experimental/llm-response-format/crew.yaml

For YAML crews and declarative scripts the tool delegates to the shared one-shot runner (Orkeon.Hosting's RunnerExecution), so the YAML-only flags apply: -V/--var KEY=VALUE, --initial-context, plus the shared --settings/--mount/--mount-id/--allow-external-mounts/--verbose/--llm-log[-path] and the diagnostics/protocol flags (--validate, --list-tools, --events jsonl, --stream, --client). The procedural-script flags (--inputs, --inputs-file, --memory-limit-mb) are ignored on that path β€” a declarative script says so on stderr. The shared runner prints the crew output under a === Crew Output === banner instead of a JSON result. Every option: the CLI reference.

API recap

The declarations are the reference. They ship with the DSL, they are what your editor reads, and they live under src/scripting/Orkeon.Scripting/Typings/ β€” concatenated at build into one orkeon.d.ts that the orkeon tool carries and writes next to your project with orkeon typings (Reference).

Two pages sit on top of them: Write a crew in TypeScript for the narrative, and the Scripting DSL reference for the method-by-method table β€” including the column the declarations cannot carry, which of the two script shapes actually honours each method.

Concept Where to look
agentBuilder() / crewBuilder() / taskBuilder() (with .decision() and .when()) / toolBuilder() agent.d.ts, crew.d.ts, task.d.ts, tool.d.ts
ExecutionContext and AgentContext (ctx.llm, ctx.memory, ctx.fileSystem, A2A, locks, spawn) context.d.ts
ctx.llm.act β€” the LLM ⇄ tool-call loop, and its ActOptions context.d.ts
Events (ctx.events.queue / ctx.events.topic) events.d.ts
stateMachine / stateGraph literal forms fsm.d.ts, graph.d.ts
onError, ErrorAction, error codes agent.d.ts, errors.d.ts
The globals the runner exchanges with the script (crew, inputs, result) globals.d.ts
The version directive /// <reference orkeon-script="1.0" /> or // @orkeon-script 1.0 orkeon-script.d.ts
Lifecycle hooks (onAgentStart, onCrewComplete, …) agent.d.ts, crew.d.ts
onCommand β€” answer dispatched CLI commands by name cli-ts-commands.md
Built-in tools.X(...) namespace tools.d.ts, tools.generated.d.ts (written by BuiltInToolTypings from the tools a run registers, pinned by BuiltInToolTypingsTests)
The agent's model settings (llm.default_, llm.model(...), llm.profile(...), llm.profiles) llm.d.ts
RAG (rag.ingest, rag.query, rag.retrieve) rag.d.ts

Autonomous tools in act

A tool built with toolBuilder() and attached to an agent with withAutonomousTool is offered to the model in the REPL act loop. The permission gate treats it from what the script declared, and nothing else (pinned by ReplAutonomousToolActTests):

  • Offered and executed. A tool declared with access("read") is offered to the model; its execute can call tools.fileRead(...) and the value it returns reaches the model JSON-encoded in the tool result.
  • The declared access is the only input of the gate. read is allowed. An edit tool is denied in plan mode and asked in default mode: the ask goes through the approval channel, and under orkeon run, which has none, an Ask becomes a Deny (ModePermissionGate.cs). A tool that declares no access counts as a write, fail-closed.
  • One approval per model-initiated call. The tools.* calls made inside execute are not asked a second time: approving the script tool covers what its body does.

Options of act

Five options of ctx.llm.act(prompt, options) shape the loop itself (the full list is ActOptions in context.d.ts). They are fixed when the call starts (one ActSession per call):

  • tools: ["file_read"] offers the model only that subset of the agent's tools. A name the agent does not hold throws UnknownToolError before the model is asked. A tool call the model makes to a tool the call does not offer is answered ERROR: tool '<name>' is not available to this agent. at once: neither the permission gate nor onToolCall sees it, and no approval is asked.
  • effort: "low" | "medium" | "high" | "xhigh" | "max" sets the provider's thinking setting for the call (LlmConfig.Thinking, enabled with that effort). The same effort is accepted by the other ctx.llm calls, by LlmConfig.with({...}) (llm.default_.with({ effort })) and by agentBuilder().effort(level); any other value is refused with effort must be low|medium|high|xhigh|max. Anthropic takes the five levels; a provider whose field knows fewer (its declared EffortLevels: the three of the default for Ollama's think, Gemini, Azure OpenAI and Mistral; up to xhigh for OpenAI and Grok; all five for Z.ai, Anthropic, OpenRouter, DeepSeek, Kimi, Qwen, Together AI, Hugging Face, MiniMax and Mammouth AI), or a model that takes fewer (the per-model table of docs/architecture/llm-providers.md), sends the highest level both take below the one asked, and logs a warning saying so, never a silent change. The prompt cache is requested the same way on an agent, agentBuilder().cache({ systemPrompt: true, tools: true, ttl: "1h" }) or llm.default_.with({ cache: { systemPrompt: true } }), mapped onto the YAML cache: block (LlmCacheConfig); a ttl other than 5m/1h, a ttl on nothing cached or an unknown key throws. Like effort on the builder, it shapes the agent's declared configuration (its turns in a crew) and the agent's ctx.llm calls, a call's own effort or cache option winning (#254).
  • onToolCall(call) runs before each tool call, before the permission gate, which judges the input the callback returns: a script that brings a model's C:\proj\a.ts back to /workspace/a.ts has the canonical path judged, once (#303). It returns "allow" (the gate judges the call as it came); "ask" (once the mode admits the call, it goes to the approval channel as a default-mode edit would, and a denied answer is a deny); { deny: reason } (the call does not run and the gate is not asked, the model reads DENIED: <reason>); or { input } (the gate judges the rewritten input, and the call runs with it). A callback that throws, or returns anything else (nothing included), denies; "ask" with no permission gate denies.
  • onToolResult(call, result) runs after each tool call with the call and its result (the JSON parsed, or the text when it is not JSON). A returned { context: "..." } replaces the line the model is shown for that result; returning nothing keeps it. Through the host's invocation pipeline (the REPL, orkeon run) a call the guardian or the gate refused (an operator's refusal included) is a result too, DENIED: …, and onToolResult runs on it; without the pipeline, and for a call onToolCall denied, a refused call never reaches it.
  • onContextPressure(pressure) prunes stale tool results from the loop (#327). Before a model turn, once the loop's messages pass contextPressure.thresholdTokens (characters / 4, 100000 by default) and older results remain, it is handed { usedTokens, thresholdTokens, usedTokensByKind: { tool }, calls } (each call: id, name, input, resultChars, age in model turns). Only results of read tools (ToolAccess.Read) that ran are offered: running one again is harmless, unlike a write, a command or a refused call. The last contextPressure.keepRecent messages (not turns, 4 by default), a result seeded from an earlier act, and a result a verdict already settled are never offered. It answers by call id: "keep", "head" (the first contextPressure.headChars characters, 1000 by default) or "drop". A pruned result leaves a line that names the call (its input cut to 200 characters), says what was cut and that the call can be run again, so the model never reads the absence as an empty result; the call itself stays in the messages. A call left out is kept and offered again; a callback that throws, or a return that is not an object, prunes nothing. The estimate counts the messages' text, tool calls and reasoning, not images nor tool schemas. token_budget reads the session buffer, which never sees the loop's messages, so it does not measure this pressure.

The callbacks run on the engine thread, through the same pump as script tools (see the threading model below); onToolCall always comes before the permission gate.

The token budget of act

budget({ tokens }) is a running sum: each chat call of the loop adds its prompt plus its completion (the provider's total). Every call resends the whole context, so the context is counted again on each call: a turn of n calls whose context grows evenly pays it about n times, and the figure bounds neither the size of the conversation nor what a provider bills with its cache. Each call logs the running sum next to the limit (act: agent '<name>' call used <n> tokens, running sum <sum>/<limit> tokens over <n> calls, Information).

budget({ contextTokens }) counts the context once (#224): each call adds its completion plus, when the provider reports cache hits (cacheHitTokens), the part of its prompt the cache did not serve, else what its prompt grew by since the same conversation's previous call: each ctx.llm.act is its own conversation, its first call counting its whole prompt, so acts in a row or at once on one budget each pay their own context (never less than zero: a compacted context adds nothing). A turn of n calls on a context of c tokens spends about c plus its completions. A provider that reports no prompt and completion counts the call whole, as tokens does. Set alone, it leaves tokens uncapped; set with it, the first one spent ends the act, the same way. Each call also logs act: agent '<name>' context counted once <sum>/<limit> contextTokens when it is set.

When the sum, or the context counted once, reaches the limit, the act does not fail. A call whose tokens pass it keeps its answer: a final answer is returned as it is. The tool calls it asks for do not run: once the budget is spent no other tool runs, on the last iteration too, and the act ends with one last chat call that may call no tool, after a user turn telling the model its budget is spent and asking it to answer now with what it has. That call keeps the tools of the loop declared with ToolMode.None β€” a history that holds tool calls needs them on Anthropic, which is sent tool_choice: none, as the OpenAI-compatible providers are; Ollama, which has no such switch, is sent no tools. That answer is the act's result, with budgetExhausted: true; a tool call it returns anyway is never run, its tokens are recorded but start no other wrap-up, and it is kept even when it ends after the wall-time limit. A warning logs that the budget ran out. When that last call fails, or answers nothing, the act rejects with BudgetExhaustedError, whose message names what it counted: Token budget exhausted: <sum> tokens sent and received over <n> calls (limit <limit>), or under contextTokens Token budget exhausted: <n> context tokens (the growth or the uncached part of each prompt, plus every completion) over <n> calls (limit <limit> contextTokens); both are on the tokens dimension. The other dimensions (tool calls, wall time, delegation depth, spawns) still reject at the gate, and maxIterations still ends with exhausted: true.

Child agents: spawn_agent and ctx.spawnBackground

  • spawn_agent is a model-callable tool, always offered in act. It runs a named crew agent as a child ({ "agent", "input" }) and returns its output. The child runs under a child budget (delegation depth + 1); a refusal (depth or spawn budget exhausted, unknown agent) is a failed tool result the model reads, never an exception. The child's acts run under the stricter of their own permissionMode and the spawner's act (plan, dontAsk > default > acceptEdits > bypassPermissions), as a crew delegation does; under plan or dontAsk the spawn itself, an edit, is refused. What a spawned run starts with ctx.spawnBackground, and a later crew.send to it, keep that floor. The run is engine work: it goes through the root pump, like script tools (see the threading model below).
  • ctx.spawnBackground(agent, input) starts a crew agent in the background and returns its ticket ({ id, agent }) at once. Its completion reaches the script-context inbox, and the next act turn reads it as a user message: agent <name> completed: <text>, or agent <name> failed: <reason>.
  • waitFor: "children" (option of act): when the model answers while background children are still running, the loop waits for them and feeds their messages back. Children still running when the act ends are cancelled.
  • crew.concurrency(n) bounds the children running at once (default 4, n >= 1). The slot is acquired before the per-agent semaphore.

Agent instances: crew.instances, crew.send, crew.stop

Each background ticket and each spawn_agent call is an agent instance of its crew, with the id a<ticket> (a1, a2, ...). The ids are script-side only: the response of the spawn_agent tool is unchanged.

  • crew.instances() lists { id, agent, state } rows; state is running, completed, failed or stopped. ctx.instanceId is the id of the instance a child body runs as.
  • crew.send(id, message) runs one more bare act on the same agent (its tools and system message, a fresh child budget) seeded with the instance's stored transcript, appends the result to that transcript and resolves to the reply text. It takes a crew gate permit, counts as a spawn against MaxSpawnedAgents and takes the per-agent semaphore. A send on an unknown or evicted id, on a running instance, or while another send on the same id runs, is refused.
  • crew.stop(id) cancels a running instance at once and returns true (false for a finished or unknown id). The gate slot is freed when the act settles, after the tool calls in flight end.
  • Bounds: crew.maxInstances(n) (default 32) keeps at most n instances, evicting the oldest finished one, never a running one; each transcript is capped in messages and in total characters, the oldest messages dropped first. A failed or cancelled act stores no transcript (the previous one stays); an act ended by { interrupted: true } stores its transcript without the trailing assistant turn whose tool calls have no result.

Durable agent memory: ctx.memory.agent

ctx.memory.agent (store, get, search, delete) outlives the run when the host provides an IScriptAgentMemoryStore: the shared runner (YAML crews and declarative scripts under orkeon run, orkeon-host) and the REPL's *.cmd.ts commands do, through one JSON file per project and agent under /workspace/.orkeon/agent-memory/<project>/. A value stored by agent a is returned in the next run for a, never for b; the key is agent:<project>:<agent name>. A write replaces the whole file under a per-file lock and restores a backup if it fails; a key holding a newline is refused. Hosts without the port (a procedural script under orkeon run, the Forge assistant and test bench) keep ctx.memory.agent in memory, for the run only.

Coexistence with YAML

The YAML configuration path remains supported and unchanged. Scripts and YAML crews can share the same hosting application: the DSL is one of several authoring surfaces, not a replacement. The published orkeon tool runs both surfaces directly (orkeon run crew.yaml and orkeon run crew.ork.ts): a consumer of the published packages needs no runner of their own to execute YAML crews.

Blocking calls from scripts

Jint executes a script on a single thread: a host call that waits for its result blocks the whole script β€” and the REPL hosting it β€” until it returns. Two CLI bridges deliberately keep that synchronous contract (blocking by design):

  • ctx.services.get("script-host").runCrew(name, input?) β€” runs a crew and waits for its output. Short crews only. The wait is bounded by a configurable timeout (ScriptHostFacadeOptions.RunCrewTimeout, config section Orkeon:Cli:ScriptHost, default 10 minutes): on expiry the script receives a clear TimeoutException, the abandoned run is cancelled cooperatively, and the REPL thread is always released (a pure-JS busy loop that ignores cancellation is eventually reaped by the Jint sandbox's own ExecutionTimeout).
  • ctx.services.get("commands").request(agent, intent, payload) β€” blocks until the agent replies; same guidance applies (see cli-ts-commands.md).

The nominal path for long work is the ticket cycle: runCrewAsync(name, input?) (backed by CommandDispatchService.postWork, same mechanism as commands.post) returns a ticket immediately and delivers the crew summary to a defineAsyncCommand's completed(result, ctx) callback.

completed may be async ((result, ctx) => void | Promise<void> in orkeon-cli.d.ts). When it returns a promise, the drain awaits it before going on to the next completion or the next command of the script, the same rule as an async dispatch: its whole body, every await included, settles there. A host read made at each hop (the session's rules, inspect) therefore sees what the operator changed between two hops, and a runCrewAsync made after an await is chained to the command like one made before it. A promise the handler does not await is not waited for, and a launch made from it is not chained. A rejection or a throw does not stop the drain: the console shows Error in completed('<name>'): <first line of the reason>, the host log keeps the whole error, and the registry reports a completion failure for the instance (CommandInstanceRegistry.ReportCompletionFailure, which stops an orkeon-repl --replay on the line that launched it). The instance keeps its own state, and a crew launched before the rejection still runs and drains.

defineAsyncCommand({
  name: "step",
  description: "Run a crew, then the next one, saving the session at each hop.",
  dispatch: (args, ctx) => ({ ticket: ctx.services.get("script-host").runCrewAsync("plan") }),
  completed: async (result, ctx) => {
    // "session": a host service of the application whose save() returns a Task, a promise here
    const saved = await ctx.services.get("session").save();
    ctx.writeLine(`plan done, session saved to ${saved}`);
    ctx.services.get("script-host").runCrewAsync("implement", { plan: result.payload });
  },
});

Threading model

A Jint engine is not bound to a thread, but it is single-drainer: one thread at a time runs its event-loop jobs, and a drain started from inside a job cannot pump β€” it would wait on jobs that only the thread it is blocking could run. A CLR call that re-enters the engine from the wrong side β€” after an await, or by draining from inside a job β€” hangs a crew run, times out a state graph or crashes concurrent ctx.state.with calls. The runtime follows one rule, and the reproducers in tests/scripting/Orkeon.Scripting.Tests/Runtime/EngineThreadingContractTests.cs pin it:

  • Every loop that calls back into script code lives in JavaScript. The crew run (crew.run, crew.runAgent, crew.runStream), the state graph (run, runStream), the state machine (send), ctx.state.with, topic delivery (publish, the event's lock) and the script-facing side of ctx.llm.act are async functions β€” async generators for the streams, so for await works on them β€” built once from a JavaScript factory. The CLR supplies only synchronous helpers (snapshot the agents, open an attempt, record a result) and Tasks the loop awaits (a semaphore acquisition, a retry delay, the run's cancellation). Every line of those loops runs as a promise reaction on whichever thread is draining.
  • A CLR callback never re-enters the engine after an await. A delegate exposed to the script may return a value synchronously, a Task whose result is a CLR value (Jint settles it on the loop), or a JS promise obtained synchronously. It never calls Invoke, Evaluate, FromObject or SetValue from a continuation, and never drains from inside a job.
  • A CLR helper reports failure as a JavaScript throw. JsHostError wraps the exception in an Error that carries it on clr (its type name on clrType), so the script's catch and finally run, the loop releases what it holds, and the CLR side recovers the typed exception from the rejected value.
  • The CLR drives the engine at three root pumps only, each with the engine at rest, under the per-engine gate, on one thread for the whole evaluation β€” the synchronous prefix and every job after it: ScriptHost for the script itself, JsCrew.RunAsync for the globalThis.crew handoff and for C# hosts, JsTool.CallAsync for a script tool the orchestrator calls. From C#, JsCrew.run, runAgent and runStream are the JS functions themselves (JsValue); RunAsync is the CLR entry, and it refuses to start from inside a CLR callback the script invoked β€” from a script, call crew.run().
  • The script and crew pumps run on a dedicated thread, not on a pool worker. A pump blocks its thread until the promise settles, so on the pool it would hold a worker for the whole run and starve a capped pool. ScriptHost.EvaluateAsync and JsCrew.RunAsync start theirs through RootPump.Start (TaskCreationOptions.LongRunning | DenyChildAttach): one thread per script and per crew run driven from C#, with no bound on their number, released when the run ends. JsTool.CallAsync is the exception and stays on a pool worker through Task.Run: a tool call is short, and a dedicated thread per call cost 145 to 164 Β΅s per spawn against about 10 Β΅s for the call (median +1491 % against a 1 % threshold). The permanent guard EngineThreadingGuardTests names that exemption (IsJsToolTaskRunExemption; its task-run-around-pump rule skips that lambda) and refuses a Task.Run around any other pump.
  • Cancellation is the only bound on a wait; ExecutionTimeout bounds execution. No promise timeout remains in the runtime: a root pump drains until its promise settles or its token fires. The sandbox's ExecutionTimeout (wall-clock, Orkeon:Scripting:Limits) bounds the evaluation itself, a whole script or a whole CLR-driven run (so does MemoryLimitBytes). Its clock stops while the permission gate decides on a ctx.llm.act tool call, since an approval channel may wait for an operator; so does the agent's wall-time budget. A cancelled RunAsync leaves the loop a short grace to unwind β€” its finally blocks, onCrewError β€” before it abandons the run and releases what the CLR owns. A run a body opens without a signal of its own β€” crew.runAgent, a sub-crew's run β€” is a child of the run that opened it: cancelled with it, unwound inside its unwind. The parent is the most recently opened attempt still open on the engine, exact under sequential nesting and best-effort under runs interleaved on one event loop; { signal: ctx.signal } is the explicit form.
  • Tests wait on an engine under a named hang guard. The runtime has no promise timeout, so a test that awaits an engine would otherwise inherit Jint's implicit 10 seconds. It waits under HangGuards.EnginePromise (2 minutes, Orkeon.Tests.Shared.Timing): set on each new Engine options lambda of a test, and, for the engines the factory and ScriptHost build, once per test project by a [ModuleInitializer] on the internal JsEngineFactory.PromiseTimeout. The command profile sets ScriptingLimitsOptions.PromiseTimeout to infinite, since a command's host awaits with UnwrapIfPromiseAsync, which applies it; other product engines keep Jint's default. The sweep TestEngineHangGuardTests fails a test engine that carries no guard.

Configuration and toolchain

The sandbox limits are read from Orkeon:Scripting:Limits (ScriptingLimitsOptions) by the orkeon run script path, the shared runner and the forge:

Key Default Meaning
MemoryLimitBytes 104857600 (100 MB) Jint memory ceiling. What a host tool the script calls (tools.*, or a tool call made by ctx.llm.act) allocates on the engine thread is left out: only the execution of the tool is outside the limit, not the rest of ctx.llm.act. The exclusion is closed on any exit from the tool call (an exception included), holds across nesting and Reset(), and belongs to the thread that opened it. orkeon run --memory-limit-mb overrides it for a procedural script; 0 or less disables it.
RecursionLimit 64 Maximum JavaScript call depth.
ExecutionTimeout 00:00:30 Wall-clock bound of one evaluation β€” a whole script, or a whole CLR-driven crew run; the permission gate's decisions are not counted.

The *.cmd.ts commands of the REPL use their own profile, Orkeon:Cli:ScriptCommands:Limits (CLI TypeScript commands).

The esbuild toolchain is read from Orkeon:Scripting:Toolchain (ScriptingToolchainOptions), by every host that transpiles: orkeon run, the shared runner, orkeon doctor, orkeon forge and the REPL's *.cmd.ts commands:

Key Default Meaning
EsbuildPath β€” Absolute path to the esbuild binary; first in the lookup order below.
EsbuildTimeout 00:00:30 Wall-clock bound of one esbuild transpilation or bundle.
TypeCheck Validate Off, Validate or Always: when tsc type-checks a .ork.ts (below).
TscPath β€” Absolute path to the tsc binary; when set it is the only candidate.
TypeCheckTimeout 00:01:00 Wall-clock bound of one type check.

esbuild is looked up, in order: Orkeon:Scripting:Toolchain:EsbuildPath, the ORKEON_ESBUILD_PATH environment variable, an esbuild-bin/esbuild[.exe] next to the running binary (what the release archives ship), the repository's tools/scripting-esbuild/node_modules/ (installed by the Orkeon.Scripting build with npm ci, skipped with -p:SkipScriptingNpmInstall=true; searched up to eight parent folders from the working directory and from the binary), then PATH. When nothing is found the error lists every place it tried; orkeon doctor reports it as the esbuild check.

The orkeon dotnet tool does not ship esbuild. Its package carries no esbuild-bin/, so after dotnet tool install -g Orkeon.Scripting.Cli a .ork.ts script runs only once esbuild is on the machine: npm install -g esbuild (it lands on PATH), or a binary you point ORKEON_ESBUILD_PATH or EsbuildPath at. Nothing is downloaded on first run. YAML crews never need it. The Orkeon.Scripting NuGet package, which runs a crew in a .NET application's own process (Hosting β€” running a crew in-process), does not ship it either and finds it the same way.

A script may open with /// <reference orkeon-script="1.0" />, or with // @orkeon-script 1.0, the form tsc accepts: it rejects the reference form (TS1084) and then skips its semantic pass, so a project that type-checks its scripts uses the line comment, which orkeon forge generates. The directive is optional; when present, a version the runtime does not support (only 1.0 today) fails the run with ScriptVersionMismatchError before anything executes. A script carrying both forms is read by its reference form.

Type-checking a script

esbuild strips types and reports syntax only. orkeon run --validate on a .ork.ts therefore runs the TypeScript compiler first (after the MCP servers connect, before the crew loads) against the orkeon.d.ts roll-up this build embeds, test.d.ts included. Orkeon:Scripting:Toolchain:TypeCheck picks when: Off never, Validate (default) in --validate, Always in --validate and before every run.

A type error prints VALIDATION FAILED: type errors (ERROR: type errors before a run), then one line per error, <virtual path>:line:col TSxxxx message, and exits 1 (2 before a run). The paths are the VFS's (/script/main.ork.ts, /script/lib/helper.ts); the compiler is an external process that reads and prints physical paths, so it works on a scratch copy whose paths are mapped back before anything is shown. The copy (of the script and of every local module it imports) blanks the two pragma forms (tsc rejects the reference form with TS1084 and then skips its semantic pass) without moving a line, and a script's relative imports still resolve. The scratch folder is written by the framework itself, outside the VFS, and deleted afterwards.

A module may keep /// <reference path="…/.orkeon/orkeon.d.ts" /> for its editor: that copy, written by orkeon typings, would otherwise be checked beside the embedded roll-up and report every identifier twice (TS6200). A copy identical to this build's roll-up (line endings aside) stands in for it; a copy that differs fails with one line on the copy, TS6200 this copy of the Orkeon typings is not the one this build ships …: regenerate it with `orkeon typings` .

tsc is looked up like esbuild: Orkeon:Scripting:Toolchain:TscPath (the only candidate when set), then tools/scripting-typecheck/node_modules/.bin/ of a checkout (bootstrap it with npm --prefix tools/scripting-typecheck install --prefer-offline), then PATH (npm install -g typescript). Nothing is downloaded. Without a compiler, Validate prints WARNING: type check skipped: … and validates the rest; Always fails with VALIDATION FAILED: type check unavailable. A tsc that dies with no diagnostic (crash, signal, non-zero exit) fails as type check failed (exit N), never as "no errors". orkeon doctor reports it as the tsc check: a missing compiler is ok under Off and Validate, where it is optional, and fail under Always; a configured TscPath that does not exist is ok under Off (unused), warn under Validate and fail under Always; a tsc that does not answer --version is ok under Off and warn otherwise.

V1 limits

  • agentBuilder().concurrency(N) capped at 1 (mutex). N-holders semaphore is V1.5.
  • Locks have no timeout. LockTimeoutError is V1.5.
  • Streaming through ctx.llm.stream is per-token when the provider is an IStreamingLlmProvider (all 16 shipped providers are); the single full-text chunk is only the fallback for a non-streaming custom provider.
  • ctx.llm.embed returns a stub vector; integration with real embedders is a follow-up.
  • FSM/Graph hierarchical composability (sub-states, sub-graphs) is V1.5.
  • Events are in-memory only (no Redis/NATS persistence).

Reference

This page says what the DSL is and where it sits; the typings say what it exposes. The crew surface is orkeon.d.ts β€” the Typings/*.d.ts above concatenated (errors.d.ts first, the others alphabetically) by the Orkeon.Scripting build, which embeds it in the assembly and also writes it to src/scripting/Orkeon.Scripting/bin/<configuration>/net10.0/dist/orkeon.d.ts. orkeon-cli.d.ts is a different file for a different surface: the *.cmd.ts commands documented in cli-ts-commands.md.

Both ship inside the orkeon tool. orkeon typings writes them into ./.orkeon/ (or --out <dir>), overwriting what is there β€” run it again after updating the tool, so the editor reads the surface of the runtime that will execute the scripts (CLI reference).