Table of Contents

🇬🇧 English version

Commandes CLI TypeScript

Référence utilisateur du sous-système Orkeon.Cli.Commands.Scripting. Pour la spécification d'architecture et la justification de conception, voir l'archive de conception des mainteneurs (feature cli-ts-commands, SPEC).

De quoi s'agit-il

Un moyen d'ajouter des commandes REPL interactives à un runner CLI Orkeon en déposant des fichiers *.cmd.ts dans un dossier — pas de recompilation .NET, pas de redémarrage de l'hôte au-delà du runner lui-même. Chaque script déclare une ou plusieurs commandes via le helper global defineCommand({...}) ; le chargeur les détecte au démarrage, les valide, et les expose aux côtés des commandes intégrées help/exit/clear.

Les commandes peuvent aussi dispatcher du travail vers des agents vivants — en synchrone (bloquer et retourner la réponse) ou en asynchrone (émettre un ticket, réagir quand l'agent répond). Voir Dispatcher des commandes vers des agents.

Démarrage rapide

mkdir -p ./commands
cat > ./commands/hello.cmd.ts <<'EOF'
defineCommand({
  name: "hello",
  description: "Say hello to the world (or to someone in particular).",
  args: {
    who: { type: "string", default: "world" },
  },
  async handler(args, ctx) {
    return ctx.continue(`Hello, ${args.who}!`);
  },
});
EOF

dotnet run --project src/apps/Orkeon.ConsoleApp -- \
    --runner=scripted-commands \
    --commands-dir ./commands

À l'invite :

scripted> /help            # 'hello' apparaît
scripted> /hello           # → Hello, world!
scripted> /hello --who=Ada # → Hello, Ada!
scripted> /help-cmd hello  # signature avec les arguments typés
scripted> /exit

Dans le REPL scripté, seule une ligne qui commence par / est une commande. @chemin référence un fichier ou un dossier (Tab complète les noms de commandes et les chemins), et tout le reste est du texte libre — confié à la commande de repli (ci-dessous), ou refusé s'il n'y en a pas. Le message qu'une commande rend via ctx.continue(...) est ce que le REPL affiche ; ctx.log part vers le volet des logs, que la TUI masque au démarrage.

Options CLI

Option Effet
--runner=scripted-commands Démarre directement dans le REPL scripted-commands au lieu du menu principal (dont l'entrée scripted ouvre le même REPL).
--commands-dir <chemin> Ajoute un répertoire à scanner (répétable ; monté en lecture seule comme /cli-commands, puis /cli-commands-1, … dans le VFS).
--no-script-commands Désactive entièrement la découverte : aucun *.cmd.ts n'est chargé, seuls help-cmd et les commandes par défaut restent.
--strict-commands Équivalent à FailFastOnInvalidScript=true + ContinueOnConflict=false (CI).
--settings <chemin> Chemin d'appsettings explicite (répétable — les fichiers suivants surchargent les précédents).
--mount <phys:virt:droits> Ajoute un montage VFS (répétable) — p. ex. pour rendre un dossier de commandes accessible. Placé et gardé comme pour orkeon run : sur une racine que les settings déclarent, il remplace les entrées de cette racine pour la session, sur une racine neuve il s'ajoute ; un montage que le REPL ne peut honorer — /sandbox, /credentials, une racine qu'il monte lui-même (/cli-commands…, /crews… tant qu'un --commands-dir ou un --crews-dir les y met), une racine deux fois en ligne de commande, un dossier absent — est refusé avant que la console s'ouvre, code 1, d'où qu'il ait été déclaré. Sans --commands-dir, --mount <dossier>:/cli-commands:ro atteint toujours un dossier de commandes.
--allow-external-mounts Un --mount hors du répertoire de travail est lisible (ou ORKEON_ALLOW_EXTERNAL_MOUNTS=1), comme pour orkeon run ; sans lui, le REPL refuse de démarrer (code de sortie 1) avant l'ouverture de la console. Toute entrée des settings en vigueur (une entrée choisie par id comprise) et les dossiers de --commands-dir et --crews-dir — des entrées du REPL, comme le script d'orkeon run — sont lisibles où qu'ils soient, sans lui.
--crews-dir <chemin> Ajoute un répertoire de résolution de crews (répétable ; monté en lecture seule comme /crews, /crews-1, …) — ce qui rend script-host / runCrewAsync("nom") résoluble.
--llm-log / --llm-log-path <rép> Le journal des échanges LLM d'orkeon run : JSONL sous ./llm-logs, ou <rép>, qui implique --llm-log (le dernier --llm-log-path l'emporte). Un dossier hors du répertoire de travail demande --allow-external-mounts ; sans lui, le REPL refuse de démarrer (code de sortie 1).
--replay <fichier> Joue les lignes du fichier comme si elles étaient tapées, puis sort (0 réussi, 1 arrêt sur erreur, 2 fichier absent ou illisible) ; voir la référence du CLI.
--interactive Avec --replay : le REPL reste ouvert après le fichier. Seul, erreur d'usage (code 2).
--log-level <niveau> Niveau minimal des journaux (Trace … None).

Chaque option à valeur accepte --option valeur et --option=valeur. --commands-dir, --settings, --mount et --crews-dir s'additionnent quand on les répète ; --allow-external-mounts prend aussi =true ou =false. orkeon-repl prend aussi --ui et --repl-wrap (référence du CLI).

appsettings.json

Les mêmes options sous Orkeon:Cli:ScriptCommands :

{
  "Orkeon": {
    "Cli": {
      "ScriptCommands": {
        "Enabled": true,
        "Directories": ["/cli-commands"],
        "FailFastOnInvalidScript": false,
        "EsbuildTranspile": true,
        "MaxScripts": 200,
        "ContinueOnConflict": true,
        "FallbackCommandName": "assistant",
        "Limits": {
          "MemoryLimitBytes": 67108864,
          "RecursionLimit": 100,
          "ExecutionTimeout": "00:05:00"
        }
      }
    }
  }
}

Les répertoires sont des chemins virtuels résolus via IFileSystemService — configurez une entrée Orkeon:FileSystem:Mounts si le répertoire n'est pas déjà monté. FallbackCommandName (défaut assistant) route toute ligne REPL non préfixée de / vers cette commande scriptée — l'interrupteur qui fait du REPL un agent conversationnel. Aucun exemple livré ne définit de commande assistant : sans elle, le texte libre reçoit la réponse d'une commande inconnue.

Référence defineCommand

defineCommand({
  name: "deploy",                 // ^[a-z][a-z0-9-]*$, never help / ? / h
  aliases: ["d", "ship"],         // optional, must not duplicate `name`
  group: "release",               // optional, ^[a-z][a-z0-9-]*$; default: the folder of the file
  description: "Deploy a crew.",  // single line, ≤ 200 chars

  args: {
    target: { type: "string", required: true, choices: ["dev", "prod"] },
    crew:   { type: "string", required: true },
    dryRun: { type: "boolean", default: false },
  },

  async handler(args, ctx) {
    ctx.log.info(`Deploying ${args.crew} to ${args.target}`);
    return ctx.continue();
  },
});

group (accepté aussi par defineAsyncCommand) est le bloc [<group>] sous lequel /help liste la commande. Absent, c'est le nom du dossier qui contient le *.cmd.ts (/cli-commands/session/clear.cmd.ts est dans session), pris sous le dossier de Orkeon:Cli:ScriptCommands:Directories qui a trouvé le fichier : un fichier placé directement dans ce dossier n'a pas de groupe, quelle que soit la profondeur du dossier dans son montage (/workspace/commands/a.cmd.ts, trouvé sous /workspace/commands, n'en a pas), et un nom de dossier qui n'est pas un nom de groupe valide n'en donne pas). /help imprime un bloc par groupe dans l'ordre d'enregistrement, (no group) en dernier ; les commandes propres au runner (ps, inspect, result, cancel, help-cmd) sont dans runner, et help-cmd <name> nomme le groupe sur sa première ligne. Un group invalide est refusé comme un nom invalide.

help, ? et h sont réservés. Un script peut délibérément prendre exit, quit, q, clear ou cls : les commandes scriptées sont résolues avant les commandes par défaut, et le loader journalise le masquage.

Quand args est omis, le handler reçoit { raw: string[] } à la place — la signature (args, ctx) => ... reste stable entre commandes typées et non typées.

Types d'arguments supportés

type Notes
"string" choices: readonly string[] optionnel, default optionnel.
"number" min, max, default optionnels.
"boolean" Un --flag nu ⇒ true. default optionnel.
"string[]" Glouton : en positionnel, consomme la fin de la ligne ; en forme drapeau, consomme jusqu'au prochain --key.

Les erreurs de validation remontent sous la forme d'un Error: ... imprimé par le runner ; le handler n'est pas invoqué.

Référence ctx (le contexte d'exécution)

interface CommandRuntimeContext {
  readonly command: { readonly name: string; readonly rawInput: string };

  readonly log: {
    debug(msg: string, data?: object): void;
    info(msg: string, data?: object): void;
    warn(msg: string, data?: object): void;
    error(msg: string, data?: object): void;
  };

  write(text: string): void;
  writeLine(text: string): void;
  writeBlock(spec: { kind: "markdown" | "diff"; text: string }): void; // stylé par la console à deux volets, lignes simples ailleurs
  readonly theme: "dark" | "light" | "none" | null
  setTheme(name: "dark" | "light" | "none"): boolean
  clear(): void;

  prompt(spec: PromptSpec): Promise<string | boolean | null>;   // null : un select abandonné (Échap)
  readonly interactive: boolean;
  progress(spec: { total?: number; label: string }): ProgressHandle;
  table<T extends object>(rows: readonly T[], columns?: readonly (keyof T)[]): void;

  readonly signal: CommandSignal;       // CancellationToken — see "Cancellation"
  readonly services: ServiceLocator;    // whitelisted

  continue(message?: string): CommandActionResult;
  exit(farewell?: string): CommandActionResult;
}

ctx.command.rawInput est la ligne telle que tapée (/deploy prod --force) ; dans le completed d'une commande asynchrone, c'est la ligne qui a lancé ce ticket : seule la commande qui l'a lancé exécute les complétions de ses propres instances, même retapée depuis. ctx.progress rend un handle doté de advance(label?), set(value, label?) et done(label?). Une globale console.log/info/debug/warn/error renvoie vers ctx.log.

Le .d.ts complet est livré dans l'outil orkeon : orkeon typings l'écrit en .orkeon/orkeon-cli.d.ts (à côté d'orkeon.d.ts) dans le répertoire courant — le chemin qu'attend la ligne /// <reference path=…> des exemples ; --out <dossier> l'écrit ailleurs (référence du CLI). Le garde-fou de typage du dépôt, scripts/check-scripting-typings.sh, vérifie chaque *.cmd.ts livré contre lui. Un fichier de commandes est aussi un moteur complet du DSL crew : agentBuilder, crewBuilder, llm, tools.* et rag y sont tous, et le await de premier niveau fonctionne.

Prompts

const target = await ctx.prompt({ type: "select", message: "Target?", choices: ["dev","prod"] });
const ok     = await ctx.prompt({ type: "confirm", message: "Proceed?", default: false });
const name   = await ctx.prompt({ type: "text", message: "Name?" });
const pwd    = await ctx.prompt({ type: "password", message: "Password:" });

Sur une console à panneaux, ctx.interactive vaut true, et select et confirm ouvrent un panneau de sélection à la place des lignes de saisie : les flèches ou un chiffre déplacent la sélection, Entrée répond, et le brouillon, l'historique et la liste des tâches attendent derrière. Esc répond null à un select et la valeur par défaut à un confirm, qui s'ouvre sur Oui sauf si sa valeur par défaut est false. Sans valeur par défaut, Entrée répond Oui, tandis qu'Esc et une ligne vide sur la console simple répondent Non. Ailleurs (la console simple, un rejeu), ils restent des lignes numérotées, et un script lit donc la même réponse partout. Une commande qui prend sa valeur en argument vérifie ctx.interactive avant d'ouvrir un panneau sans argument.

Un choix est une chaîne, à la fois sa valeur et son libellé, ou un objet. Un select prend aussi ce que le panneau peint autour des options :

const picked = await ctx.prompt({
  type: "select",
  message: "Model?",
  title: "Select model",
  description: "Applies to this session",
  keys: "Enter to set · Esc to cancel",          // à la place de la ligne de touches par défaut
  cancellable: true,                             // false : Esc ne quitte pas le panneau
  detailed: true,                                // répond { value, control } plutôt que la valeur
  control: { label: "effort", values: ["low", "high"], value: "high" },  // les flèches latérales l'ajustent
  choices: [
    { value: "a", label: "Alpha", description: "alignée après le libellé", hint: "visible quand sélectionné", current: true },
    "beta",
  ],
});

current marque la valeur en vigueur et ouvre le panneau dessus, default ayant la priorité. Sur des lignes tapées, un contrôle répond la valeur sur laquelle il s'est ouvert, car rien ne l'y ajuste.

Annulation

ctx.signal est le CancellationToken .NET brut exposé par Jint. Les propriétés sont en PascalCase à cause de la réflexion :

while (!ctx.signal.IsCancellationRequested) {
  // long-running work
}
ctx.signal.ThrowIfCancellationRequested();

L'alias TypeScript CommandSignal déclaré dans le .d.ts est une commodité de documentation ; les membres au runtime sont en PascalCase.

Services

const fs = ctx.services.get("fs");       // unknown : aucun type n'est déclaré pour `fs` ni `tools`
const tools = ctx.services.get("tools");
if (ctx.services.has("llm")) { /* … */ }

La whitelist de l'hôte détermine ce qui est accessible. Clés par défaut : fs, tools et runtime (la version du runtime, plus bas), plus en option llm, logger, commands (la façade de dispatch — voir plus bas), script-host (lancement de crews depuis une commande, et script-host.listCrews(), les noms de crews découverts — voir Piloter des crews depuis le REPL) et, dans orkeon-repl, permissions (les règles d'appels d'outils de la session, plus bas), approvals (les approbations d'outils en attente, plus bas) et session (enregistrer la session conservée, en charger une autre, plus bas), et usage (la consommation LLM de la session par modèle et par commande, plus bas) là où l'hôte tient un gestionnaire de coûts ou des instances de commande ; pour ces sept-là, les typings rendent CommandsFacade, ScriptHostFacade, PermissionRulesFacade, PendingApprovals, SessionFacade, RuntimeInfo et SessionUsage sans argument de type. configuration n'est délibérément pas exposée — la racine de configuration porte des clés d'API — les typings ne la déclarent donc pas, et demander une clé hors de la whitelist lève une erreur. Les hôtes ajoutent les leurs en passant une Action<ScriptServiceWhitelist> à AddScriptCommands (Add(name, factory), AddOptional(name, factory)).

Dispatcher des commandes vers des agents

Une commande peut s'adresser à un agent vivant par son nom et laisser sa réponse décider quand la commande est terminée. C'est la façade commands, accessible via ctx.services.get("commands"). Sous le capot, elle s'appuie sur un IAgentChannel qui lui est propre — un canal en mémoire que crée AddScriptCommands : la façade résout le nom d'agent → AgentId, corrèle la requête/réponse côté hôte, et trace chaque dispatch dans un registre interrogeable.

Règle clé : la commande se termine quand l'agent répond, pas quand le handler retourne. Le routage est point-à-point — une commande cible exactement un agent, qui est son unique finisseur (pas de fan-out, pas de join).

Côté agent — onCommand

Un agent déclare qu'il répond aux commandes dispatchées avec onCommand (dans le DSL crew — voir scripting.md). La valeur qu'il retourne est la réponse qui termine la commande :

const echo = agentBuilder()
  .name("echo").role("Echo").goal("Echo a payload back")
  .onCommand("run", (env) => env.payload.toUpperCase())     // answers intent "run"
  .onCommand((env) => ({ success: true, payload: "ack" }))  // catch-all (any intent)
  .build();

Le handler reçoit une enveloppe { intent, payload, from, correlationId } et retourne soit une chaîne de payload, soit { success?, payload?, error? }. L'agent doit être activé sur le bus de dispatch (AgentCommandRegistrar) pour qu'une commande .cmd.ts puisse l'atteindre par son nom. Le JS du handler s'exécute sous le verrou moteur de l'agent ; il est donc sûr même quand un dispatch asynchrone d'arrière-plan l'invoque.

Dispatch synchrone — request

Une defineCommand normale qui attend l'agent. request bloque jusqu'à ce que l'agent réponde et retourne la CommandResponse (de sorte qu'un await dessus se résout en la valeur — une commande sync est faite pour bloquer). Son streamed est vrai quand un tour quelconque de la requête a été écrit sur la console au premier plan (Orkeon:Cli:ConsoleStreaming:Enabled) ; une sortie en arrière-plan ou étiquetée rapporte faux. N'imprimez payload que s'il est faux, sinon la réponse s'affiche deux fois :

defineCommand({
  name: "ask",
  description: "Ask the 'echo' agent and wait.",
  args: { text: { type: "string", required: true } },
  handler(args, ctx) {
    const res = ctx.services.get("commands").request("echo", "run", args.text);
    if (!res.success) return ctx.continue("agent error: " + res.error);
    // The console already showed a streamed answer: print it only when it did not.
    return res.streamed ? ctx.continue() : ctx.continue("→ " + res.payload);
  },
});

request(agent, intent, payload) retourne { agent, intent, success, payload, streamed, error? }.

Dispatch asynchrone — defineAsyncCommand

Utilisez defineAsyncCommand quand le travail doit se détacher : dispatch tire et rend l'invite immédiatement ; le completed optionnel est rejoué plus tard quand l'agent répond.

defineAsyncCommand({
  name: "ask-bg",
  description: "Ask the 'echo' agent in the background.",
  maxConcurrent: 3,                                  // admission quota (see below)
  args: { text: { type: "string", required: true } },
  dispatch(args, ctx) {                              // does NOT block
    const ticket = ctx.services.get("commands").post("echo", "run", args.text);
    ctx.log.info("launched (ticket " + ticket + ")");
    return { ticket };
  },
  completed(result, ctx) {                           // run when the agent answers
    ctx.writeLine("✓ " + result.agent + ": " + result.payload);
  },
});
  • post(agent, intent, payload) retourne immédiatement un ticket (string) et exécute la requête sur une tâche d'arrière-plan.
  • completed(result, ctx) n'est pas appelé depuis le thread d'arrière-plan (Jint est mono-thread). Dès que le travail aboutit, l'hôte imprime une ligne concise (✓ [t1] ask-bg → echo: done) et exécute completed sur le moteur du script, sous son verrou — inutile de taper une autre commande. Les commandes d'un même fichier partagent un moteur, mais chacune n'exécute que les fins de ses propres instances (les exécutions lancées sous son nom) : une commande sœur tapée entre-temps n'exécute jamais le completed d'une autre commande.
  • Pour une valeur à lire à la demande, sondez avec result --ticket=… (ci-dessous).
  • Chaînage depuis completed. completed peut appeler runCrewAsync(name, input) : il retourne aussitôt un ticket, et la fin du second crew est drainée vers sa propre commande (le même nom de commande), dont le completed s'exécute à son tour. La chaîne est bornée par MaxChainDepth (8 par défaut, ScriptCommandsConfiguration.MaxChainDepth) ; la profondeur compte combien de sauts completed séparent une instance de son lancement (inspect l'affiche). Un commands.post compte de la même façon (la profondeur du parent plus un ; il ne prend pas d'options). Un runCrewAsync ou un post plus profond est refusé par une ChainDepthExceededException, levée en JS, dont le message nomme la profondeur, la limite et la commande : chain depth 8 reached (MaxChainDepth 8, /dev-batches).
  • Un pilote qui boucle : { chain: "continue" }. Une commande qui relance son propre travail après chaque cycle terminé (un plan exécuté lot après lot) passe runCrewAsync(name, input, { chain: "continue" }) : la nouvelle instance prend la profondeur de l'instance dont le completed s'exécute au lieu de cette profondeur plus un, si bien que la boucle commande → crew → completed de la même commande → crew dure autant qu'il le faut. L'instance parente est toujours une instance de la même commande : une commande n'exécute que le completed de ses propres instances, et ce que ce completed lance lui est rattaché. Hors d'un completed (un dispatch, un handler) l'option ne change rien : le lancement prend la profondeur qu'il prendrait sans elle (un premier saut est de profondeur 1), et un post monte toujours. Toute autre valeur de chain est une erreur de script.
  • Un crew qui est la conversation : { onMain: true }. runCrewAsync(name, input, { onMain: true }) fait du crew la conversation plutôt qu'une tâche à côté. Dans la console à volets, ce qu'il écrit, texte diffusé compris, ses appels et ses approbations arrivent sur l'écran main, sans ligne dans la liste ni ligne de lancement ; la console simple écrit son texte sans préfixe de ticket, et dans les deux ses approbations ne nomment aucune tâche. Sa ligne de fin n'apparaît que s'il a échoué ou si son jeton a expiré. Échap Échap l'interrompt quoi qu'on ait tapé depuis son lancement, car il reste dans le tour de l'invite ; une annulation demandée, par ces touches ou par cancel, n'écrit pas de ligne de fin et n'appelle pas completed. Le fil principal porte une seule conversation : lancé pendant qu'un autre crew onMain tourne, le crew est une tâche ordinaire à côté. ps et get en rendent toujours compte (onMain sur la vue). Une valeur ni absente ni booléenne lève une exception.
  • Un crew qui ne doit pas tourner deux fois : { exclusive: true }. Un crew qui ne doit pas tourner deux fois à la fois (une revue, l'écrivain d'un magasin partagé) est lancé par runCrewAsync(name, input, { exclusive: true }) : tant qu'un autre lancement exclusif du même crew n'est pas terminal, l'appel lève une erreur avant tout appel LLM, en nommant l'instance en cours — crew 'code-review' already running (ticket t2). La vérification et le lancement sont une seule étape : deux lignes tapées dans le même tick, ou une chaîne de completed, ne peuvent pas passer toutes les deux. Le crew est libre de nouveau quand son travail a réellement fini : l'instance se termine, échoue, ou une exécution annulée atteint son prochain point d'annulation coopératif et s'arrête (un completed qui le relance est admis). cancel() seul ne le libère pas : un relancement exclusif est refusé tant que le travail annulé n'a pas fini, si bien que deux exécutions ne se chevauchent jamais. Un runCrew synchrone d'un crew tenu par un runCrewAsync exclusif est refusé de la même façon. Un lancement sans l'option n'est ni refusé ni compté ; un exclusive qui n'est ni absent ni booléen (null compris) est une erreur de script. Contrairement à maxConcurrent ci-dessous, elle borne le crew, pas la commande : un alias de la commande qui ne lance rien répond pendant l'exécution. Les deux options se combinent ({ chain: "continue", exclusive: true }).

Quota d'admission — maxConcurrent

Déclaré sur defineAsyncCommand, il borne le nombre d'instances en vol de cette commande. Omis ⇒ non borné (∞). L'acquisition est non bloquante : quand le quota est plein, une nouvelle invocation est rejetée immédiatement (le dispatch ne s'exécute jamais) avec un message Rejected: quota of N instance(s) of '<cmd>' reached. Le slot est libéré quand l'agent répond. maxConcurrent n'a d'effet réel que pour les commandes async — une commande sync tient déjà le moteur et est sérialisée.

Introspection des commandes en vol

Le registre de dispatch est exposé de deux manières. Depuis un script :

const facade = ctx.services.get("commands");
facade.list({ state: "running" });   // CommandInstanceView[] ; aussi { name }, { agent }, ou "running"
facade.get("t3");                    // one view, or undefined
facade.cancel("t3");                 // request cancellation; returns boolean

Et sous forme de commandes intégrées au REPL (rapides, restent réactives pendant que le travail async tourne en arrière-plan) :

Commande Effet
ps [--state=…] Liste les instances. État : running (défaut), done, failed, cancelled, rejected, all.
inspect --ticket=<t> Détail complet d'une instance (état, agent, profondeur de chaîne, durée écoulée, résultat, progression). Un ticket nu fonctionne aussi : /inspect t3.
result --ticket=<t> Imprime le payload résultat (sondage). Signale « still running » si pas terminé.
cancel --ticket=<t> Demande l'annulation d'un ticket en vol.

Une CommandInstanceView porte : ticket, name, kind (sync/async), targetAgent, intent, correlationId, state, onMain, startedAt, completedAt?, elapsedMs, tokens, result?, error?, progress?. Les tickets s'écrivent t1, t2, … ; les 200 entrées terminales les plus récentes sont conservées pour que result/inspect puissent lire un ticket récent, puis évincées. Les quatre commandes intégrées ne sont enregistrées que si au moins un *.cmd.ts a été trouvé.

Câblage (côté hôte)

AddScriptCommands enregistre le substrat de dispatch comme singleton (son propre canal in-memory — le bus de dispatch CLI — plus l'annuaire de noms et le registre d'instances), ce qui fait se résoudre la clé optionnelle commands. Un agent est connecté par l'AgentCommandRegistrar interne, qui enregistre le handler de canal et le mapping nom→id ; aucune API publique ne l'expose dans cette version, et aucun hôte livré ne l'appelle : orkeon-repl ne charge que des fichiers *.cmd.ts et n'active aucun agent, donc tant qu'un hôte n'en enregistre pas, request et post lèvent commands: unknown agent 'echo'. Registered: (none).

Exemple de bout en bout

examples/cli-ts-commands/ fournit dispatch.cmd.ts (les commandes ask / ask-bg) et echo-agent.ork.ts (l'agent onCommand). Avec l'agent enregistré par l'hôte :

scripted> /ask hello            # → HELLO        (sync, bloque)
scripted> /ask-bg hello         # rend la main ; puis  ✓ [t1] ask-bg → echo: done
scripted> /ps --state=all       # t1 ask-bg echo done …
scripted> /result --ticket=t1   # [t1] HELLO

Construire un hôte REPL en C#

orkeon-repl est un hôte construit à partir de quatre projets ; un hôte à vous assemble les mêmes pièces.

Projet Ce qu'il apporte à un hôte
Orkeon.Cli.Abstractions Les contrats : IInteractiveCommand (Name, Aliases, Description, ExecuteAsync(CommandContext, ct) qui rend CommandResult.Continue(...) / Exit(...)), IInteractiveCommandRegistry (Commands, Fallback facultatif), IConsoleAdapter avec SystemConsoleAdapter et le LineEditingConsoleAdapter à édition de ligne, et InteractiveRunnerBase — la boucle elle-même.
Orkeon.Cli AddOrkeonCli() : les trois commandes par défaut — help (?, h), exit (quit, q), clear (cls) — et le DefaultCommandRegistry qui les porte, en singletons.
Orkeon.Cli.Commands.Scripting AddScriptCommands(configuration?, configure?, configureWhitelist?) : le loader des *.cmd.ts et son ScriptCommandRegistry, le substrat de dispatch (commands), script-host et ScriptHost. AddLlmConsoleStreaming(configuration, enabledByDefault) affiche dans la console la sortie streamée d'act() quand Orkeon:Cli:ConsoleStreaming:Enabled vaut true (une clé absente vaut enabledByDefault ; la REPL passe true).
Orkeon.Cli.TerminalGui AddOrkeonCliTerminalGui(options) : la console Terminal.Gui v2 à deux volets (ci-dessous).

Un runner dérive d'InteractiveRunnerBase, dont le constructeur prend le registre par défaut, le registre propre à l'hôte, l'adaptateur de console, un logger et le fournisseur de services ; il fournit une Banner et un Prompt, et peut surcharger SlashCommandsOnly (seules les lignes préfixées de / sont des commandes), ResolveFallback() (la commande qui reçoit tout le reste), OnStartAsync, OnExitAsync et OnUnknownCommandAsync. Une ligne se résout d'abord dans le registre de l'hôte, puis dans les commandes par défaut — d'où la possibilité, pour un script, de masquer exit ou clear. Le registre qu'enregistre AddScriptCommands ne charge rien quand il est résolu : appelez son EnsureLoadedAsync depuis OnStartAsync, comme le fait le ScriptedCommandsRunner d'orkeon-repl.

services.AddOrkeonCli();                                   // help / exit / clear + DefaultCommandRegistry
services.AddScriptCommands(configuration);                 // *.cmd.ts, commands, script-host
services.AddSingleton<IConsoleAdapter, SystemConsoleAdapter>();
services.AddSingleton<MyRunner>();                         // : InteractiveRunnerBase
services.AddOrkeonCliTerminalGui(new TerminalGuiOptions()); // en dernier : remplace l'adaptateur et les loggers

// puis
await using var tui = provider.GetRequiredService<TerminalGuiHost>();
await tui.RunAsync(provider.GetRequiredService<MyRunner>(), CancellationToken.None);

La console à deux volets — Orkeon.Cli.TerminalGui

AddOrkeonCliTerminalGui remplace la console par un écran Terminal.Gui v2 : le REPL l'occupe, et un tiroir de logs (Ctrl+G) reçoit les lignes de journal qui sinon s'entremêleraient avec l'invite. Il enregistre TerminalGuiHost, remplace IConsoleAdapter par l'adaptateur posé sur le volet REPL (la complétion Tab est branchée quand l'hôte enregistre un IReplInputAssist ; quand cette source est aussi un IReplCommandCatalog, un / en début de saisie ouvre au-dessus un menu des commandes, que la frappe restreint : les flèches le parcourent, Tab complète la commande, Entrée l'exécute, Esc le quitte en gardant le texte tapé, et une ligne rappelée de l'historique ne l'ouvre jamais), et remplace tous les ILoggerProvider par TerminalGuiLoggerProvider — un logger console écrirait dans l'écran que Terminal.Gui possède. Le fournisseur est aussi publié pour tout le processus (AmbientLoggerProvider), si bien qu'un hôte construit à l'intérieur d'une commande journalise dans le même volet. Appelez-le après les autres enregistrements, et appelez ClearStdoutLoggersForTerminalGui() dans la configuration des logs ; un second appel est ignoré. TerminalGuiHost.RunAsync(runner, ct) exécute le REPL sur une tâche d'arrière-plan pendant que Terminal.Gui possède le thread principal, et rend la main quand le REPL se termine ou que l'utilisateur quitte.

TerminalGuiOptions (un record à propriétés init — passez une instance construite) : InitialSplitRatio (0.5), DefaultMinimumLogLevel (Information), LogsBufferCapacity (5000 entrées, une entrée sur plusieurs lignes comptant pour une), LogsPaneTitle (Logs), LogsVisibleAtStartup (false), ReplWordWrap (true), ReplTranscriptCapacity (10000 lignes), BannerEnabled (true), Banner, Glyphs (Auto), SpinnerVerbs. Les touches : Ctrl+G tiroir de logs, Ctrl+R volet REPL, Ctrl+L / Ctrl+K vident les logs / le REPL, Ctrl+F recherche dans les logs, Ctrl+↑ / Ctrl+↓ redimensionnent, F2 / Maj+F2 plus / moins de détail dans les logs, F3 retour à la ligne, ↓ (depuis la dernière ligne du prompt) ou F4 liste des tâches, Ctrl+C copie la sélection, Ctrl+V et le clic droit collent dans la saisie, Ctrl+Q quitte (il demande d'abord confirmation tant qu'un tour s'exécute). Aucune vue de texte n'ouvre de menu contextuel : un clic droit colle, rien d'autre. orkeon-repl choisit cette console avec --ui (référence du CLI).

Ce que montre le transcript. Une entrée soumise s'affiche sur une barre grise après une rangée vide, le marqueur de prompt sur sa première ligne ; la copie d'une ligne entière rend ce qui a été tapé. Ce qu'écrit une commande slash pend sous son rappel, sur un coude, jusqu'à ce que la console lise de nouveau. Un tour de dix secondes ou plus se ferme sur une ligne atténuée avec son temps et ses jetons. Le modèle d'affichage est dans l'ADR-017.

Touches sur le prompt. Échap efface le brouillon ; un second Échap aussitôt après (toute autre touche entre les deux désarme la paire, et elle s'arme aussi sur un brouillon vide) interrompt le tour soumis depuis le prompt, qu'il s'exécute comme commande synchrone ou comme ticket détaché, y compris pendant une attente de nouvelle tentative (Reconnecting to …). La barre d'aide affiche esc esc to interrupt tant que ce tour s'exécute. Seul le tour du prompt est interrompu : un crew lancé par autre chose (un runCrewAsync détaché, la compaction, l'indexation) continue, et reste atteignable par /ps et /cancel <ticket> ; aucune touche ne l'annule. Ctrl+C n'annule jamais et ne quitte jamais : avec une sélection il la copie (le transcript, ou la saisie, où un glissement de souris sélectionne aussi) ; sans sélection il imprime une ligne d'aide (Ctrl+C or Ctrl+Shift+C copies a selection — esc esc interrupts the turn.). Ctrl+V colle le presse-papiers dans la saisie quelle que soit la vue qui a le focus, en mode runner comme en mode REPL, et s'efface tant qu'une boîte de dialogue modale (recherche, confirmation de sortie) a le focus. Dans la liste des tâches (↓ ou F4), Échap revient au prompt et n'annule rien, un tour en cours ou non ; il arme la paire comme un Échap sur le prompt (F4 et Tab non), si bien que Échap Échap depuis la liste interrompt un tour en cours. Ctrl+Q quitte aussitôt quand rien ne tourne, et demande confirmation tant qu'un tour s'exécute, comme pour une commande synchrone.

Prompt, historique et liste des tâches. Le prompt lit une touche dans l'un de trois états, jamais deux fois : le champ, l'historique et la liste des tâches. Dans le champ, ↑ sur la première ligne (une ligne visuelle : une longue ligne se replie, et ↑/↓ en parcourent d'abord les lignes) entre dans l'historique, garde le texte tapé comme brouillon et affiche l'entrée la plus récente, curseur à la fin ; sans historique, il déplace le curseur comme d'habitude. ↓ sur la dernière ligne donne le focus à la liste des tâches quand elle contient une tâche autre que main (la barre d'aide affiche alors ↓ tasks), et ne fait rien sinon. Début / Fin atteignent le début / la fin de la ligne, Ctrl+Début / Ctrl+Fin ceux du texte. Dans l'historique, ↑ affiche l'entrée précédente (rien sur la plus ancienne), ↓ la suivante, et depuis la plus récente rend le brouillon et quitte l'historique ; toute modification le quitte et garde le texte ; Entrée envoie l'entrée affichée et abandonne le brouillon. Les entrées vides et la répétition de la plus récente ne sont pas enregistrées. Dans la liste (la barre d'aide affiche ↑/↓ select · enter view), ↓ descend sans boucler, ↑ remonte et, sur la première ligne, revient au champ ; Échap revient au champ depuis n'importe quelle ligne, F4 aussi, et le champ retrouve son texte et son curseur ; Début / Fin atteignent la première / la dernière ligne ; Entrée imprime le détail de la tâche sélectionnée sur l'écran affiché et n'envoie rien ; une touche imprimable revient au champ avec ce caractère tapé. Tab revient au champ comme Échap ; Ctrl+V ou un clic droit y revient et colle au curseur restauré. L'état suit le focus : un clic sur une ligne donne le focus à la liste sur cette ligne (un double-clic imprime aussi son détail sur l'écran affiché), et le focus qui atteint le champ par un autre chemin quitte la liste et garde le texte courant ; le curseur ❯ n'est jamais dessiné tant que les touches vont au prompt. La ligne sélectionnée est le destinataire du prochain message, et le reste de retour dans le champ : le texte indicatif affiche Message @<tâche>… et le filet au-dessus de l'invite se termine par ── <tâche> ─ ; sélectionner main rend le destinataire par défaut. Le transcript tient un écran par fil, main et chaque tâche : la sélection affiche l'écran du fil, si bien que la déplacer avec ↑ / ↓ change l'écran montré, et main montre celui de main (voir « La zone du bas »). La sélection suit sa tâche quand la liste se retrie, et le champ reprend le focus, avec main pour destinataire, quand la liste se vide. Envoyer à une tâche demande le TuiIntegration.SendToTask de l'hôte ((ticket, texte) → bool) ; tant qu'aucun hôte ne le fournit, Entrée avec une tâche pour destinataire imprime que l'envoi à une tâche n'est pas pris en charge, et le texte reste dans le champ, ni envoyé ni enregistré. L'hôte du REPL (orkeon-repl) le branche sur la réponse à la question human_input que la tâche a posée ; une tâche qui n'en attend aucune garde le texte dans le champ (@<task> waits for no answer: nothing was sent, the text stays in the field.). Ces touches s'effacent tant qu'une boîte de dialogue modale a le focus.

La zone du bas. Sous le transcript viennent la ligne du spinner (glyphe et verbe dans l'accent, la parenthèse atténuée), un filet ─ atténué sur toute la largeur, terminé par ── <tâche> ─ dans l'accent tant que le destinataire est une tâche autre que main, l'invite (❯ accent et gras, le texte indicatif atténué et en italique), un filet nu, la barre d'état, une ligne vide et la liste des tâches. La barre d'état est indentée de deux colonnes et joint ses parties par un · atténué : le mode de permission (⏵⏵ bypass permissions on (shift+tab to cycle), en jaune pour bypassPermissions, dontAsk et acceptEdits, atténué sinon), les aides, et ↓ tasks tant qu'une tâche autre que main existe ; depuis la liste elle affiche ↑/↓ select · enter view seul. La liste montre main d'abord, puis les tâches vivantes dans l'ordre de création, puis la tâche terminée à laquelle l'invite s'adresse, s'il y en a une, et main reste listée tant qu'une tâche est listée : le ❯ de l'accent en colonne 0 tant que la liste a le focus, ● pour le destinataire et ◯ pour les autres (vert en cours, rouge en échec ou annulée, atténué sinon ; une ligne terminée est atténuée, sa phrase d'activité dit l'issue, ✔ finished, ✗ failed ou ⊘ cancelled, ses métriques la durée finale), le nom en gras, la phrase d'activité coupée par …, et alignés à droite et atténués <durée> · ↓ <jetons> tokens, le total de la tâche, mis à jour par le sondage à 1 Hz. Les largeurs sont des colonnes de terminal mesurées sur les graphèmes (un emoji ou un caractère CJK en compte deux) ; sur un volet étroit la phrase cède d'abord, puis le nom, puis les métriques, et un redimensionnement reconstruit les lignes à la nouvelle largeur. Elle grandit jusqu'à 6 lignes, puis défile avec le curseur. Un écran par fil. main et chaque tâche ont leur propre écran, de ReplTranscriptCapacity lignes, et seul celui du destinataire est affiché. Une ligne qu'une tâche écrit (texte streamé, question d'approbation d'outil) arrive sur l'écran de cette tâche, ouvert à sa première ligne, et ne porte pas de préfixe de ticket [t1] dans la console à volets (la console simple le garde) ; une étiquette de crew ([<taskId>] ) reste, elle distingue les agents d'un crew dans l'écran. L'écran main porte les tours de l'invite et les lignes de cycle de vie, jamais la sortie d'une tâche. La ligne de fin d'une tâche ( ✓ [t1] ask-bg → echo: done) et ce qu'écrit le completed de sa commande vont sur main, la ligne de fin gardant son ticket, qui y nomme la tâche. La copie, la sélection à la souris, le retour à la ligne (un seul état pour tous les écrans) agissent sur l'écran affiché ; Échap Échap interrompt toujours le tour de l'invite, quel que soit l'écran affiché, sa ligne Interrupted arrivant sur main. Une ligne d'attention, comme une question d'approbation d'outil, s'affiche sur l'écran affiché quelle que soit la tâche qui demande, et est enregistrée une fois dans l'écran de la tâche qui demande. Dans la console à volets, une tâche qui se termine quitte la liste au sondage suivant, et son écran avec elle : ce qu'elle y a écrit ne se relit plus, et ps/inspect en rendent toujours compte. L'exception est la tâche en cours de lecture : destinataire, elle garde sa ligne, son écran et le destinataire, jusqu'à ce que le destinataire change ou que TuiIntegration.FinishedAgentRows ne rende plus la tâche. Un sondage dont le flux des terminées échoue garde la ligne terminée du destinataire de la dernière lecture réussie : une panne n'est pas l'hôte qui oublie une tâche. Entre deux sondages, une nouvelle tâche imprime ● <nom>(<intention>) puis ⎿ Backgrounded agent (↓ tasks) dans le transcript, et une tâche terminée ● Agent "<nom>" finished · <durée>, ✗ Agent "<nom>" failed · <durée> ou ⊘ Agent "<nom>" cancelled · <durée> : l'état final vient du TuiIntegration.FinishedAgentRows de l'hôte (les tâches terminées qu'il conserve), si bien qu'une tâche qui démarre et finit entre deux sondages reçoit quand même ses deux lignes, dans l'ordre ; sans lui, une tâche qui quitte la liste se lit comme terminée. Ces lignes vont à l'écran main. Le destinataire reste sur une tâche qui se termine ; la ligne @<tâche> finished · recipient is main est imprimée, et le destinataire revient à main, seulement quand l'hôte l'oublie, tant que le prompt a le focus ; un sondage dont le fournisseur de lignes lève une exception n'écrit rien et laisse les lignes, la liste et le destinataire tels quels. Échap Échap imprime ⎿ Interrupted · What should Orkeon do instead?. Les couleurs viennent de rôles sémantiques (Normal, Dim, Accent, Ok, Alert, Error) sur le fond du terminal, en 24 bits quand COLORTERM vaut truecolor ou 24bit et en 16 couleurs nommées sinon. Avec TerminalGuiOptions.Glyphs réglé sur GlyphMode.Never, ❯ ● ◯ ✔ ✗ ⊘ ⏵ ⎿ ※ ─ ↑ ↓ … deviennent > * o v x - > | * - ^ v ..., les ↑/↓ de la barre d'aide et la phrase coupée compris.

Le témoin du modèle. Le témoin aligné à droite de la barre d'aide nomme le modèle sélectionné (24 colonnes au plus, un nom plus long finit par …) et se colore selon ce que la console a observé des appels de ce modèle, jamais par une sonde : vert tant que le modèle est utilisable, une réponse finale 2xx comprise ; ambre pendant une attente de nouvelle tentative de ce modèle ; rouge après un non-2xx final, un délai dépassé, ou quand aucun modèle n'est configuré (l'étiquette dit alors no model). Seuls les appels du modèle affiché le colorent, et un changement de modèle le remet au vert. Un appel arrêté par l'appelant (Échap Échap) n'est pas un échec et laisse la couleur inchangée.

État de session partagé avec les commandes. La console lit et écrit deux clés de l'état de session (ISessionBufferService, qu'une commande atteint par get_state et set_state de session_store) : default_permission_mode (SessionStateKeys.DefaultPermissionMode, Orkeon.Constants.Cli), le mode de permission qu'elle affiche et fait tourner sur Maj+Tab (default → acceptEdits → plan → bypassPermissions), et selected_model (SessionStateKeys.SelectedModel), le modèle que nomme le témoin. La commande /mode d'un produit écrit la première clé, et la console affiche son choix : les clés sont un contrat et gardent leur nom. La commande /model d'un produit écrit la seconde clé pour nommer le modèle ; sans elle, le témoin se rabat sur le réglage Llm:Model.

Approbations des appels d'outils. Avec le contrôle des permissions activé, orkeon-repl enregistre un canal d'approbation (AddConsoleToolApproval) : un appel pour lequel le mode demande est soumis à l'opérateur, dont la ligne suivante y répond. Venu d'un crew lancé par runCrewAsync, la boucle de lecture lui remet cette ligne (IReplLineInterceptor) avant de résoudre une commande ; venu d'un crew lancé par runCrew, qui tient la boucle, l'appel en attente lit lui-même la réponse, et le temps mis à répondre ne compte pas dans RunCrewTimeout. Dans la console à volets, la question ouvre un panneau sur Oui, et Entrée seul autorise donc cet appel une fois : ses options répondent à cette question par son identifiant (y, s ou n) et n'arrivent jamais à une lecture comme une ligne, Esc refuse, et /, ou une lettre qu'aucune option ne porte, rend la question à la saisie avec les lettres déjà tapées, pour qu'une commande passe d'abord, la ligne de statut la posant alors. Une commande passe le mode de la session à act dans permissionMode ; elle ne gère pas la question elle-même. Voir la référence du CLI.

Règles de session. Le contrôle lit les règles d'autorisation et de refus de la session avant le mode (IToolPermissionRules, tenues par le REPL). Une commande les pose par ctx.services.get("permissions") : allow(tool, argument?, pattern?), deny(...), clear(), list(). Une règle couvre tous les appels d'un outil, ou ceux dont l'argument correspond en entier à un motif, * valant n'importe quelle suite de caractères. Une règle de refus refuse l'appel dans tous les modes ; une règle d'autorisation le laisse passer sans demander dans tous les modes sauf plan, qui reste en lecture seule : dontAsk lance donc ce qu'une règle autorise et refuse le reste. Les règles durent jusqu'à la sortie du REPL. enabled (en lecture seule) dit si l'hôte a enregistré le contrôle (Orkeon:Security:PermissionGate:Enabled = true) : à false, les règles et les modes ne contrôlent rien et chaque appel d'outil passe, si bien qu'une commande qui affiche un mode peut le dire. Un crew lit le même fait par ctx.llm.permissionGate.enabled.

const permissions = ctx.services.get("permissions");
permissions.allow("shell_command", "command", "npm test*");
permissions.deny("shell_command", "command", "git push*");

Approbations en attente. Une commande lit les approbations d'outils qui attendent l'opérateur par ctx.services.get("approvals"), présent quand l'hôte enregistre le canal d'approbation (IToolApprovalWatch). Il est en lecture seule : list() rend les questions en attente à cet instant, celle que la prochaine réponse règle en premier, chacune un objet simple { taskId, command, tool, input } : le ticket de la tâche de fond qui demande (t1) et le nom de sa commande, tous deux null hors d'une tâche, le nom de l'outil, et l'entrée de l'appel telle que la ligne d'état l'affiche, ses arguments JSON coupés à 60 caractères (PendingToolApprovalInput). La liste est vide une fois que l'opérateur a répondu : une commande /tasks distingue ainsi une tâche bloquée sur l'opérateur d'une tâche qui tourne.

const approvals = ctx.services.has("approvals") ? ctx.services.get("approvals").list() : [];
for (const a of approvals) ctx.writeLine(`[${a.taskId}] ${a.command} waits for approval of ${a.tool} ${a.input}`);

Enregistrer et charger la session. orkeon-repl conserve sa session par projet (Orkeon:Cli:Session:Persist, actif sauf si les réglages le désactivent) : elle est enregistrée après chaque tour et à la sortie dans <SessionsDirectory>/<projet>-<hash>/last.json, et rechargée au démarrage. Tant qu'elle est conservée, ctx.services.get("session") sert deux appels. save() écrit ce fichier tout de suite, sous la même forme, et se résout en son chemin virtuel ; save(path) écrit la session sous la même forme dans un autre fichier virtuel, que load accepte en retour, et se résout en ce chemin (un chemin vide rejette la promesse). load(path) lit un fichier que le REPL a enregistré, à un chemin virtuel, et remplace le tampon de conversation et le sac d'état (les deux choses que /clear remet à zéro), avec l'identifiant et le titre de la session, par les siens ; il se résout en le nombre de messages chargés, et le tour suivant poursuit cette conversation. Les instances de commandes en cours (commands.list) ne sont pas touchées, et la session continue de s'enregistrer dans son propre fichier : la session chargée écrase last.json après le tour suivant, il faut donc archiver la session courante avec save(path) avant un load, sans quoi elle est perdue. Le fichier est jugé en entier avant tout changement : un fichier absent, illisible ou sans la forme qu'écrit le REPL (SessionId, Messages avec chacun un Role et un Content, State) rejette la promesse, et la session reste telle qu'elle était. Les deux passent par le système de fichiers virtuel : un chemin hors d'un montage, ou sans droit de lecture (ou d'écriture), est refusé de la même façon. Un load pendant le tour en cours d'une autre commande n'est pas pris en charge : le dernier qui écrit le tampon l'emporte.

const session = ctx.services.get("session");
const archived = await session.save("/workspace/saved/before-review.json"); // garder d'abord la session courante
const count = await session.load("/workspace/saved/review.json");
ctx.writeLine(`archived ${archived}, loaded ${count} messages`);

Version du runtime. ctx.services.get("runtime"), toujours présent, décrit le runtime qui exécute la commande par un objet simple { version, commit, channel } : la version publiée sans ses métadonnées de build (1.2.0 pour 1.2.0+3f9c2ab), telle qu'orkeon doctor l'imprime ; le sha du commit que portent ces métadonnées (la partie après +), null quand il n'y en a pas ; et le canal par lequel le runtime a été installé, lu dans le marqueur INSTALL-CHANNEL de l'installation comme orkeon doctor le lit (deb, tarball, source, dotnet-tool…), unknown quand rien n'en nomme. orkeon-repl enregistre le sien (ScriptRuntimeInfo) ; un hôte qui n'en enregistre aucun rend la version de son assembly d'entrée et le canal unknown.

const runtime = ctx.services.get("runtime");
ctx.writeLine(`Orkeon ${runtime.commit ? `${runtime.version}+${runtime.commit}` : runtime.version} (${runtime.channel})`);

Consommation de la session. Une commande lit la consommation LLM de la session par ctx.services.get("usage"), présent quand l'hôte tient un gestionnaire de coûts (ICostBudgetManager) ou des instances de commande (le REPL tient les deux). Il est en lecture seule : report() rend les chiffres de l'instant, { promptTokens, completionTokens, cacheHitTokens, cacheWriteTokens, reasoningTokens, totalTokens, calls, unpricedCalls, cost, byModel, byCommand }. Les comptes de cache sont une part du prompt, le raisonnement une part de la complétion (rapporté par Z.AI et OpenRouter). Chacun de ces trois vaut null tant qu'aucun appel ne l'a rapporté, jamais 0 : un fournisseur qui ne mesure pas le cache donne null, un qui n'en a mesuré aucun donne 0, et un appel qui n'a rien rapporté n'ajoute rien aux autres. Les totaux comptent chaque appel que le gestionnaire de coûts a enregistré (CostReport.TotalUsage) ; byModel a une ligne par modèle nommé dans la réponse du fournisseur, avec ses calls : un appel dont le fournisseur ne nomme aucun modèle est dans les totaux et dans aucune ligne, les totaux peuvent donc dépasser la somme de byModel. byCommand a une ligne par instance de commande que la session garde (un crew lancé par runCrewAsync compris, la plus récente d'abord), tirée de ce que InstanceAttributingUsageSink lui a crédité, avec son ticket, son name, son state et ses calls. Un cost est ce que le fournisseur a facturé, sinon le prix que le registre connaît pour le modèle (Orkeon:CostTracking), et null quand aucun des deux n'est connu pour aucun de ses appels : une commande /usage distingue ainsi un appel gratuit d'un appel sans prix. Chaque ligne et les totaux portent unpricedCalls, les appels que personne n'a tarifés, que cost compte pour 0 : tant qu'il n'est pas nul, le cost est un minorant.

const usage = ctx.services.get("usage").report();
for (const m of usage.byModel) ctx.writeLine(`${m.model}: ${m.promptTokens} in (${m.cacheHitTokens ?? "n/a"} cached), ${m.completionTokens} out, ${m.cost ?? "n/a"}`);
for (const c of usage.byCommand) ctx.writeLine(`[${c.ticket}] ${c.name}: ${c.promptTokens + c.completionTokens} tokens, ${c.cost ?? "n/a"}`);

Les appels d'une étape. Pendant qu'un tour appelle des outils, les lignes au-dessus de la ligne d'état comptent les appels de l'étape et listent les derniers ($ commande, Read chemin), chacun avec ce sur quoi il travaille : le point d'invocation de l'hôte prévient la console par un ToolActivityFeed, et seul l'argument désigné pour cet outil atteint l'écran, jamais ce qu'une édition écrit ni les arguments d'un outil non listé (ToolCallSubject). Une étape finit avec le texte suivant de son écran une fois qu'aucun de ses appels ne tourne, ou avec sa tâche ou son tour, même sur un appel encore ouvert : ses lignes laissent place à une ligne du transcript, Read 1 file, ran 2 shell commands. Sur une saisie vide, ctrl+o liste une fois les appels de la dernière étape ; avec du texte dans la saisie, il reste un retour à la ligne. Chaque fil a son étape, affichée avec son écran, et un panneau garde la place pour lui.

Le changement d'un appel. Pour edit_file et file_write, le décorateur lit le fichier avant et après l'appel et remet à l'écran un ToolCallDiff (LineDiff, une comparaison par lignes) : le transcript montre le fichier et ses compteurs, des lignes numérotées sur fond rouge ou vert, les mots changés dans une teinte plus forte et des points de suspension entre deux changements éloignés, jusqu'à 80 lignes. La comparaison sert à l'écran seul : ce que reçoit le modèle ne change pas, rien n'est lu tant qu'aucun écran n'écoute, et un fichier de plus de 1 Mio, binaire ou illisible, ou une entrée qui n'est pas un fichier ordinaire, montre l'appel sans son changement. Un autre écrivain qui touche le fichier pendant l'appel se voit dans le diff. ctx.writeBlock({kind:"diff"}) peint de la même façon un patch unifié, avec les numéros lus sur les lignes @@ ; copier une ligne entière redonne la ligne du patch.

Markdown. Le flux d'un assistant et ctx.writeBlock({kind:"markdown"}) sont lus une ligne terminée à la fois (MarkdownLines, Markdig pour l'intérieur d'une ligne) : titres, gras, italique, code en ligne, liens, listes, citations, filets, blocs de code et tableaux. La ligne en cours d'écriture s'affiche telle qu'elle arrive et est remplacée quand elle se termine : un marqueur peut donc apparaître un instant avant d'être lu. Un tableau attend la ligne qui le termine, puis se dessine dans un cadre, ou se lit rangée par rangée si l'écran est trop étroit ; au-delà de 200 rangées, un nouveau bloc commence. Une emphase ouverte sur deux lignes reste telle qu'elle est écrite. Copier une ligne entière redonne son markdown ; en copier une partie donne ce qui est affiché. Le flux n'atteint l'écran que si Orkeon:Cli:ConsoleStreaming:Enabled est actif ; ce qu'une commande écrit avec ctx.writeLine n'est pas lu comme du markdown.

Les tâches dans le fil. Les tâches apparues dans une même lecture de la liste forment un groupe, ● 3 agents launched (↓ to manage) puis une ligne ├─/└─ par tâche ; une tâche seule garde ses deux lignes. Une ligne de fin dit ce que la tâche a consommé, outils, jetons et temps, quand c'est connu, et son glyphe dit comment elle a fini.

Loin de la fin. Un transcript remonté dessine ↓ more below (click or ctrl+end) sur sa dernière ligne et, une fois sorti de l'écran le prompt auquel répondent les lignes, ce prompt sur sa première ligne. Les deux sont dessinés par-dessus les lignes, sans faire partie du texte : ni la sélection ni la copie ne les voient, et remonter d'une ligne de plus montre celle qu'ils couvrent.

La barre. context N% est ce qu'a envoyé le dernier appel au modèle du tour du prompt, quelle que soit l'instance de commande du tour qui l'a fait, rapporté à Orkeon:Cli:Session:ContextWindowTokens, 200000 sans ce réglage, la fenêtre que rapporte token_budget. Avant tout appel, l'entrée est absente ; un nouveau prompt garde le dernier chiffre jusqu'à la réponse de son premier appel, et une session vidée (un /clear qui réinitialise le tampon) le retire. Elle reste discrète jusqu'à 79 %, en alerte dès 80 %, en erreur dès 95 %. Sur un prompt vide, ? liste les touches ; pendant qu'un ctx.prompt de script lit, c'est un caractère comme un autre.

Palettes. Orkeon:Cli:Tui:Theme nomme la palette au démarrage : Dark, Light ou None, les couleurs du terminal, gras et italique conservés. Omis, None si NO_COLOR est défini, sinon Dark : un réglage l'emporte sur la variable, comme le demande no-color.org. Toute autre valeur, un nombre compris, est refusée au démarrage. La palette n'est pas détectée depuis le terminal. ctx.setTheme("light") la change pour la session, écran compris, et répond false sur une console sans palettes ; ctx.theme la nomme.

Matrice de support TypeScript (esbuild → Jint)

Fonctionnalité Support
interface, type, enum (non-const) ✅
import/export (chemins relatifs) ✅
async/await, Promise, Promise.all ✅
Déstructuration, spread, valeurs par défaut, rest ✅
Classes, getters/setters, héritage ✅
Littéraux de gabarit (template literals) ✅
Map/Set/WeakMap/WeakSet ✅
JSON.parse/JSON.stringify ✅
Regex (sans lookbehind) ✅
Modules npm (fs, path, node:*) ❌ Utilisez ctx.services.get("fs").
fetch, setTimeout, setInterval ❌/⚠️
Décorateurs (@experimental) ❌ esbuild s'arrête au stage-3.
Chemins/alias tsconfig ⚠️ imports relatifs uniquement.

Contraintes (bonnes à connaître)

  • Découverte au démarrage uniquement. Modifiez un script, redémarrez le runner. Pas de hot reload (délibéré).
  • Un moteur par fichier de script, gardé chaud. Toutes les commandes qu'un fichier déclare partagent l'état Jint de ce fichier d'une invocation à l'autre ; les commandes de fichiers différents sont isolées.
  • Jint n'est pas thread-safe. Le runner sérialise les invocations ; un SemaphoreSlim protège chaque moteur défensivement.
  • Limites de sandbox (profil CLI) : 64 Mo de mémoire, 100 de récursion max, 5 min d'exécution. Surcharge via Orkeon:Cli:ScriptCommands:Limits. Attendre la réponse à ctx.prompt ne compte pas comme de l'exécution, et l'attente d'un handler n'a pas de limite propre : annuler la commande y met fin.
  • Politique de conflit : le premier script gagne, par ordre ordinal des chemins ; le second est journalisé en Warning. Basculez ContinueOnConflict=false pour échouer vite.
  • VFS uniquement. Les scripts lisent le disque via ctx.services.get("fs") — pas de System.IO direct.

Dépannage

Symptôme Cause probable Action
hello n'apparaît pas dans /help Script hors des Directories configurés, ou erreur d'évaluation journalisée en Error Vérifiez les logs de Orkeon.Cli.Commands.Scripting.Loading.ScriptCommandLoader.
Esbuild binary not found. Tried (in order): … Aucun esbuild sur le chemin de recherche Définissez Orkeon:Scripting:Toolchain:EsbuildPath ou ORKEON_ESBUILD_PATH, lancez npm ci dans tools/scripting-esbuild/, ou mettez esbuild dans le PATH — npm install -g esbuild le fait ; l'outil dotnet ne le livre pas (ordre de recherche).
defineCommand is not defined Script évalué avant les bindings (bug) Ouvrez une issue avec le chemin du script.
Le prompt ne s'affiche pas dans le panneau REPL Adaptateur autre que Terminal.Gui ou heuristique de préfixe manquée Assurez-vous que le script écrit les prompts avec un suffixe > .
Error: Argument '--target' value 'staging' is not in choices [dev, prod]. Faute de frappe ou choices obsolètes Utilisez /help-cmd <name> pour voir la signature à jour.
Une ligne n'exécute rien / Unknown command Tapée sans le / initial, et pas de commande de repli Préfixez les commandes par /, ou définissez la commande FallbackCommandName.