Table of Contents

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

Scripting DSL reference (.ork.ts)

Every builder, every method, and the one column that exists nowhere else: which of the two script shapes actually honours it.

The signatures live in src/scripting/Orkeon.Scripting/Typings/*.d.ts, concatenated at build into the orkeon.d.ts your editor reads. This page does not repeat them. It answers the question the declarations cannot: does the engine that will run my file read this at all?

For the narrative version β€” what to write, in what order, and why β€” see Write a crew in TypeScript.

The two shapes

A .ork.ts file is dispatched to one of two different engines, chosen by how the file ends. orkeon run reads the source (RunCommand.DeclaresCrewHandoffAsync) looking for an assignment to globalThis.crew β€” (globalThis as any).crew = … counts too β€” and routes on what it finds.

Procedural Declarative
the file ends with await crew.run() globalThis.crew = crew
engine ScriptHost.RunFromFileAsync β€” the script's own await crew.run() shared runner β†’ JsCrewConfigurationAdapter β†’ ICrewOrchestrationService
runs agent .body() yes, one per agent, in declaration order no β€” ignored
honours withTask / process / manager no β€” ignored yes β€” manager where the process has one (hierarchical, consensual), refused elsewhere
orkeon run --validate fails (did not assign globalThis.crew) β€” after running the script: loading it evaluates it, await crew.run() included works β€” the script is evaluated, the crew is not run

They are opposites, not variants. The procedural run loop (JavaScript, JsCrew.Run.cs, run under the script's own pump) walks the agents and never looks at tasks; Process reaches only a telemetry tag. The adapter, symmetrically, never invokes a body: the only places it names one are the warnings it emits for the declarations it drops.

The rule: write .body() and you are procedural; write withTask and you are declarative. Never both in one file. A crew with tasks that ends with await crew.run() runs its agents and ignores every task you wrote β€” logging a warning that says exactly that.

It is orkeon run that routes a globalThis.crew script to the declarative engine. A host that runs the file through ScriptHost β€” the REPL's script-host service, a C# host calling RunFromFileAsync β€” has no orchestrator: it runs the exported crew procedurally, bodies and all, tasks ignored.

What each shape reads

Measured against JsCrewConfigurationAdapter.cs, JsCrew.cs and JsExecutionContext.cs, not inferred.

agentBuilder()

Method Procedural Declarative
name βœ… βœ…
role goal backstory stored, not sent: ctx.llm sends your prompt alone; role only serves crew.findByRole βœ… the agent's prompt β€” build() requires role
llm the provider only: an agent configured with llm.profile("…") has ctx.llm talk to that profile's provider, on the profile's model; otherwise ctx.llm uses the host's provider on its configured model (per call: { llm: { profile } } for another host profile, { llm: { model } } for another model) βœ… an LlmConfig β€” llm.default_, llm.model("…"), llm.profile("…"), .with({...}) β€” sets the agent's provider (one of the host's profiles), model, temperature and token cap. A string or a plain object is refused by .llm(...)
tools([...]) built-ins by name βœ… what ctx.llm.act may call β€” a name the host does not offer rejects act with an UnknownToolError, before any model call βœ… strict: an unknown name fails the run
withAutonomousTool(s) instances callable from a body (tool.execute(input)) and offered to ctx.llm.act, which runs the tool's execute in the script βœ… registered and resolved by name
effort(level) β€” "low", "medium", "high", "xhigh" or "max": turns the provider's thinking on at that effort βœ… sent on the agent's ctx.llm calls, unless a call sets its own { effort } βœ…
cache({ systemPrompt, tools, ttl }) β€” YAML cache:: asks the provider's prompt cache to keep the system prompt and/or the tool definitions (ttl "5m" or "1h"; cache({}) turns caching off, the host default Llm:Cache included) βœ… sent on the agent's ctx.llm calls, unless a call sets its own { cache } βœ…
maxIterations verbose allowDelegation ❌ (act has its own maxIterations) βœ… β€” maxIterations defaults to 20, as in YAML and C#
maxRpm β€” YAML maxRpm:: at most N model requests per minute for this agent, one more waiting its turn (none by default; 0 or less refused at build()) ❌ (warned: ctx.llm calls are no agent turns β€” the host's RateLimiting still caps them) βœ…
maxExecutionTime(seconds) β€” YAML maxExecutionTime:: the seconds a task may take on this agent (none by default; 0, negative, decimal or above 4294967 refused at build()) ❌ (warned: the procedural engine runs no task) βœ…
workingRoot(path) β€” YAML working_root:: the virtual directory its file and shell tools stay inside (agent working root; none by default; an empty path refused at build(), a root under no mount, relative or holding .. refused when the agent's run starts) βœ… every tool the body runs β€” through ctx.llm.act, ctx.tools or tools β€” stays inside it; a child started by spawn_agent or ctx.spawnBackground without a root of its own runs under it, and so does each later crew.send to it βœ…
filesystem([...]) β€” YAML filesystem:: the only virtual paths its tools may touch, each a path or { path, access } with access "ro", "rw" or "rwnd" (agent file-system scope; none by default; an empty array, an unknown key or access refused at build(), an entry under no mount or above the mount's rights refused when the agent's run starts) βœ… every tool the body runs β€” through ctx.llm.act, ctx.tools or tools β€” is held to it; a child started by spawn_agent, ctx.spawnBackground or ctx.delegate runs under it, its own filesystem only narrowing it, and so does each later crew.send to it; a run started from code while agents run (crew.run, crew.runAgent, a sub-crew's) takes the open attempts' scope, refused when their scopes differ; onAgentStart/onAgentStop hooks run under the agent's scope (a crew hook under the first agent's), a lifecycle hook whose scope the mounts refuse is skipped with a warning; rag.ingest from a scoped body expands its globs under the scope and refuses a source outside it βœ…
announceMounts(value) β€” YAML announce_mounts:: whether its system prompt lists its virtual paths and working root (on by default) βœ… off, ctx.fileSystem.prompt is ""; on, it holds the section, which the body places in the prompt it gives ctx.llm.act (that prompt is the script's: nothing is added to it) βœ…
withResponseFormat(type) / withResponseSchema(name, schema, strict?) ❌ (per call: { responseFormat }) βœ…
body βœ… the whole point ❌ never invoked
withState β†’ ctx.state βœ… ❌
onError βœ… ❌
onAgentStart / onAgentStop fire when the agent joins a crew (crewBuilder().build(), crew.add, ctx.spawn) and leaves it (crew.remove) β€” not at run start and end the same: onAgentStart fires at build(), during evaluation, although the run warns that both are ignored
concurrency only 1 β€” see below ❌
onCommand neither: it is the CLI dispatch seam, not a run-time hook

crewBuilder()

Method Procedural Declarative
name βœ… βœ…
goal ❌ stored, never read βœ…
verbose βœ… βœ…
withAgent(s) β€” a built agent; anything else is refused βœ… βœ…
withTask(s) β€” a built task; anything else is refused ❌ ignored βœ… the whole point
process ❌ telemetry tag only βœ… ("graph" selects the domain's retry-and-route strategy, not a script-drawn topology β€” see below)
manager ❌ βœ… β€” process("hierarchical"): the manager assigns and reviews on that agent's .llm(...) (llm.profile("claude") puts it on that profile); process("consensual"): the arbiter of the ManagerDecision fallback; the four other processes refuse it when the run adapts the crew, as does an agent of another crew
memory ❌ βœ…
planning β€” YAML planning: true: a step-by-step plan per task, read in the task's prompt (off by default; on the host's default profile) ❌ (warned) βœ…
maxRpm β€” YAML maxRpm:: at most N model requests per minute for the crew, all its agents and its manager together (none by default; 0 or less refused at build()) ❌ (warned) βœ…
budget βœ… βœ… with process("autonomous") β€” the crew's budget, as YAML budget:; refused with another process, as is a limit that is not 1 or more, when the run adapts the crew
concurrency(n) β€” the most children (ctx.spawnBackground, spawn_agent) the crew runs at once (default 4; n must be 1 or more) βœ… ❌ (not warned)
maxInstances(n) β€” the most agent instances (crew.instances()) the crew keeps (default 32; the oldest ended one goes first) βœ… ❌ (not warned)
onCrewStart / onCrewComplete / onCrewError βœ… ❌

Everything marked ❌ on the declarative side, concurrency and maxInstances aside, is announced: the run logs one warning per dropped declaration, naming the method and the agent it was written on. It is still dropped β€” the two shapes are two engines.

What await crew.run() resolves to β€” a CrewResult, exactly what crew.d.ts declares: output, the last agent output that was not null, as the body returned it β€” the same value as that run's tasks[i].output, an object staying an object ("" when no agent returned anything) β€” and tasks, one { name, output, durationMs } per agent run, in the order they ran, output being what the body returned. Nothing more: no artifacts map. TypingsRuntimeParityTests compares the two result shapes type by type.

process("graph") is not stateGraph

They are different facilities with a shared word. process("graph") runs the crew on the domain's graph strategy: one node per task, chained in execution order (a retry is the task's retry:), with a circuit breaker tuned by GraphConfig; a crew file can also describe its nodes and edges in a graph: block, which a script does not write. stateGraph({ nodes, edges }) is the topology you draw, and it runs when you call .run() on it β€” from an agent .body(), so procedurally.

crewBuilder() has no graph(...) method: process("graph") builds on its own, and a stateGraph runs only through its own .run().

taskBuilder()

Declarative only β€” the procedural engine never reads tasks. Carried to the crew: description, agent (a built agent), expectedOutput, withContext(s) (this is what builds the DAG), tools (added to the agent's own tools for that task only, never replacing them), humanInput, asyncExecution, retry, deliverable, withResponseFormat(type), withResponseSchema(name, schema, strict?) and withProfile(name) (YAML llm_override: { profile }: this task alone runs on one of the host's profiles, on that profile's own model, and "default" brings it back to the host's default; a name the host does not offer fails the load, listing the known ones). name is the task's key: when(...) and a decision's state refer to a task by it, and a decision task requires it. Accepted but not acted on: expect (recorded in the task context when there is no deliverable, never validated).

decision(spec) makes the task a decision task: spec is an object literal { questions, minConfidence, state, longContext, fallback }, the shape of the YAML decision: block. It needs no agent, and a task that has both is refused at load. when(decisionTask, clauses) runs the task only when the decision task named answered as asked: clauses is a clause object ({ category: ["bug"], urgency: ">= 0.7", "category.bug": ">= 0.25" }) or the string "otherwise"; when() throws (an Error the script catches) only for an empty task name or for clauses that is neither an object nor a string. A string other than "otherwise", an unknown question or option, or a malformed clause passes the builder and is refused at load. Two decision tasks with the same name in one script are refused at load (Task '<name>' declares a decision twice.). state lists the tasks whose output is the decision's state (default: each dependency that ran); with the circuit off, or by --no-decision, the task answers from fallback (see Decision models). Decision tasks and conditions run in the Sequential, Parallel and Graph processes only. A second .when() on one task throws an Error naming the task. A state that is not an array, a fallback that is not an object, and a choice value, score entry or fallback value that is not a string are refused at load, naming the task and the key. Two tasks with the same name are refused at load. A task without .name() is keyed by its full description; truncation is display only. See Decision models.

asyncExecution() follows the YAML rule: under .process("sequential") the task runs alongside the tasks after it, and a task that lists it in withContext waits for it; under .process("parallel") it has no effect of its own; under the four other modes the crew is refused when the run adapts it, naming the task (see Asynchronous tasks).

retry({ attempts, backoffMs?, backoff? }) is the YAML retry: block (see Task retry): a failed attempt runs the whole task again, tool calls included, up to attempts runs in all (at least 1, required); backoffMs (default 0) and backoff ("fixed", the default, or "exponential") set the wait. A missing or invalid attempts, a negative backoffMs, an unknown backoff, or a retry on a decision task throws an Error the script catches at the call (or at build() for the decision task). It is the only retry of a .process("graph") crew.

A task's agent and the tasks of its withContext(s) are the crew's own (withAgent(s), withTask(s)): one the crew does not hold is refused when the run adapts the crew, naming the task, the call and what the crew has.

toolBuilder()

Both shapes. name, description, withSchema, execute, access, build.

The schema is not read by the type system: toolBuilder() with no type argument gives execute an unknown input, and every field access on it is an error. State the shape the schema promises:

const wordCount = toolBuilder<{ text: string }, { words: number }>()
    .name("word_count")
    .withSchema({ type: "object", properties: { text: { type: "string" } }, required: ["text"] })
    .execute((input) => ({ words: input.text.trim().split(/\s+/).length }))
    .build();

The globals

Three names the runner exchanges with the script, declared in globals.d.ts.

Global Direction Meaning
crew script β†’ runner The declarative handoff. Assigning it is what selects the declarative engine.
inputs runner β†’ script What --inputs / --inputs-file parsed β€” or the input of the REPL's script-host.runCrew(name, input). Procedural shape only.
result script β†’ runner What a procedural run reports when the script's completion value is undefined β€” which is always the case once the file has a top-level await, because it then runs wrapped in an async function. Assign it as globalThis.result = …: a top-level const result is local to that wrapper. Serialised to JSON: a CrewResult goes whole β€” its output and one { name, output, durationMs } per agent under tasks β€” and a plain projection prints only what it names. Left unassigned, the run prints {"result": null}.

ctx β€” the agent context

Procedural shape only; nothing in the declarative path constructs one.

ctx.state carries the one legal mutator, with(). It replaces the state with what the callback returns, under the agent's state mutex β€” so carry the fields you are not changing:

await ctx.state.with(prev => ({ ...prev, count: prev.count + 1 }));

Assigning directly (ctx.state.count = 1) throws StateMutationOutsideWithException. The state is a JS Proxy whose set trap exists to make that loud rather than lost.

ctx.signal is a .NET CancellationToken projected through interop, not a DOM AbortSignal β€” there is no DOM in Jint. It carries IsCancellationRequested and CanBeCanceled, CLR-cased; aborted, addEventListener and throwIfAborted are all undefined. Pass it along (crew.run({ signal: ctx.signal })) rather than polling it.

ctx.llm β€” complete(prompt), chat(messages), stream(prompt) (async-iterable; usage and reasoningChunks are read after the loop, reasoning at once), extract(prompt, schema), decide(prompt, choices), embed(text), act(prompt, opts), and interrupt() / isInterrupted. Every call goes to the agent's provider (the host's, or its profile's), or to the profile { llm: { profile } } names; without one, a <undefined-llm:…> echo answers, which is what lets the examples run keyless. A call takes these options, all for that call only: llm: { profile } runs it on the host profile of that name (Llm:Profiles:<name>) by the rule of llm.profile(name) β€” a name the host does not offer throws an Error the script catches (an awaited call rejects with it), listing the known ones (also in llm.profiles), "default" is the host's own provider, and a decision profile applies its stages to the call β€” and the others patch the configuration of the call's provider: responseFormat ("json_object", "json_schema", "text"), llm: { model } (a per-call model, within the profile's provider when profile is set: { profile, model } is llm.profile(profile, { model }); an LlmConfig is refused there, its temperature and token cap would not apply) and effort ("low", "medium", "high", "xhigh" or "max": the provider's thinking, on at that effort; any other value is refused with effort must be low|medium|high|xhigh|max) and cache (the prompt-cache request, as agentBuilder().cache(...) takes it). act takes more: see Options of act (tools, effort, onToolCall, onToolResult, onContextPressure, waitFor). There is no per-call vendor, temperature or token cap, and no signal β€” the call already observes the context's. embed is a local stub: it calls no provider and reads none of these options.

What the model takes and what becomes of the effort are read, not guessed (#359, #360). An LlmConfig (llm.default_, llm.model("…"), llm.profile("…"), .with({...})) carries capabilities: { model, known, thinking, efforts }, thinking one of "none", "effortOnly", "toggle", "budget", and efforts the levels among low to max, in order, that the provider and the model both take (empty when the model takes no effort or does not reason; known: false when the capability table has no entry, the provider's levels then apply unchecked). It also carries reasoning, and so do the results of act and chat and the object stream() returns: { model, asked, sent, notice }, the effort asked (by the call's effort, agentBuilder().effort, .with({ effort }) or the host's Llm:Thinking:Effort), the effort sent (null when none goes out) and notice, "lowered", "dropped", "unchecked" (a model the table does not know) or null when it went as asked; reasoning is null when no effort is asked. Inside an agent, ctx.llm calls run on the agent's provider, model and effort, which no LlmConfig the script holds carries: ctx.llm.reasoning(opts) and ctx.llm.capabilities(opts) answer for the call those options name, judged as that call is (the options' effort and llm: { profile, model } included), and place no call; that is the report complete and extract cannot carry, since they return the text or the object alone. Both are null without a provider. They are judged before the call: a fallback profile answers for its first link and a decision profile for its target, so a call that fails over, or that a decision routes to another profile, may be judged otherwise.

chat takes a bare message array or { messages: [...] }. extract(prompt, schema, opts) takes the same forms as its first argument, the caller's turns sent in order, plus a prompt string; its options add system, sent as the first message with the JSON instruction appended to it, so the user content goes untouched. Without system, the instruction is appended to the prompt or to the last user message. A re-ask carries the refused answer as an assistant turn:

const again = await ctx.llm.extract<Invoice>({ messages: [
    { role: "user", content: prompt },
    { role: "assistant", content: refused },
    { role: "user", content: "That is not JSON. Answer with the object only." },
] }, schema, { system: "You extract invoices." });

When the reply is not JSON, extract throws an error that says why: the provider's own failure (ctx.llm.extract: the provider failed: …, with the HTTP status and the vendor's message), an empty reply (and, when it ended on finish_reason: length or max_tokens, that the output budget ran out, reasoning included, naming the cap the model actually ran with: MaxTokens, else the model's resolved limit), or a reply that does not parse (the line and byte of the JSON error, then how the reply begins and ends). Each message carries the finish reason and the prompt, completion and reasoning token counts the provider gave. decide raises the provider's failure the same way (ctx.llm.decide: the provider failed: …) instead of reporting an empty answer. chat, like complete, answers a failed call with the <undefined-llm:…> marker holding the provider's sentence, never with an empty content.

act is the LLM ⇄ tool-call loop: it offers the model the built-ins the agent selected with .tools([...]) and its withAutonomousTool instances β€” whose execute runs in the script, on the engine's own thread β€” until the model stops asking or maxIterations (default 10, 0 = unlimited) is reached. It resolves to { output, iterations } (plus interrupted or exhausted when the loop stopped early). Every tool call of a turn runs, in order, and the turn is replayed in the provider's own tool protocol β€” the assistant turn with its calls, then one tool result per call, a permission refusal or a tool error included β€” whether the provider answers in the OpenAI shape (most providers, Ollama included) or with the Anthropic Messages body. A result is cut once, at the framework's bound (AgentDefaults.ResolveMaxToolResultLength: 4 000 characters by default; per-tool overrides: file_read 32 000, node_read 256 000, shell_command 10 000, and 12 000 for the analysis tools that answer with a graph or a page: dependency_graph, sub_graph, edge_list, flow_trace, impact_analysis, codebase_map, package_summary, symbol_detail, codebase_search, structural_search, structural_rewrite, affected_tests): by the host's tool invocation pipeline when it has one, by act otherwise. A turn the provider failed resolves output to <undefined-llm:<the provider's error>>, as complete does. A call a stage of the host's decision profile blocks is not a provider failure: complete, chat, extract, decide, act and a stream iteration reject with a DecisionBlockedError (errorType: "DecisionBlocked", profile, stage, risk for a guard, reason), so a crew can tell the user which stage refused the request; uncaught, it fails the run with the DecisionBlockedException. A name in .tools([...]) that no tool of the host answers to (compared case-insensitively) is not skipped: act rejects with an UnknownToolError (agentName, toolNames, availableTools) before any model call β€” the procedural twin of the load failure the declarative shape gets for the same name; an onError handler reads it as validation. ActOptions.system seeds a real role:"system" message that persists across every iteration; without it act() sends a single user message. ActOptions.context seeds a user message of its own between system and the prompt: the prompt stays the last user message, the request a decision profile's guard and route stages judge, so the context cannot dilute its risk. permissionMode (default, acceptEdits, bypassPermissions, plan, dontAsk) is checked against the host's permission gate on each tool call, when the host registered one: a call the mode asks about waits for the operator when the host has an approval channel (orkeon-repl has one), and is refused otherwise; the time the gate takes to decide is not counted in ExecutionTimeout, nor in the agent's wall-time budget (.budget({ wallTime })). ctx.llm.permissionGate.enabled says whether the host registered a gate; without one, a permissionMode checks nothing and the call logs one warning saying so β€” declare a script tool's .access("read") for it to pass plan; onDelta receives the streamed text of each assistant turn, and onToolCallDelta each fragment of a tool call the model is building ({index, id?, name?, argumentsDelta}; id and name come on the fragment that carries them, and Ollama sends a call whole). On a host that registered DLP, the arguments of a call arrive held, in one redacted fragment, once the call ends.

ctx.delegate(agentOrName, input) is crew.runAgent: the target runs with its own context, under its semaphore and its onError policy. Neither gives the run a budget unless asked: ctx.delegate(agent, input, { budget: { toolCalls: 20, tokens: 50000, wallTime: 300 } }) (and the same budget in crew.runAgent's options) bounds that run with the keys and values of crewBuilder().budget(...) (toolCalls, tokens, contextTokens, wallTime in seconds or as "5m", delegationDepth, spawnedAgents). tokens is a running sum of the prompt and completion of every call, the context counted again on each. contextTokens counts the context once: each call's completion plus the uncached part of its prompt when the provider reports cache hits, else what the prompt grew by since the same conversation's previous call (each ctx.llm.act its own), so a turn of n calls on a context of c tokens spends about c plus its completions, not n Γ— c; set alone it leaves tokens uncapped, and a declarative autonomous crew refuses it. Once either is reached, ctx.llm.act makes one last call that may call no tool and resolves with budgetExhausted: true (the token budget of act). A spent dimension ends the run with BudgetExhaustedError, the error a crew's budget gives, and a child it spawns (spawn_agent, ctx.spawnBackground) derives its budget from the run's. An unknown key, a count that is not a whole number of 1 or more, or an unreadable wallTime is refused when the run opens, where the procedural crewBuilder().budget(...) skips it. charge: "crew", beside budget, counts what the run spends (tool calls, tokens, spawns; its wall clock runs with the caller's) against the budget of the run it is called from as well β€” the crew's, from an agent body of crew.run β€” so runs started at once never spend more than the crew allows. A call the run's own budget refuses is not charged, and the children it spawns are charged too, each allowed no more than what both budgets have left. Without budget the run spends straight from the caller's, and it is refused when the caller runs under no budget. ctx.delegate charges its own context's budget. crew.runAgent cannot name the body it is called from: it charges the one budget every open agent body runs under, and is refused when bodies under different budgets are open (a fan-out beside a budgeted delegated run); call ctx.delegate from the body instead. crew.run and crew.runStream ignore both keys. ctx.send(agentOrName, message), receive({ timeout }) and broadcast(message) exchange messages; send and broadcast are synchronous. ctx.crew is a read-only view of the crew (name, findByName, findById, findByRole, has, lock(name, fn)). ctx.log.info(message, ...args) joins the extra arguments with a space, objects as JSON. Also ctx.memory (crew, and agent in an agent body), ctx.events, ctx.lock(name, fn), ctx.spawn. ctx.spawnBackground(agent, input) starts a crew agent as a child and returns its ticket; ctx.instanceId is the id of the agent instance a body runs as; ctx.fileSystem.prompt is the ## File system section a declarative turn of the agent holds (the file system in the prompt), for the body to place in its own system prompt; crew.instances(), crew.send(id, message) and crew.stop(id) list, message and stop the kept instances (Agent instances). See context.d.ts.

A host failure reaches the script as an instance of the class errors.d.ts declares β€” try { await q.pop({ timeout: 100 }) } catch (e) { if (e instanceof ReceiveTimeoutError) … } β€” with that class's fields (agentName, timeoutMs…), plus clrType (the .NET type name) and clr (the exception). A failure with no declared class is a plain Error with the same two properties. A builder or factory method that refuses its argument β€” agentBuilder().effort("turbo"), a build() missing a field, a stateGraph(...) literal with a bad topology, llm.profile("ghost") β€” throws an InvalidScriptError (clrType "InvalidScriptException") the script catches, and an awaited ctx.llm.* call refused the same way rejects with one: the message names the fault, so a script that builds from data tests e instanceof InvalidScriptError and falls back to a default. A value over a domain limit stays a plain Error, its clrType "ArgumentException", and so does an out-of-range ErrorAction.retry delay ("OverflowException"). The engine's own limits (time, memory, recursion) are not refusals: they stop the script whatever it catches. An onError handler receives { code, message, exception, attempt, agent: { id, name } } and the context; code is one of rate_limit, network, timeout, receive_timeout, state_mutation, agent_not_in_crew, validation, decision_blocked, unknown.

The namespaces

Global What it holds
llm The model settings agentBuilder().llm(...) takes (declarative shape). llm.default_ β€” a value, not a function β€” is the host's provider on its configured model (an empty model when the host configures none: the agent then runs on that provider's own default, never on OpenAI's), or the <undefined-llm> echo when the host has none; llm.model(name, overrides?) is the same provider on another model; llm.profile(name, overrides?) is one of the host's named profiles (Llm:Profiles:<name>) on its own model β€” an agent configured with it runs its turns and its ctx.llm calls on that provider, and a name the host does not offer throws an Error the script catches (try … catch), listing the known ones ("default" is llm.default_); llm.profiles is that list, a frozen array of names β€” "default" first, then the host's profiles in the spelling it declared, never an endpoint or a key β€” so a script checks a name before it asks for it, without case as llm.profile compares. with({ model, temperature, maxTokens, responseFormat, effort, cache }) returns a copy, keeps the profile, and refuses any other key. There is no per-vendor factory: a script picks among the providers the host configured, by profile name.
tools The host's built-in tools, called from a body: tools.fileRead({ path }), the snake_case name camelCased. tools.generated.d.ts declares the input and the result of every built-in tool a run registers, written from its request and response records (the tool's own snake_case keys: tools.fileRead({ path, max_length })), so a misspelled parameter fails the type check; tools.d.ts declares the e-mail and drive families by hand. A plugin or MCP tool is reachable the same way, untyped.
rag rag.ingest({ collection, sources, chunkingStrategy?, reindex?, prune? }), rag.query(question, { collection, profile?, topN? }) (a grounded answer with citations) and rag.retrieve(...) (the same passages, no generation). Needs a host that registered the RAG subsystem (AddOrkeonRag); bound in orkeon run, the REPL and the daemon host alike.
test Only under orkeon run --test: the mocks and assertions of the script (below).
ErrorAction The factories an onError handler returns: fail(), skip(), fallback(value), retry({ delay?, max? }). Anything else is treated as fail().
stateMachine, stateGraph, START, END Below.

The test namespace (orkeon run --test)

orkeon run --test binds the global test (declared in Typings/test.d.ts); without the flag a script has none, and a reference to it is a ReferenceError. Under the flag the host's configured model β€” or the --llm-mock file β€” stays behind the mock: a prompt an expectation of test.mockLlm fits is answered by it, any other prompt goes to the configured provider. One mock is shared by ctx.llm, the crews of the script, the namespace and the providers of llm.profile("…"), so an expectation registered in the script is the one a call meets, whichever profile it is made on.

test.mockLlm.when("weather").respond("sunny");        // a string to look for, or { prompt: /regex/ }
test.mockTool("lookup").when({ city: "Paris" }).respond({ temp: 21 });

await crew.run();
test.assertLlmCalled({ times: 1, with: "weather" });
test.assertToolCalled("lookup");

From .NET, MockLlmProvider and MockTool (Orkeon.Scripting.Testing) take the same expectations through When(string | Regex).Respond(...); TestOverrideLlmProvider is the provider that puts them in front of a configured one.

A failed assertion is an Error too (clrType "AssertionException"), as is a refused mock (test.mockTool(""), a { prompt: /regex/ } .NET cannot read): a catch-all try … catch around it swallows the failure, so rethrow what the catch does not handle.

stateMachine and stateGraph

Both are literal-driven.

stateMachine takes { name, initial, states }. Transitions live inside each state, keyed by event name, and the destination field is target:

const fsm = stateMachine({
    name: "order", initial: "pending",
    states: {
        pending:  { transitions: { approve: { target: "approved" } }, onEntry: (c) => {} },
        approved: { transitions: { ship: { target: "shipped" } } },
        shipped:  {},
    },
});
await fsm.send("approve");   // resolves to the NEW state name

send(event, payload?) returns the state it ended in β€” which is the current state, unchanged, when the event is unknown to it or a guard refused. An unknown event is not an error. A transition may carry a guard (return false to veto it); a state may carry onEntry and onExit, each handed { state, payload }. The machine exposes name and current. There is no run() method and no circuitBreaker option.

stateGraph takes { name, nodes, edges, graphConfig? }. edges is an object keyed by source node, not a list of pairs, and START/END are plain strings ("__START__"):

const g = stateGraph<{ done: boolean }>({
    name: "research",
    nodes: { gather: (s) => ({ ...s, done: true }) },
    edges: { [START]: "gather", gather: END },
    graphConfig: { circuitBreakerPreset: "Strict" },
});

An edge is a node name, END, or a function of the state returning one (a conditional edge). graphConfig bounds each run(state): circuitBreakerPreset (Strict, Default, Permissive) or the individual maxTransitions, maxStateVisits, maxRetryCycles (the script graph's own budget: the run-wide count of entries into a node already entered once, kept for the budget parity of the two engines; it is not a task retry, which is the task's retry:) and maxTotalDurationSeconds β€” exceeding a count throws, running out of time cancels the run. runStream(state) yields each hop ({ fromNode, toNode, state }) for for await.

stateGraph(...) checks the graph's shape when it is built, with the validator the Domain engine and the crew's graph share (ADR-018), and reports every fault in one InvalidScriptError the script catches: an edge from or to an undeclared node, a node with no outgoing edge, a node nothing reaches (an orphan), no path from START to END, a node that cannot reach END. A function edge cannot be read before it runs, so it is assumed to be able to lead anywhere, END included. Each time the loop enters a node, a graph.node.entered event goes to the host (orkeon run --events jsonl writes it).

Defaults, when graphConfig is absent: 200 transitions, no bound on the visits of one node, no bound on revisits (maxRetryCycles) and no duration bound; a circuitBreakerPreset replaces all four. (The Domain engine alone takes the Strict policy, 50 transitions and 5 visits, and a bare CircuitBreakerPolicy is 100 and 10: the defaults differ per engine and stay as they are.) maxStateVisits is the Domain's MaxStateVisits: a node entered more often than that trips the breaker. maxRetryCycles counts, over the whole run, the entries into a node already entered once; on a graph that loops on one node, maxRetryCycles: k and maxStateVisits: k + 1 are the same bound (the node runs k + 1 times, the next entry throws), which GraphBudgetParityTests pins on both engines. With several nodes it stays a different, run-wide bound.

TState cannot be inferred from the node bodies β€” a node both takes and returns the state, so inference is circular β€” and falls back to Record<string, unknown>. Annotate the call (stateGraph<OrderState>({...})) to get a node that returns the wrong shape reported.

Design limits

The declarations and the C# runtime are written in two languages. Two gates tie them together: scripts/check-scripting-typings.sh typechecks every .ork.ts under examples/ against the typings, and a parity test (TypingsRuntimeParityTests) compares, member by member, each declared interface with the runtime type behind it. No gap between the two remains; what follows are limits of the design, each of them stated rather than silent.

Limit Behaviour
budget() in the declarative shape The crew's budget when the process is "autonomous", the one process that spends it (keys toolCalls, tokens, delegationDepth, spawnedAgents, wallTime; contextTokens is refused there, the strategy counting each finished task's tokens, not each call's prompt). With another process the crew is refused when the run adapts it, the error naming the process.
.body() in the declarative shape Ignored, and said so: the run logs a warning naming the agent. The most expensive confusion in the DSL, and the reason for the shape table above.
globalThis.inputs in the declarative shape Never planted. Passing --inputs, --inputs-file or --memory-limit-mb to a declarative script prints a warning on stderr instead of dropping the flag in silence.
ctx.llm.embed Returns a deterministic stub vector, not a real embedding.
concurrency(n) with n > 1 Rejected at build with a clear message: an agent's concurrency is a mutex. Loud, not silent.
Locks have no timeout There is no LockTimeoutError.
Events In-memory only; no Redis/NATS persistence.
FSM/Graph composition Neither sub-states nor sub-graphs.

Conditional inclusion

The only conditional construct is when(decisionTask, clauses) on a task builder, which runs the task on a decision task's answers at runtime (see decision(spec) above). There is no predicate that includes or excludes an agent or a task when the script is built.

Guard the call instead:

const b = crewBuilder().name("nightly");
if (shouldAudit) b.withAgent(auditor);

Editor setup

Run orkeon typings in your project: it writes orkeon.d.ts (this DSL) and orkeon-cli.d.ts (the REPL's *.cmd.ts commands) into ./.orkeon/ β€” --out <dir> picks another folder β€” and overwrites them, so run it again after updating the tool. Each script then opens with /// <reference path="./.orkeon/orkeon.d.ts" /> (the path relative to the script). The files come from the tool itself, so they describe the runtime that will execute your scripts. In a clone, the sources are src/scripting/Orkeon.Scripting/Typings/*.d.ts, concatenated by the build into bin/<configuration>/net10.0/dist/orkeon.d.ts under that project.

To pin the typings of a release, or to diff two of them, take them from the Release instead of from whichever tool is installed: each GitHub Release attaches orkeon-typings-<version>.tar.gz, the same two files orkeon typings writes, taken from that release's own build. It is listed in the release's SHA256SUMS and attested like the other archives (gh attestation verify, see Verify what you install):

VER=<version>    # the tag without its v
curl -fsSL -O "https://github.com/Orkeon/orkeon/releases/download/v$VER/orkeon-typings-$VER.tar.gz"
gh attestation verify "orkeon-typings-$VER.tar.gz" --repo Orkeon/orkeon
mkdir -p .orkeon && tar -xzf "orkeon-typings-$VER.tar.gz" --strip-components=1 -C .orkeon
# between two versions, extract each into its own folder and:  diff -r typings-A typings-B

When a Release does not carry it, orkeon typings is the source. Then copy tools/scripting-typecheck/tsconfig.base.json, which is the configuration the repository's own gate uses.

Three of its options are load-bearing:

  • moduleDetection: "force" β€” without it, top-level await crew.run() is rejected (TS1375) and a top-level const crew collides with the crew global (TS2451). Two errors that have nothing to do with your code.
  • target/lib ES2022 β€” what Jint supports. Asking for more promises APIs that are not there; the DOM in particular is absent, which is why ctx.signal is not an AbortSignal.
  • types: [] β€” there is no Node in a .ork.ts. process, require and Buffer do not exist at run time and should not exist at authoring time either.

Where to go next