π«π· 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; itsexecutecan calltools.fileRead(...)and the value it returns reaches the model JSON-encoded in the tool result. - The declared
accessis the only input of the gate.readis allowed. Anedittool is denied inplanmode and asked indefaultmode: the ask goes through the approval channel, and underorkeon run, which has none, an Ask becomes a Deny (ModePermissionGate.cs). A tool that declares noaccesscounts as a write, fail-closed. - One approval per model-initiated call. The
tools.*calls made insideexecuteare 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 throwsUnknownToolErrorbefore the model is asked. A tool call the model makes to a tool the call does not offer is answeredERROR: tool '<name>' is not available to this agent.at once: neither the permission gate noronToolCallsees 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 sameeffortis accepted by the otherctx.llmcalls, byLlmConfig.with({...})(llm.default_.with({ effort })) and byagentBuilder().effort(level); any other value is refused witheffort must be low|medium|high|xhigh|max. Anthropic takes the five levels; a provider whose field knows fewer (its declaredEffortLevels: the three of the default for Ollama'sthink, Gemini, Azure OpenAI and Mistral; up toxhighfor 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 ofdocs/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" })orllm.default_.with({ cache: { systemPrompt: true } }), mapped onto the YAMLcache:block (LlmCacheConfig); attlother than5m/1h, attlon nothing cached or an unknown key throws. Likeefforton the builder, it shapes the agent's declared configuration (its turns in a crew) and the agent'sctx.llmcalls, a call's owneffortorcacheoption 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'sC:\proj\a.tsback to/workspace/a.tshas 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 adefault-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 readsDENIED: <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: β¦, andonToolResultruns on it; without the pipeline, and for a callonToolCalldenied, 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 passcontextPressure.thresholdTokens(characters / 4, 100000 by default) and older results remain, it is handed{ usedTokens, thresholdTokens, usedTokensByKind: { tool }, calls }(each call:id,name,input,resultChars,agein 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 lastcontextPressure.keepRecentmessages (not turns, 4 by default), a result seeded from an earlieract, and a result a verdict already settled are never offered. It answers by call id:"keep","head"(the firstcontextPressure.headCharscharacters, 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_budgetreads 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_agentis a model-callable tool, always offered inact. 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 ownpermissionModeand 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 withctx.spawnBackground, and a latercrew.sendto 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 nextactturn reads it as a user message:agent <name> completed: <text>, oragent <name> failed: <reason>.waitFor: "children"(option ofact): when the model answers while background children are still running, the loop waits for them and feeds their messages back. Children still running when theactends 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;stateisrunning,completed,failedorstopped.ctx.instanceIdis 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 againstMaxSpawnedAgentsand takes the per-agent semaphore. Asendon an unknown or evicted id, on a running instance, or while anothersendon the same id runs, is refused.crew.stop(id)cancels a running instance at once and returnstrue(falsefor 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 mostninstances, 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 sectionOrkeon:Cli:ScriptHost, default 10 minutes): on expiry the script receives a clearTimeoutException, 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 ownExecutionTimeout).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'slock) and the script-facing side ofctx.llm.actare async functions β async generators for the streams, sofor awaitworks on them β built once from a JavaScript factory. The CLR supplies only synchronous helpers (snapshot the agents, open an attempt, record a result) andTasks 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, aTaskwhose result is a CLR value (Jint settles it on the loop), or a JS promise obtained synchronously. It never callsInvoke,Evaluate,FromObjectorSetValuefrom a continuation, and never drains from inside a job. - A CLR helper reports failure as a JavaScript throw.
JsHostErrorwraps the exception in anErrorthat carries it onclr(its type name onclrType), so the script'scatchandfinallyrun, 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:
ScriptHostfor the script itself,JsCrew.RunAsyncfor theglobalThis.crewhandoff and for C# hosts,JsTool.CallAsyncfor a script tool the orchestrator calls. From C#,JsCrew.run,runAgentandrunStreamare the JS functions themselves (JsValue);RunAsyncis the CLR entry, and it refuses to start from inside a CLR callback the script invoked β from a script, callcrew.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.EvaluateAsyncandJsCrew.RunAsyncstart theirs throughRootPump.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.CallAsyncis the exception and stays on a pool worker throughTask.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 guardEngineThreadingGuardTestsnames that exemption (IsJsToolTaskRunExemption; itstask-run-around-pumprule skips that lambda) and refuses aTask.Runaround any other pump. - Cancellation is the only bound on a wait;
ExecutionTimeoutbounds execution. No promise timeout remains in the runtime: a root pump drains until its promise settles or its token fires. The sandbox'sExecutionTimeout(wall-clock,Orkeon:Scripting:Limits) bounds the evaluation itself, a whole script or a whole CLR-driven run (so doesMemoryLimitBytes). Its clock stops while the permission gate decides on actx.llm.acttool call, since an approval channel may wait for an operator; so does the agent's wall-time budget. A cancelledRunAsyncleaves the loop a short grace to unwind β itsfinallyblocks,onCrewErrorβ before it abandons the run and releases what the CLR owns. A run a body opens without asignalof its own βcrew.runAgent, a sub-crew'srunβ 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 eachnew Engineoptions lambda of a test, and, for the engines the factory andScriptHostbuild, once per test project by a[ModuleInitializer]on the internalJsEngineFactory.PromiseTimeout. The command profile setsScriptingLimitsOptions.PromiseTimeoutto infinite, since a command's host awaits withUnwrapIfPromiseAsync, which applies it; other product engines keep Jint's default. The sweepTestEngineHangGuardTestsfails 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.
LockTimeoutErroris V1.5. - Streaming through
ctx.llm.streamis per-token when the provider is anIStreamingLlmProvider(all 16 shipped providers are); the single full-text chunk is only the fallback for a non-streaming custom provider. ctx.llm.embedreturns 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).