Table of Contents

🇬🇧 English version

Référence du DSL de scripting (.ork.ts)

Chaque builder, chaque méthode, et la colonne qui n'existe nulle part ailleurs : laquelle des deux formes de script l'honore réellement.

Les signatures vivent dans src/scripting/Orkeon.Scripting/Typings/*.d.ts, concaténées au build dans le orkeon.d.ts que lit votre éditeur. Cette page ne les recopie pas. Elle répond à la question que les déclarations ne peuvent pas trancher : le moteur qui va exécuter mon fichier lit-il seulement ceci ?

Pour la version narrative — quoi écrire, dans quel ordre, et pourquoi — voir Écrire une crew en TypeScript.

Les deux formes

Un fichier .ork.ts est confié à l'un de deux moteurs différents, choisi par la façon dont le fichier se termine. orkeon run renifle la source (RunCommand.DeclaresCrewHandoffAsync) à la recherche d'une affectation à globalThis.crew — (globalThis as any).crew = … compte aussi — et route selon ce qu'il trouve.

Procédurale Déclarative
le fichier finit par await crew.run() globalThis.crew = crew
moteur ScriptHost.RunFromFileAsync — le propre await crew.run() du script runner partagé → JsCrewConfigurationAdapter → ICrewOrchestrationService
exécute les .body() d'agent oui, un par agent, dans l'ordre de déclaration non — ignoré
honore withTask / process / manager non — ignoré oui — manager là où le process en a un (hierarchical, consensual), refusé ailleurs
orkeon run --validate échoue (did not assign globalThis.crew) — après avoir exécuté le script : le charger l'évalue, await crew.run() compris fonctionne — le script est évalué, la crew n'est pas exécutée

Ce sont des opposés, pas des variantes. La boucle procédurale (en JavaScript, JsCrew.Run.cs, exécutée sous la propre pompe du script) parcourt les agents et ne regarde jamais les tâches ; Process n'atteint qu'un tag de télémétrie. L'adaptateur, symétriquement, n'invoque jamais un body : les seuls endroits où il en nomme un sont les avertissements qu'il émet pour les déclarations qu'il ignore.

La règle : écrivez .body() et vous êtes en procédural ; écrivez withTask et vous êtes en déclaratif. Jamais les deux dans un fichier. Une crew avec des tâches qui se termine par await crew.run() exécute ses agents et ignore chaque tâche écrite — en journalisant un avertissement qui le dit exactement.

C'est orkeon run qui route un script globalThis.crew vers le moteur déclaratif. Un hôte qui exécute le fichier via ScriptHost — le service script-host du REPL, un hôte C# qui appelle RunFromFileAsync — n'a pas d'orchestrateur : il exécute la crew exportée en procédural, .body() compris, tâches ignorées.

Ce que lit chaque forme

Mesuré sur JsCrewConfigurationAdapter.cs, JsCrew.cs et JsExecutionContext.cs, pas déduit.

agentBuilder()

Méthode Procédurale Déclarative
name âś… âś…
role goal backstory conservés, pas envoyés : ctx.llm envoie votre seul prompt ; role ne sert qu'à crew.findByRole ✅ le prompt de l'agent — build() exige role
llm le fournisseur seulement : un agent configuré avec llm.profile("…") fait parler ctx.llm au fournisseur de ce profil, sur le modèle du profil ; sinon ctx.llm utilise le fournisseur de l'hôte sur son modèle configuré (par appel : { llm: { profile } } pour un autre profil de l'hôte, { llm: { model } } pour un autre modèle) ✅ un LlmConfig — llm.default_, llm.model("…"), llm.profile("…"), .with({...}) — règle le fournisseur de l'agent (l'un des profils de l'hôte), son modèle, sa température et son plafond de jetons. Une chaîne ou un objet simple est refusé par .llm(...)
tools([...]) intégrés par nom ✅ ce que ctx.llm.act peut appeler — un nom que l'hôte n'offre pas fait rejeter act par une UnknownToolError, avant tout appel au modèle ✅ strict : un nom inconnu fait échouer le run
withAutonomousTool(s) instances appelables depuis un body (tool.execute(input)) et proposées à ctx.llm.act, qui exécute le execute de l'outil dans le script ✅ enregistrées et résolues par nom
effort(level) — "low", "medium", "high", "xhigh" ou "max" : active la réflexion du fournisseur à cet effort ✅ envoyé sur les appels ctx.llm de l'agent, sauf si un appel fixe son propre { effort } ✅
cache({ systemPrompt, tools, ttl }) — le cache: du YAML : demande au cache de prompt du fournisseur de garder le prompt système et/ou les définitions d'outils (ttl "5m" ou "1h" ; cache({}) coupe le cache, y compris le défaut Llm:Cache de l'hôte) ✅ envoyé sur les appels ctx.llm de l'agent, sauf si un appel fixe son propre { cache } ✅
maxIterations verbose allowDelegation ❌ (act a son propre maxIterations) ✅ — maxIterations vaut 20 par défaut, comme en YAML et en C#
maxRpm — le maxRpm: du YAML : au plus N requêtes au modèle par minute pour cet agent, une de plus attendant son tour (aucun par défaut ; 0 ou moins refusé à build()) ❌ (avertit : les appels ctx.llm ne sont pas des tours d'agent — le RateLimiting de l'hôte les plafonne toujours) ✅
maxExecutionTime(seconds) — le maxExecutionTime: du YAML : les secondes qu'une tâche peut prendre chez cet agent (aucun par défaut ; 0, négatif, décimal ou au-dessus de 4294967 refusé à build()) ❌ (avertit : le moteur procédural n'exécute aucune tâche) ✅
workingRoot(path) — le working_root: du YAML : le répertoire virtuel où restent ses outils fichier et shell (racine de travail d'un agent ; aucune par défaut ; un chemin vide refusé à build(), une racine hors de tout mount, relative ou contenant .. refusée au démarrage du run de l'agent) ✅ chaque outil que le corps exécute — par ctx.llm.act, ctx.tools ou tools — y reste ; un enfant lancé par spawn_agent ou ctx.spawnBackground sans racine propre s'exécute sous elle, comme chaque crew.send ultérieur à cet enfant ✅
filesystem([...]) — le filesystem: du YAML : les seuls chemins virtuels que ses outils peuvent toucher, chacun un chemin ou { path, access } avec access "ro", "rw" ou "rwnd" (périmètre de fichiers d'un agent ; aucun par défaut ; un tableau vide, une clé ou un accès inconnus refusés à build(), une entrée hors de tout mount ou au-delà des droits du mount refusée au démarrage du run de l'agent) ✅ chaque outil que le corps exécute — par ctx.llm.act, ctx.tools ou tools — y est tenu ; un enfant lancé par spawn_agent, ctx.spawnBackground ou ctx.delegate s'exécute sous lui, son propre filesystem ne pouvant que le réduire, comme chaque crew.send ultérieur à cet enfant ; un run lancé depuis le code pendant que des agents tournent (crew.run, crew.runAgent, celui d'une sous-crew) prend le périmètre des tentatives ouvertes, refusé quand leurs périmètres diffèrent ; les hooks onAgentStart/onAgentStop s'exécutent sous le périmètre de l'agent (un hook de crew sous celui du premier agent), un hook de cycle de vie dont les mounts refusent le périmètre est sauté avec un avertissement ; rag.ingest depuis un corps à périmètre développe ses globs sous le périmètre et refuse une source hors de lui ✅
announceMounts(value) — l'announce_mounts: du YAML : si son prompt système liste ses chemins virtuels et sa racine de travail (actif par défaut) ✅ désactivé, ctx.fileSystem.prompt vaut "" ; actif, il porte la section, que le corps place dans le prompt qu'il donne à ctx.llm.act (ce prompt est celui du script : rien n'y est ajouté) ✅
withResponseFormat(type) / withResponseSchema(name, schema, strict?) ❌ (par appel : { responseFormat }) ✅
body ✅ tout l'intérêt ❌ jamais invoqué
withState → ctx.state ✅ ❌
onError ✅ ❌
onAgentStart / onAgentStop se déclenchent quand l'agent rejoint une crew (crewBuilder().build(), crew.add, ctx.spawn) et la quitte (crew.remove) — pas au début et à la fin du run de même : onAgentStart se déclenche à build(), pendant l'évaluation, bien que le run avertisse que les deux sont ignorés
concurrency seulement 1 — voir plus bas ❌
onCommand ni l'un ni l'autre : c'est la couture de dispatch CLI, pas un hook d'exécution

crewBuilder()

Méthode Procédurale Déclarative
name âś… âś…
goal ❌ conservé, jamais lu ✅
verbose âś… âś…
withAgent(s) — un agent construit ; tout le reste est refusé ✅ ✅
withTask(s) — une tâche construite ; tout le reste est refusé ❌ ignoré ✅ tout l'intérêt
process ❌ tag de télémétrie seulement ✅ ("graph" choisit la stratégie de reprise-et-routage du domaine, pas une topologie dessinée par le script — voir plus bas)
manager ❌ ✅ — process("hierarchical") : le manager assigne et revoit sur le .llm(...) de cet agent (llm.profile("claude") le place sur ce profil) ; process("consensual") : l'arbitre du repli ManagerDecision ; les quatre autres process le refusent quand le run adapte la crew, de même qu'un agent d'une autre crew
memory ❌ ✅
planning — le planning: true du YAML : un plan pas à pas par tâche, lu dans le prompt de la tâche (coupé par défaut ; sur le profil par défaut de l'hôte) ❌ (avertit) ✅
maxRpm — le maxRpm: du YAML : au plus N requêtes au modèle par minute pour la crew, tous ses agents et son manager confondus (aucun par défaut ; 0 ou moins refusé à build()) ❌ (avertit) ✅
budget ✅ ✅ avec process("autonomous") — le budget de la crew, comme budget: en YAML ; refusé avec un autre process, comme une limite qui n'est pas d'au moins 1, quand le run adapte la crew
concurrency(n) — le plus grand nombre d'enfants (ctx.spawnBackground, spawn_agent) que la crew exécute à la fois (4 par défaut ; n doit valoir 1 ou plus) ✅ ❌ (sans avertissement)
maxInstances(n) — le plus grand nombre d'instances d'agent (crew.instances()) que la crew garde (32 par défaut ; la plus ancienne terminée part la première) ✅ ❌ (sans avertissement)
onCrewStart / onCrewComplete / onCrewError ✅ ❌

Tout ce qui porte un ❌ du côté déclaratif, hors concurrency et maxInstances, est annoncé : l'exécution journalise un avertissement par déclaration abandonnée, en nommant la méthode et l'agent sur lequel elle était écrite. C'est toujours abandonné — les deux formes sont deux moteurs.

Ce que rend await crew.run() — un CrewResult, exactement ce que déclare crew.d.ts : output, la dernière sortie d'agent qui n'était pas null, telle que le corps l'a rendue — la même valeur que le tasks[i].output de cette exécution, un objet restant un objet ("" quand aucun agent n'a rien rendu) — et tasks, une entrée { name, output, durationMs } par exécution d'agent, dans l'ordre où ils ont tourné, output étant ce que le corps a rendu. Rien de plus : aucune table artifacts. TypingsRuntimeParityTests compare les deux formes de résultat type par type.

process("graph") n'est pas stateGraph

Deux dispositifs différents qui partagent un mot. process("graph") exécute la crew sur la stratégie graphe du domaine : un nœud par tâche, enchaînés dans l'ordre d'exécution (un retry est le retry: de la tâche), avec un disjoncteur réglé par GraphConfig ; un fichier de crew peut aussi décrire ses nœuds et ses arêtes dans un bloc graph:, qu'un script n'écrit pas. stateGraph({ nodes, edges }) est la topologie que vous dessinez, et elle s'exécute quand vous appelez .run() dessus — depuis un .body() d'agent, donc en procédural.

crewBuilder() n'a pas de méthode graph(...) : process("graph") se construit seul, et un stateGraph ne tourne que par son propre .run().

taskBuilder()

Déclaratif uniquement — le moteur procédural ne lit jamais les tâches. Transmis à la crew : description, agent (un agent construit), expectedOutput, withContext(s) (c'est ce qui construit le DAG), tools (ajoutés aux outils de l'agent pour cette tâche seulement, sans jamais les remplacer), humanInput, asyncExecution, retry, deliverable, withResponseFormat(type), withResponseSchema(name, schema, strict?) et withProfile(nom) (le llm_override: { profile } du YAML : cette tâche seule tourne sur un des profils de l'hôte, sur le modèle propre de ce profil, et "default" la ramène au défaut de l'hôte ; un nom que l'hôte n'offre pas fait échouer le chargement en listant les profils connus). name est la clé de la tâche : when(...) et le state d'une décision désignent une tâche par elle, et une tâche de décision l'exige. Accepté mais sans effet : expect (consigné dans le contexte de la tâche en l'absence de deliverable, jamais validé).

decision(spec) fait de la tâche une tâche de décision : spec est un littéral d'objet { questions, minConfidence, state, longContext, fallback }, la forme du bloc YAML decision:. Elle n'a pas besoin d'agent, et une tâche qui a les deux est refusée au chargement. when(decisionTask, clauses) n'exécute la tâche que si la tâche de décision nommée a répondu comme demandé : clauses est un objet de clauses ({ category: ["bug"], urgency: ">= 0.7", "category.bug": ">= 0.25" }) ou la chaîne "otherwise" ; when() ne lève (une Error que le script rattrape) que pour un nom de tâche vide ou pour des clauses qui ne sont ni un objet ni une chaîne. Une chaîne autre que "otherwise", une question ou une option inconnue, ou une clause mal formée passe le builder et est refusée au chargement. Deux tâches de décision de même name dans un script sont refusées au chargement (Task '<name>' declares a decision twice.). state liste les tâches dont la sortie est l'état de la décision (par défaut : chaque dépendance qui a tourné) ; circuit désactivé, ou par --no-decision, la tâche répond par son fallback (voir Modèles de décision). Les tâches de décision et les conditions ne s'exécutent que dans les processus Sequential, Parallel et Graph. Un second .when() sur une tâche lève une Error qui nomme la tâche. Un state qui n'est pas un tableau, un fallback qui n'est pas un objet, et une valeur de choice, une entrée de score ou une valeur de fallback qui n'est pas une chaîne sont refusés au chargement, en nommant la tâche et la clé. Deux tâches de même name sont refusées au chargement. Une tâche sans .name() est identifiée par sa description complète ; la troncature n'est que l'affichage. Voir Modèles de décision.

asyncExecution() suit la règle du YAML : sous .process("sequential") la tâche tourne pendant les tâches qui la suivent, et une tâche qui la cite dans withContext l'attend ; sous .process("parallel") elle n'a pas d'effet propre ; sous les quatre autres modes la crew est refusée quand le run l'adapte, en nommant la tâche (voir Tâches asynchrones).

retry({ attempts, backoffMs?, backoff? }) est le bloc YAML retry: (voir Retry d'une tâche) : une tentative en échec rejoue la tâche entière, appels d'outils compris, jusqu'à attempts exécutions au total (au moins 1, obligatoire) ; backoffMs (défaut 0) et backoff ("fixed", le défaut, ou "exponential") règlent l'attente. Un attempts absent ou invalide, un backoffMs négatif, un backoff inconnu, ou un retry sur une tâche de décision lève une Error que le script rattrape à l'appel (ou à build() pour la tâche de décision). C'est le seul retry d'une crew .process("graph").

L'agent d'une tâche et les tâches de son withContext(s) sont ceux de la crew (withAgent(s), withTask(s)) : un agent ou une tâche que la crew ne tient pas est refusé quand le run adapte la crew, le message nommant la tâche, l'appel et ce que la crew a.

toolBuilder()

Les deux formes. name, description, withSchema, execute, access, build.

Le schéma n'est pas lu par le système de types : toolBuilder() sans argument de type donne à execute une entrée unknown, et tout accès de champ dessus est une erreur. Déclarez la forme que le schéma promet :

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();

Les globales

Trois noms que le runner échange avec le script, déclarés dans globals.d.ts.

Globale Sens Signification
crew script → runner Le handoff déclaratif. L'affecter est ce qui sélectionne le moteur déclaratif.
inputs runner → script Ce que --inputs / --inputs-file a analysé — ou l'input de script-host.runCrew(name, input) dans le REPL. Forme procédurale uniquement.
result script → runner Ce qu'un run procédural rapporte quand la valeur de complétion du script est undefined — ce qui est toujours le cas dès que le fichier a un await de premier niveau, puisqu'il s'exécute alors enveloppé dans une fonction async. Affectez-la sous la forme globalThis.result = … : un const result de premier niveau reste local à cette enveloppe. Sérialisé en JSON : un CrewResult passe entier — son output et un { name, output, durationMs } par agent sous tasks — et une projection simple n'affiche que ce qu'elle nomme. Non affectée, le run affiche {"result": null}.

ctx — le contexte d'agent

Forme procédurale uniquement ; rien sur le chemin déclaratif n'en construit un.

ctx.state porte l'unique mutateur légal, with(). Il remplace l'état par ce que le callback retourne, sous le mutex d'état de l'agent — portez donc les champs que vous ne changez pas :

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

Affecter directement (ctx.state.count = 1) lève StateMutationOutsideWithException. L'état est un Proxy JS dont le trap set existe pour rendre cela bruyant plutôt que perdu.

ctx.signal est un CancellationToken .NET projeté par interop, pas un AbortSignal du DOM — il n'y a pas de DOM dans Jint. Il porte IsCancellationRequested et CanBeCanceled, casse CLR ; aborted, addEventListener et throwIfAborted valent tous undefined. Transmettez-le (crew.run({ signal: ctx.signal })) plutôt que de l'interroger.

ctx.llm — complete(prompt), chat(messages), stream(prompt) (itérable async ; usage et reasoningChunks se lisent après la boucle, reasoning aussitôt), extract(prompt, schema), decide(prompt, choices), embed(text), act(prompt, opts), et interrupt() / isInterrupted. Chaque appel part vers le fournisseur de l'agent (celui de l'hôte, ou celui de son profil), ou vers le profil que nomme { llm: { profile } } ; sans fournisseur, un écho <undefined-llm:…> répond, ce qui permet aux exemples de tourner sans clé. Un appel prend ces options, toutes pour cet appel seulement : llm: { profile } le fait tourner sur le profil de l'hôte de ce nom (Llm:Profiles:<nom>) selon la règle de llm.profile(name) — un nom que l'hôte n'offre pas lève une Error que le script rattrape (un appel attendu la rejette), listant les profils connus (aussi dans llm.profiles), "default" est le fournisseur propre de l'hôte, et un profil de décision applique ses étapes à l'appel — et les autres corrigent la configuration du fournisseur de l'appel : responseFormat ("json_object", "json_schema", "text"), llm: { model } (un modèle par appel, dans le fournisseur du profil quand profile est donné : { profile, model } vaut llm.profile(profile, { model }) ; un LlmConfig y est refusé, sa température et son plafond de jetons ne s'appliqueraient pas) et effort ("low", "medium", "high", "xhigh" ou "max" : la réflexion du fournisseur, activée à cet effort ; toute autre valeur est refusée avec effort must be low|medium|high|xhigh|max) et cache (la demande de cache de prompt, telle que la prend agentBuilder().cache(...)). act en prend davantage : voir Options de act (tools, effort, onToolCall, onToolResult, onContextPressure, waitFor). Il n'y a ni fournisseur nommé, ni température, ni plafond de jetons par appel, et pas de signal — l'appel observe déjà celui du contexte. embed est un stub local : il n'appelle aucun fournisseur et ne lit aucune de ces options.

Ce que prend le modèle et ce que devient l'effort se lisent, sans se deviner (#359, #360). Un LlmConfig (llm.default_, llm.model("…"), llm.profile("…"), .with({...})) porte capabilities : { model, known, thinking, efforts }, thinking valant "none", "effortOnly", "toggle" ou "budget", et efforts les niveaux parmi low à max, dans l'ordre, que le fournisseur et le modèle prennent tous deux (vide quand le modèle ne prend aucun effort ou ne raisonne pas ; known: false quand la table des capacités n'a pas d'entrée, les niveaux du fournisseur s'appliquent alors sans vérification). Il porte aussi reasoning, comme les résultats de act et de chat et l'objet que rend stream() : { model, asked, sent, notice }, l'effort demandé (par l'effort de l'appel, agentBuilder().effort, .with({ effort }) ou le Llm:Thinking:Effort de l'hôte), l'effort envoyé (null quand aucun ne part) et notice, "lowered", "dropped", "unchecked" (un modèle que la table ne connaît pas) ou null quand il est parti tel que demandé ; reasoning vaut null quand aucun effort n'est demandé. Dans un agent, les appels de ctx.llm partent sur le fournisseur, le modèle et l'effort de l'agent, qu'aucun LlmConfig détenu par le script ne porte : ctx.llm.reasoning(opts) et ctx.llm.capabilities(opts) répondent pour l'appel que ces options désignent, jugé comme cet appel l'est (l'effort et le llm: { profile, model } des options compris), sans passer d'appel ; c'est le rapport que complete et extract ne peuvent pas porter, puisqu'ils rendent le texte ou l'objet seul. Les deux valent null sans fournisseur. Ils sont jugés avant l'appel : un profil de bascule répond pour son premier maillon et un profil de décision pour sa cible, si bien qu'un appel qui bascule, ou qu'une décision route vers un autre profil, peut être jugé autrement.

chat prend un tableau de messages nu ou { messages: [...] }. extract(prompt, schema, opts) prend les mêmes formes en premier argument, les tours de l'appelant envoyés dans l'ordre, en plus d'une chaîne de prompt ; ses options ajoutent system, envoyé en premier message avec l'instruction JSON ajoutée à sa suite, de sorte que le contenu utilisateur part intact. Sans system, l'instruction est ajoutée au prompt ou au dernier message utilisateur. Une relance porte la réponse refusée comme tour assistant :

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." });

Quand la réponse n'est pas du JSON, extract lève une erreur qui dit pourquoi : l'échec du fournisseur lui-même (ctx.llm.extract: the provider failed: …, avec le statut HTTP et le message du vendeur), une réponse vide (et, quand elle s'est arrêtée sur finish_reason: length ou max_tokens, que le budget de sortie est épuisé, raisonnement compris, en nommant le plafond avec lequel le modèle a réellement tourné : MaxTokens, sinon la limite résolue du modèle) ou une réponse qui ne se lit pas (la ligne et l'octet de l'erreur JSON, puis le début et la fin de la réponse). Chaque message porte la raison d'arrêt et les comptes de jetons de prompt, de complétion et de raisonnement que le fournisseur a donnés. decide lève l'échec du fournisseur de la même façon (ctx.llm.decide: the provider failed: …) au lieu de signaler une réponse vide. chat, comme complete, répond à un appel en échec par le marqueur <undefined-llm:…> qui porte la phrase du fournisseur, jamais par un contenu vide.

act est la boucle LLM ⇄ appels d'outils : elle propose au modèle les outils intégrés que l'agent a choisis avec .tools([...]) et ses instances withAutonomousTool — dont le execute s'exécute dans le script, sur le fil du moteur — jusqu'à ce que le modèle cesse de demander ou que maxIterations (défaut 10, 0 = illimité) soit atteint. Elle se résout en { output, iterations } (plus interrupted ou exhausted quand la boucle s'est arrêtée avant). Chaque appel d'outil d'un tour s'exécute, dans l'ordre, et le tour est rejoué dans le protocole d'outils du fournisseur — le tour de l'assistant avec ses appels, puis un résultat tool par appel, refus de permission ou erreur d'outil compris —, que le fournisseur réponde au format OpenAI (la plupart des fournisseurs, Ollama compris) ou avec le corps Messages d'Anthropic. Un résultat est coupé une fois, à la borne du framework (AgentDefaults.ResolveMaxToolResultLength : 4 000 caractères par défaut ; surcharges par outil : file_read 32 000, node_read 256 000, shell_command 10 000, et 12 000 pour les outils d'analyse qui répondent par un graphe ou une 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) : par le pipeline d'invocation d'outils de l'hôte quand il en a un, par act sinon. Un tour en échec chez le fournisseur résout output en <undefined-llm:<l'erreur du fournisseur>>, comme complete. Un appel qu'une étape du profil de décision de l'hôte bloque n'est pas une panne du fournisseur : complete, chat, extract, decide, act et une itération de stream rejettent par une DecisionBlockedError (errorType: "DecisionBlocked", profile, stage, risk pour une étape guard, reason), et une équipe peut dire à l'utilisateur quelle étape a refusé la requête ; non interceptée, elle fait échouer le run avec la DecisionBlockedException. Un nom de .tools([...]) auquel aucun outil de l'hôte ne répond (comparaison insensible à la casse) n'est pas sauté : act rejette par une UnknownToolError (agentName, toolNames, availableTools) avant tout appel au modèle — le pendant procédural de l'échec de chargement que la forme déclarative obtient pour le même nom ; un handler onError la lit comme validation. ActOptions.system sème un vrai message role:"system" qui persiste à chaque itération ; sans lui, act() envoie un seul message utilisateur. ActOptions.context sème un message utilisateur à part entre system et le prompt : le prompt reste le dernier message utilisateur, la requête que jugent les étapes guard et route d'un profil de décision, si bien que le contexte n'en dilue pas le risque. permissionMode (default, acceptEdits, bypassPermissions, plan, dontAsk) est vérifié auprès de la porte de permissions de l'hôte à chaque appel d'outil, quand l'hôte en a enregistré une : un appel pour lequel le mode demande attend l'opérateur quand l'hôte a un canal d'approbation (orkeon-repl en a un), et il est refusé sinon ; le temps que la porte met à décider ne compte ni dans ExecutionTimeout, ni dans le budget de temps mural de l'agent (.budget({ wallTime })). ctx.llm.permissionGate.enabled dit si l'hôte a enregistré une porte ; sans elle, un permissionMode ne contrôle rien et l'appel journalise un avertissement qui le dit — déclarez .access("read") sur un outil de script pour qu'il passe plan ; onDelta reçoit le texte streamé de chaque tour de l'assistant, et onToolCallDelta chaque fragment d'appel d'outil que le modèle est en train de construire ({index, id?, name?, argumentsDelta} ; id et name viennent sur le fragment qui les porte, et Ollama envoie un appel entier). Sur un hôte qui a enregistré la DLP, les arguments d'un appel arrivent retenus, en un seul fragment rédigé, une fois l'appel terminé.

ctx.delegate(agentOuNom, input) est crew.runAgent : la cible s'exécute avec son propre contexte, sous son sémaphore et sa politique onError. Ni l'un ni l'autre ne donne de budget à l'exécution sans qu'on le demande : ctx.delegate(agent, input, { budget: { toolCalls: 20, tokens: 50000, wallTime: 300 } }) (et le même budget dans les options de crew.runAgent) borne cette exécution avec les clés et valeurs de crewBuilder().budget(...) (toolCalls, tokens, contextTokens, wallTime en secondes ou sous la forme "5m", delegationDepth, spawnedAgents). tokens est une somme courante du prompt et de la complétion de chaque appel, le contexte compté de nouveau à chacun. contextTokens compte le contexte une fois : la complétion de chaque appel plus la part de son prompt que le cache n'a pas servie quand le fournisseur rapporte des hits de cache, sinon ce dont le prompt a crû depuis l'appel précédent de la même conversation (chaque ctx.llm.act la sienne), si bien qu'un tour de n appels sur un contexte de c tokens dépense environ c plus ses complétions, pas n × c ; seul, il laisse tokens sans plafond, et une crew autonome déclarative le refuse. Une fois l'un ou l'autre atteint, ctx.llm.act fait un dernier appel qui ne peut appeler aucun outil et se résout avec budgetExhausted: true (le budget de tokens d'act). Une dimension épuisée termine l'exécution par BudgetExhaustedError, l'erreur que donne le budget d'une crew, et un enfant qu'elle lance (spawn_agent, ctx.spawnBackground) dérive son budget du sien. Une clé inconnue, un compte qui n'est pas un entier d'au moins 1 ou un wallTime illisible est refusé à l'ouverture de l'exécution, là où le crewBuilder().budget(...) procédural l'ignore. charge: "crew", à côté de budget, compte ce que l'exécution dépense (appels d'outils, tokens, enfants ; son horloge murale court avec celle de l'appelant) aussi sur le budget de l'exécution d'où elle est appelée — celui de la crew, depuis un body d'agent de crew.run — si bien que des exécutions lancées ensemble ne dépensent jamais plus que la crew ne le permet. Un appel que le budget propre de l'exécution refuse n'est pas imputé, et les enfants qu'elle lance sont imputés aussi, chacun borné par ce qui reste aux deux budgets. Sans budget, l'exécution dépense directement sur celui de l'appelant, et elle est refusée quand l'appelant ne tourne sous aucun budget. ctx.delegate charge le budget de son propre contexte. crew.runAgent ne peut pas nommer le body d'où il est appelé : il charge l'unique budget sous lequel tournent tous les body d'agent ouverts, et il est refusé quand des body sous des budgets différents sont ouverts (un fan-out à côté d'une exécution déléguée budgétée) ; appelez alors ctx.delegate depuis le body. crew.run et crew.runStream ignorent les deux clés. ctx.send(agentOuNom, message), receive({ timeout }) et broadcast(message) échangent des messages ; send et broadcast sont synchrones. ctx.crew est une vue en lecture seule de la crew (name, findByName, findById, findByRole, has, lock(name, fn)). ctx.log.info(message, ...args) joint les arguments supplémentaires par une espace, les objets en JSON. Et aussi ctx.memory (crew, et agent dans un body d'agent), ctx.events, ctx.lock(name, fn), ctx.spawn. ctx.spawnBackground(agent, input) démarre un agent de la crew comme enfant et rend son ticket ; ctx.instanceId est l'id de l'instance d'agent dont un body est l'exécution ; ctx.fileSystem.prompt est la section ## File system que porte un tour déclaratif de l'agent (le système de fichiers dans le prompt), que le corps place dans son propre prompt system ; crew.instances(), crew.send(id, message) et crew.stop(id) listent, interrogent et arrêtent les instances gardées (Instances d'agents). Voir context.d.ts.

Un échec côté hôte parvient au script comme une instance de la classe que déclare errors.d.ts — try { await q.pop({ timeout: 100 }) } catch (e) { if (e instanceof ReceiveTimeoutError) … } — avec les champs de cette classe (agentName, timeoutMs…), plus clrType (le nom du type .NET) et clr (l'exception). Un échec sans classe déclarée est un simple Error qui porte ces deux mêmes propriétés. Une méthode de builder ou de fabrique qui refuse son argument — agentBuilder().effort("turbo"), un build() auquel manque un champ, un littéral stateGraph(...) à la topologie fautive, llm.profile("ghost") — lève une InvalidScriptError (clrType "InvalidScriptException") que le script rattrape, et un appel ctx.llm.* attendu refusé de la même façon est rejeté avec elle : le message nomme la faute, si bien qu'un script qui construit à partir de données teste e instanceof InvalidScriptError et se rabat sur une valeur par défaut. Une valeur au-delà d'une limite du domaine reste un simple Error, de clrType "ArgumentException", tout comme un délai ErrorAction.retry hors bornes ("OverflowException"). Les limites propres du moteur (temps, mémoire, récursion) ne sont pas des refus : elles arrêtent le script quoi qu'il rattrape. Un gestionnaire onError reçoit { code, message, exception, attempt, agent: { id, name } } et le contexte ; code vaut rate_limit, network, timeout, receive_timeout, state_mutation, agent_not_in_crew, validation, decision_blocked ou unknown.

Les espaces de noms

Globale Ce qu'elle contient
llm Les réglages de modèle que prend agentBuilder().llm(...) (forme déclarative). llm.default_ — une valeur, pas une fonction — est le fournisseur de l'hôte sur son modèle configuré (un model vide quand l'hôte n'en configure aucun : l'agent tourne alors sur le modèle par défaut de ce fournisseur, jamais sur celui d'OpenAI), ou l'écho <undefined-llm> quand l'hôte n'en a pas ; llm.model(name, overrides?) est le même fournisseur sur un autre modèle ; llm.profile(name, overrides?) est l'un des profils nommés de l'hôte (Llm:Profiles:<nom>) sur son propre modèle — un agent configuré avec lui fait ses tours et ses appels ctx.llm sur ce fournisseur, et un nom que l'hôte n'offre pas lève une Error que le script rattrape (try … catch), qui liste les profils connus ("default" est llm.default_) ; llm.profiles est cette liste, un tableau gelé de noms — "default" d'abord, puis les profils de l'hôte dans l'orthographe qu'il a déclarée, jamais une adresse ni une clé — pour qu'un script vérifie un nom avant de le demander, sans tenir compte de la casse comme llm.profile. with({ model, temperature, maxTokens, responseFormat, effort, cache }) rend une copie, garde le profil et refuse toute autre clé. Il n'y a pas de fabrique par vendeur : un script choisit parmi les fournisseurs que l'hôte a configurés, par nom de profil.
tools Les outils intégrés de l'hôte, appelés depuis un body : tools.fileRead({ path }), le nom snake_case passé en camelCase. tools.generated.d.ts déclare l'entrée et le résultat de chaque outil intégré qu'un run enregistre, écrits depuis ses records de requête et de réponse (les clés snake_case de l'outil : tools.fileRead({ path, max_length })), si bien qu'un paramètre mal orthographié échoue au contrôle de types ; tools.d.ts déclare à la main les familles e-mail et drive. Un outil de plugin ou MCP s'atteint de la même façon, sans type.
rag rag.ingest({ collection, sources, chunkingStrategy?, reindex?, prune? }), rag.query(question, { collection, profile?, topN? }) (une réponse ancrée avec citations) et rag.retrieve(...) (les mêmes passages, sans génération). Demande un hôte qui a enregistré le sous-système RAG (AddOrkeonRag) ; liée dans orkeon run, le REPL et l'hôte daemon.
test Seulement sous orkeon run --test : les mocks et assertions du script (plus bas).
ErrorAction Les fabriques qu'un gestionnaire onError retourne : fail(), skip(), fallback(value), retry({ delay?, max? }). Tout le reste vaut fail().
stateMachine, stateGraph, START, END Ci-dessous.

L'espace de noms test (orkeon run --test)

orkeon run --test lie le global test (déclaré dans Typings/test.d.ts) ; sans le drapeau, un script n'en a pas, et s'y référer est une ReferenceError. Sous le drapeau, le modèle configuré par l'hôte — ou le fichier de --llm-mock — reste derrière le mock : un prompt que couvre une attente de test.mockLlm reçoit sa réponse, tout autre prompt va au fournisseur configuré. Un seul mock est partagé par ctx.llm, les crews du script, l'espace de noms et les fournisseurs de llm.profile("…") : une attente enregistrée dans le script est celle que rencontre un appel, quel que soit le profil.

test.mockLlm.when("météo").respond("ensoleillé");      // un texte à chercher, ou { prompt: /regex/ }
test.mockTool("lookup").when({ city: "Paris" }).respond({ temp: 21 });

await crew.run();
test.assertLlmCalled({ times: 1, with: "météo" });
test.assertToolCalled("lookup");

Depuis .NET, MockLlmProvider et MockTool (Orkeon.Scripting.Testing) prennent les mêmes attentes par When(string | Regex).Respond(...) ; TestOverrideLlmProvider est le fournisseur qui les place devant un fournisseur configuré.

Une assertion en échec est aussi une Error (clrType "AssertionException"), comme un mock refusé (test.mockTool(""), un { prompt: /regex/ } que .NET ne sait pas lire) : un try … catch qui rattrape tout l'avale, donc relancez ce que le catch ne traite pas.

stateMachine et stateGraph

Les deux sont pilotés par littéral.

stateMachine prend { name, initial, states }. Les transitions vivent dans chaque état, indexées par nom d'événement, et le champ de destination est 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");   // résout vers le NOUVEL état

send(event, payload?) rend l'état où la machine a abouti — c'est-à-dire l'état courant, inchangé, quand l'événement lui est inconnu ou qu'un garde a refusé. Un événement inconnu n'est pas une erreur. Une transition peut porter un guard (rendre false l'interdit) ; un état peut porter onEntry et onExit, qui reçoivent { state, payload }. La machine expose name et current. Il n'y a pas de méthode run() ni d'option circuitBreaker.

stateGraph prend { name, nodes, edges, graphConfig? }. edges est un objet indexé par nœud source, pas une liste de paires, et START/END sont de simples chaînes ("__START__") :

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

Une arête est un nom de nœud, END, ou une fonction de l'état qui en rend un (une arête conditionnelle). graphConfig borne chaque run(state) : circuitBreakerPreset (Strict, Default, Permissive) ou les bornes individuelles maxTransitions, maxStateVisits, maxRetryCycles (le budget propre au graphe de script : le compte, sur tout le run, des entrées dans un nœud déjà entré une fois, gardé pour la parité de budget des deux moteurs ; ce n'est pas un retry de tâche, qui est le retry: de la tâche) et maxTotalDurationSeconds — dépasser un compte lève une erreur, manquer de temps annule le run. runStream(state) produit chaque saut ({ fromNode, toNode, state }) pour un for await.

stateGraph(...) vérifie la forme du graphe à sa construction, avec le validateur que partagent le moteur du Domain et le graphe d'une crew (ADR-018), et signale toutes les fautes dans une seule InvalidScriptError que le script rattrape : une arête depuis ou vers un nœud non déclaré, un nœud sans arête sortante, un nœud que rien n'atteint (un orphelin), aucun chemin de START à END, un nœud qui ne peut pas atteindre END. Une arête fonction ne se lit pas avant de s'exécuter : on suppose qu'elle peut mener n'importe où, END compris. Chaque fois que la boucle entre dans un nœud, un événement graph.node.entered part vers l'hôte (orkeon run --events jsonl l'écrit).

Défauts, quand graphConfig est absent : 200 transitions, aucune borne sur les visites d'un nœud, aucune borne sur les revisites (maxRetryCycles) et aucune borne de durée ; un circuitBreakerPreset remplace les quatre. (Le moteur du Domain seul prend la politique Strict, 50 transitions et 5 visites, et un CircuitBreakerPolicy nu vaut 100 et 10 : les défauts diffèrent selon le moteur et restent tels quels.) maxStateVisits est le MaxStateVisits du Domain : un nœud entré plus souvent déclenche le disjoncteur. maxRetryCycles compte, sur tout le run, les entrées dans un nœud déjà entré une fois ; sur un graphe qui boucle sur un seul nœud, maxRetryCycles: k et maxStateVisits: k + 1 sont la même borne (le nœud s'exécute k + 1 fois, l'entrée suivante lève), ce que GraphBudgetParityTests fixe sur les deux moteurs. Avec plusieurs nœuds, c'est une autre borne, globale au run.

TState ne peut pas être inféré depuis les corps de nœuds — un nœud prend et rend l'état, l'inférence est donc circulaire — et retombe sur Record<string, unknown>. Annotez l'appel (stateGraph<OrderState>({...})) pour qu'un nœud rendant la mauvaise forme soit signalé.

Limites de conception

Les déclarations et le runtime C# sont écrits dans deux langages. Deux garde-fous les relient : scripts/check-scripting-typings.sh vérifie le typage de chaque .ork.ts de examples/ contre les typings, et un test de parité (TypingsRuntimeParityTests) compare, membre par membre, chaque interface déclarée au type du runtime qui la porte. Il ne reste aucun écart entre les deux ; ce qui suit, ce sont des limites de conception, chacune dite plutôt que silencieuse.

Limite Comportement
budget() en forme déclarative Le budget de la crew quand le process est "autonomous", le seul process qui le dépense (clés toolCalls, tokens, delegationDepth, spawnedAgents, wallTime ; contextTokens y est refusé, la stratégie comptant les tokens de chaque tâche terminée, pas le prompt de chaque appel). Avec un autre process, la crew est refusée quand l'exécution l'adapte, l'erreur nommant le process.
.body() en forme déclarative Ignoré, et dit : l'exécution journalise un avertissement qui nomme l'agent. La confusion la plus coûteuse du DSL, et la raison du tableau des formes ci-dessus.
globalThis.inputs en forme déclarative Jamais planté. Passer --inputs, --inputs-file ou --memory-limit-mb à un script déclaratif affiche un avertissement sur stderr au lieu de perdre l'option en silence.
ctx.llm.embed Rend un vecteur bidon déterministe, pas un vrai embedding.
concurrency(n) avec n > 1 Rejeté au build avec un message clair : la concurrence d'un agent est un mutex. Bruyant, pas silencieux.
Les locks n'ont pas de timeout Il n'existe pas de LockTimeoutError.
Les événements En mémoire seulement ; pas de persistance Redis/NATS.
Composition FSM/Graphe Ni sous-états ni sous-graphes.

Inclusion conditionnelle

La seule construction conditionnelle est when(decisionTask, clauses) sur un builder de tâche, qui exécute la tâche selon les réponses d'une tâche de décision à l'exécution (voir decision(spec) plus haut). Il n'y a pas de prédicat qui inclut ou exclut un agent ou une tâche à la construction du script.

Gardez l'appel :

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

Réglage de l'éditeur

Lancez orkeon typings dans votre projet : il écrit orkeon.d.ts (ce DSL) et orkeon-cli.d.ts (les commandes *.cmd.ts du REPL) dans ./.orkeon/ — --out <dossier> en choisit un autre — et les écrase, relancez-le donc après une mise à jour de l'outil. Chaque script commence alors par /// <reference path="./.orkeon/orkeon.d.ts" /> (chemin relatif au script). Les fichiers viennent de l'outil lui-même : ils décrivent le runtime qui exécutera vos scripts. Dans un clone, les sources sont src/scripting/Orkeon.Scripting/Typings/*.d.ts, concaténées par le build dans bin/<configuration>/net10.0/dist/orkeon.d.ts sous ce projet.

Pour figer les typings d'une release, ou en comparer deux, prenez-les sur la Release plutôt que sur l'outil installé : chaque Release GitHub joint orkeon-typings-<version>.tar.gz, les deux mêmes fichiers que orkeon typings écrit, pris sur le build de cette release. Il figure dans le SHA256SUMS de la release et il est attesté comme les autres archives (gh attestation verify, voir Vérifier ce que vous installez) :

VER=<version>    # le tag sans son 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
# entre deux versions, extrayez chacune dans son dossier puis :  diff -r typings-A typings-B

Quand une Release ne le porte pas, orkeon typings en est la source. Copiez ensuite tools/scripting-typecheck/tsconfig.base.json, qui est la configuration qu'utilise le garde-fou du dépôt lui-même.

Trois de ses options portent tout le poids :

  • moduleDetection: "force" — sans elle, un await crew.run() au niveau supĂ©rieur est rejetĂ© (TS1375) et un const crew au niveau supĂ©rieur entre en collision avec la globale crew (TS2451). Deux erreurs qui n'ont rien Ă  voir avec votre code.
  • target/lib ES2022 — ce que Jint supporte. Demander plus promet des API absentes ; le DOM en particulier n'existe pas, d'oĂą le fait que ctx.signal n'est pas un AbortSignal.
  • types: [] — il n'y a pas de Node dans un .ork.ts. process, require et Buffer n'existent pas Ă  l'exĂ©cution et ne devraient pas exister Ă  l'Ă©criture non plus.

OĂą aller ensuite