Piloter des crews depuis le REPL — le pont .cmd.ts → crew.ork.ts
Une commande scriptée est un plan de contrôle : elle analyse ce que vous avez tapé et
décide de ce qui doit arriver. Une crew est un moteur : elle fait le travail. La couture
entre les deux est le service script-host, et cette page documente cette couture — le motif
derrière un assistant de codage agentique bâti sur la pile scriptée d'Orkeon, où des commandes
*.cmd.ts (Orkeon.Cli.Commands.Scripting) pilotent des crews crew.ork.ts
(Orkeon.Scripting) au-dessus des outils C# ToolBase.
Tout ce qui suit est livré et exécutable depuis un clone. La section
## Exécution en fin de page le lance.
Architecture : plan de contrôle vs moteur
REPL (Orkeon.ConsoleApp --runner=scripted-commands)
│ parses "/cmd args" + free text
▼
*.cmd.ts (Orkeon.Cli.Commands.Scripting) ══ CONTROL PLANE ══
defineCommand (sync) / defineAsyncCommand (async) never does the work itself
│ │ │
│ tools.* (direct ops) │ services.get("script-host")│ services.get("commands")
▼ ▼ .runCrew / .runCrewAsync ▼ .request / .post
ops thin ══ ENGINE: crew.ork.ts ══ living agent .onCommand(env)
/hello /crews ScriptHost.RunFromFileAsync (lightweight reply, no ctx)
.body() / ctx.llm.act / budget
│ tools.<camelCase>(params)
▼
C# tools (IBaseTool / ToolBase)
│
ISessionBufferService · ICategoryMemoryStore · ICostBudgetManager
La règle que ce schéma encode : le registre de commandes est un plan de contrôle, pas un
moteur de concurrence. Tout le TypeScript tourne dans Jint — mono-thread, avec une boucle
d'événements mais sans timers — donc une commande, synchrone ou asynchrone, ne fait jamais le travail long
elle-même. Elle parle à un moteur côté hôte au travers de la whitelist de services, et
script-host est ce moteur pour les crews. Le versant dispatch de la même règle est dans
Commandes CLI en TypeScript.
Le service script-host (pont cmd → crew)
ctx.services.get("script-host") expose ScriptHostFacade :
| Méthode | Sémantique |
|---|---|
runCrew(name, input?) |
Charge <crews-dir>/<nom>/crew.ork.ts, l'exécute via ScriptHost.RunFromFileAsync (honore .body() + ctx.llm), attend, rend un CrewRunOutput ({ ok, summary?, artifacts?, streamed, error? }). Crews courtes : l'attente est bornée par RunCrewTimeout (ci-dessous), au-delà de quoi le script reçoit une TimeoutException. |
runCrewAsync(name, input?, options?) |
Poste l'exécution sur un thread du pool et rend un ticket immédiatement. La complétion est drainée vers le completed(result) d'un defineAsyncCommand, par le même cycle de tickets que commands.post. Workflows longs. options accepte { chain: "continue" }, { onMain: true } (la crew devient la conversation) et { exclusive: true } (refusé tant qu'un autre lancement exclusif de la même crew tourne : crew 'x' already running (ticket tN)), décrits dans Commandes TypeScript du CLI. |
listCrews() |
Les noms de crews découverts. |
Une crew inconnue n'est pas une exception : runCrew rend ok: false avec
crew '<nom>' not found under: …. runCrewAsync a besoin du substrat de dispatch
qu'enregistre AddScriptCommands, et lève une erreur sans lui.
ScriptHost exécute le fichier en procédural : une crew qui se termine par
globalThis.crew = crew n'est pas confiée ici à un orchestrateur, elle est exécutée comme
await crew.run() l'exécuterait — .body() exécutés, tâches ignorées
(les deux formes). Écrivez en forme
procédurale les crews que ce pont lance.
Une crew se résout par son nom dans les répertoires donnés à l'hôte : --crews-dir est
répétable, chaque répertoire est monté en lecture seule comme /crews, /crews-1, …
(CliCrewMountBootstrapper), et la crew nommée review est le fichier
<dir>/review/crew.ork.ts ; le premier répertoire qui l'a l'emporte. input arrive dans la
crew comme globalThis.inputs, un objet JS analysé depuis du JSON avant l'évaluation, par le
hook de pré-exécution de ScriptHost, et le globalThis.result de la crew revient comme
summary (une chaîne telle quelle, tout le reste sérialisé en JSON).
La même résolution se configure sous Orkeon:Cli:ScriptHost (ScriptHostFacadeOptions) :
| Clé | Défaut | Rôle |
|---|---|---|
CrewDirectories |
vide | Répertoires virtuels parcourus dans l'ordre ; --crews-dir s'y ajoute. |
CrewFileName |
crew.ork.ts |
Le fichier d'entrée cherché sous <dir>/<nom>/. |
RunCrewTimeout |
00:10:00 |
Borne d'un runCrew synchrone ; zéro ou négatif la désactive. |
Une boucle d'agent dans une crew — ctx.llm.act
Un agent interactif est un agent dont le .body() est la boucle : il appelle
ctx.llm.act(prompt, opts), qui déroule le cycle LLM ⇄ appels d'outils sur le catalogue
d'outils de l'agent, jusqu'à ce que le modèle cesse de demander des outils ou que
maxIterations soit atteint (src/scripting/Orkeon.Scripting/Typings/context.d.ts, act<T>
et ActOptions). Les outils proposés au modèle sont les outils intégrés que l'agent a choisis
avec .tools([...]). Il se lance comme une crew — runCrewAsync(name, { prompt, permissionMode }),
la crew transmettant inputs.permissionMode à act — et non par onCommand, qui n'a pas
de ctx et ne peut donc pas atteindre le LLM. La continuité de la
conversation entre exécutions vient du singleton ISessionBufferService.
ActOptions.system sème un vrai message role:"system" devant le prompt utilisateur, et
il persiste à chaque itération de la boucle d'outils. Sans lui, act() envoie un seul message
utilisateur : l'identité et la politique d'outils voyagent avec l'autorité d'un utilisateur, et
la gestion native du system des fournisseurs (Anthropic system au premier niveau,
cache_control) ne se déclenche jamais. Un message system au niveau conversation
l'emporte sur LlmConfig.SystemMessage chez tous les fournisseurs.
ActOptions.context sème le contexte du tour (mémoire, état du dépôt, tours précédents) comme
un message utilisateur à part, après system et devant le prompt. Le prompt reste le dernier
message utilisateur, celui que jugent les étapes guard et route d'un profil de décision : le
contexte ne peut pas diluer le risque de la requête ; et system reste le même d'un tour
à l'autre, ce qui garde son accès au cache de prompt.
Appels d'outils en lecture, en parallèle. Les appels d'outils d'un même tour du modèle qui
sont de classe lecture — l'outil déclare l'Access Read et son nom figure sur la liste
d'autorisation explicite (file_read, directory_read, directory_search, count_pattern,
glob, grep, rag_search, codebase_*, symbol_*, index_status, node_outline,
node_read ; la session shell n'y figure pas) — s'exécutent en parallèle, dans la limite de
MaxParallelToolCalls (4 par défaut) de
Orkeon:Tools:ResultLimits. Un appel d'écriture, ou dont l'accès est Unspecified, est une
barrière : une lecture placée après lui l'attend et voit son effet. Les résultats, et les messages
d'outil renvoyés au modèle, gardent l'ordre des appels. Hooks : pour chaque groupe parallèle,
onToolCall s'exécute d'abord pour toutes les lectures (séquentiellement, dans l'ordre des
appels, sur le fil du moteur), puis les exécutions, puis onToolResult dans l'ordre des appels ;
aucun callback ne s'exécute jamais en même temps qu'un autre. Quand un appel frère échoue, est
annulé ou lève BudgetExhaustedException, les autres vont à leur terme et sont consignés, et la
première erreur est relancée après le groupe. Dans un hôte qui enregistre le canal par
AddConsoleToolApproval, les approbations que demandent les lectures concurrentes sont
sérialisées (SerializingToolApprovalChannel) ; orkeon-repl enregistre son canal directement :
deux questions concurrentes n'y sont pas mises en file une à une
(Limitations connues). Les boucles natives d'une crew YAML et le dispatcher de chat se
déploient de la même façon ; les sites en repli texte (le chemin texte de ChatToolDispatcher et
LegacyTextAgentLoop) restent séquentiels.
Permissions et budget
Le garde de permissions est un service DI de premier rang, IPermissionGate
(Orkeon.Application.Interfaces.Security) implémenté par ModePermissionGate
(Orkeon.Infrastructure.Security), consulté à chaque appel d'outil dans ctx.llm.act. Cinq
modes (bypassPermissions, plan, acceptEdits, default, dontAsk), classification
lecture/écriture depuis la déclaration IBaseTool.Access de l'outil lui-même (avec une table
d'outils de lecture curée et les préfixes codebase_/symbol_/index_ en repli), fermeture
par défaut sur un outil inconnu et sur un mode inconnu. Dans orkeon-repl, un appel pour lequel
le mode demande est soumis à l'opérateur (y une fois, s pour la session, n non) par le canal
d'approbation du REPL ; un appel que le mode refuse, ou que l'opérateur refuse, revient au modèle
en DENIED: …, réponse de l'outil. Un hôte sans canal refuse les demandes. Le tout est derrière
Orkeon:Security:PermissionGate:Enabled (défaut false), câblé par le REPL
et RunnerHost (AddOrkeonPermissionGate), sans effet quand c'est désactivé. Dans la TUI,
Maj+Tab fait tourner le mode par défaut de la session. Voir
les sous-systèmes opt-in.
Le budget est l'autre borne : process("autonomous") plus .budget({...})
(AgentExecutionBudget, cinq dimensions).
Les primitives de session
Trois ports portent ce qu'une conversation doit conserver entre deux exécutions :
ISessionBufferService(singleton) — le tampon de conversation : messages, métadonnées, troncature tête+queue, estimation de tokens. Pivot de la boucle et des commandes de session.ICategoryMemoryStore— CRUD mémoire typé sur quatre catégories (user/project/feedback/reference) :ListAsync(category, newestFirst),AddAsync(renvoie l'id),ReplaceAsync(id, content)(même id et même catégorie,CreatedAtremis à jour),DeleteAsync,GetAsync.ICostBudgetManager— télémétrie cumulée coût/tokens/appels.
Session durable et script de démarrage
Dans le REPL, la session survit à un redémarrage. Avec Orkeon:Cli:Session:Persist activé (valeur par
défaut du REPL quand la clé est absente), FileSessionBufferService décore le tampon en mémoire et
conserve la dernière session de chaque projet — messages, état, identifiant et titre — dans
<SessionsDirectory>/<projet>-<hash>/last.json via IFileSystemService. Le projet est la racine
physique de l'espace de travail que le REPL monte en /workspace ; le fichier est lu une fois au
démarrage, réhydraté sans revalidation, et écrit après chaque tour et à la sortie du REPL. Un fichier corrompu démarre une
session vide. session_store lit le tampon réhydraté comme n'importe quel autre.
La mémoire typée de memory_store survit de la même façon. Avec Orkeon:Cli:Memory:Persist activé
(valeur par défaut du REPL quand la clé est absente), FileCategoryMemoryStore conserve les entrées de
chaque projet dans <Orkeon:Cli:Memory:RootDirectory>/<projet>-<hash>/memory.json — le même slug de
projet que le fichier de session, les deux sont donc côte à côte. Le fichier est lu au premier accès et
écrit après chaque add, replace ou delete ; l'id suivant est écrit avec les entrées, un id n'est
donc jamais réutilisé après une suppression. Désactivé, InMemoryCategoryMemoryStore garde les entrées
le temps du processus.
Orkeon:Cli:Session:StartScript désigne un script exécuté une fois, l'hôte construit : un .ork.ts
via l'hôte de scripts, tout autre fichier comme script shell. Sa sortie standard, son chemin et sa
source sont stockés dans l'état sous SessionStateKeys.SessionStartOutput et placés avant le premier
tour en texte libre, de sorte qu'un script de démarrage puisse nommer le travail en cours. Un script en
échec est journalisé et ne bloque jamais le démarrage.
AddOrkeonSessionTools() les expose aux scripts sous forme de six outils — session_store,
session_snip, token_budget, memory_store, session_cost, session_stats — catalogués
avec les autres dans l'inventaire des outils. ISessionBufferService.Truncate,
derrière session_snip et l'opération truncate de session_store, compte des tours, pas des
messages : un tour commence à un message user et possède les messages tool, assistant et note
qui le suivent, de sorte qu'une coupe ne sépare jamais une requête de sa réponse ni une trace d'outil
de la réponse qui l'a utilisée. Il répond un SessionTruncation (RemovedCount, KeptFromIndex,
qui pointe toujours un message user ou vaut -1), et un buffer qui contient moins de tours que demandé reste intact.
Les outils dans les commandes (tools.* dans .cmd.ts)
Chaque moteur que construit JsEngineFactory porte l'espace de noms tools, et la factory de la CLI est
construite avec les outils intégrés et le fournisseur LLM : tools.<camelCase>(params)
fonctionne donc dans un handler .cmd.ts exactement comme dans une crew. C'est ainsi qu'une
commande fait elle-même un petit travail plutôt que de payer une crew — lire un fichier,
mettre en forme un rapport — pendant que tout ce qui est long passe par script-host.
Exécution
Deux répertoires, deux rôles. --commands-dir charge le plan de contrôle, --crews-dir
fournit les moteurs. Les deux pointent vers du matériel livré dans ce dépôt, et aucun ne
demande de clé d'API :
# Le plan de contrôle seul — les commandes de démonstration du dépôt
dotnet run --project src/apps/Orkeon.ConsoleApp -- \
--runner=scripted-commands \
--commands-dir examples/cli-ts-commands
# Le pont — des commandes qui lancent une crew par son nom via script-host
dotnet run --project src/apps/Orkeon.ConsoleApp -- \
--runner=scripted-commands \
--commands-dir examples/cli-ts-commands \
--crews-dir examples/cli-ts-commands/crews
scripted> /crews
review
scripted> /review src/Program.cs
src/Program.cs: source file — worth a read
scripted> /review-bg examples/README.md
✓ [t1] review-bg → crew:review: done
✓ review: examples/README.md: not a source file — skipped
La crew de démonstration n'appelle aucun modèle, d'où l'absence de clé ; pointez le .body()
d'un agent sur ctx.llm.act et le même pont en porte une vraie. Sans le REPL, une crew
s'exécute directement depuis la CLI :
dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run examples/scripting/01-hello-world.ork.ts
Le pont lui-même est couvert par ScriptHostFacadeTests, dans
tests/cli/Orkeon.Cli.Commands.Scripting.Tests/, qui exerce la résolution de crew et le cycle
de tickets sans clé.
Où aller ensuite
- DSL de scripting — architecture : ce qu'est le runtime
.ork.tset où il se situe. - Commandes CLI en TypeScript : le plan de contrôle en entier —
defineCommand, schémas d'arguments, dispatch vers les agents. examples/cli-ts-commands/: la source de la session ci-dessus.