Table of Contents

🇬🇧 English version

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, CreatedAt remis à 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