🇬🇧 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, unawait crew.run()au niveau supérieur est rejeté (TS1375) et unconst crewau niveau supérieur entre en collision avec la globalecrew(TS2451). Deux erreurs qui n'ont rien à voir avec votre code.target/libES2022— ce que Jint supporte. Demander plus promet des API absentes ; le DOM en particulier n'existe pas, d'où le fait quectx.signaln'est pas unAbortSignal.types: []— il n'y a pas de Node dans un.ork.ts.process,requireetBuffern'existent pas à l'exécution et ne devraient pas exister à l'écriture non plus.
OĂą aller ensuite
- Écrire une crew en TypeScript — le guide.
- DSL de scripting — architecture — ce qu'est le runtime et où il se situe.
- Commandes CLI en TypeScript — le plan de contrôle
.cmd.ts. - Piloter des crews depuis le REPL — le pont
.cmd.ts→crew.ork.ts.