Protocole de session agentique
Un assistant qui travaille dans l'espace de travail de l'apprenant (Copilot, Claude Code, Codex, OpenCode) peut piloter une leçon Studium et exécuter lui-même la vraie science. Studium reste le cerveau de la leçon : il choisit la scène suivante, note les réponses et met à jour la maîtrise. L'assistant, appelé ici opérateur, exécute le code dans le terminal ou le notebook de l'espace de travail, et l'éditeur affiche les figures. Studium n'exécute jamais de code lui-même et n'a besoin d'aucun bac à sable par apprenant.
Cette page décrit les deux canaux entre Studium et un opérateur, puis le canal fichiers en détail. Les noms de fichiers, de champs et de statuts restent en anglais, tels que le code les attend.
Deux canaux
| Canal | Surface | Pour qui |
|---|---|---|
| MCP (typé, en direct) | les outils MCP d'apps/lesson-mcp : start_lesson_session, get_current_scene, get_scene_artifacts, submit_response, submit_turn, request_hint, get_run_manifest, submit_run_result, end_session |
un assistant ou un éditeur qui parle MCP |
| Fichiers (universel) | un dossier .studium-session/ |
tout assistant capable de lire et d'écrire des fichiers |
Les deux appliquent la même expurgation : la clé de réponse (affirmations, défauts attendus, réponses modèles, choix correct d'un quiz) est retirée avant que quoi que ce soit n'atteigne l'opérateur. L'opérateur audite une lecture faite par une IA sans recevoir la solution.
Le canal fichiers
.studium-session/
task.md Studium -> opérateur l'étape courante, expurgée : quoi faire et la référence de l'artefact réel
response.json opérateur -> Studium la réponse de l'apprenant, p. ex. {"text": "..."} ou {"kind": "flaw_report", "text": "..."}
run.json Studium -> opérateur un manifeste d'exécution côté apprenant (scènes de reproduction seulement)
run_result.json opérateur -> Studium {"ran": true, "passed": true, "landmark": "...", "artifacts": [...], "checks": [...]}
feedback.md Studium -> opérateur le résultat noté et si la leçon a avancé
index.json journal partagé une entrée par étape : {step, scene_id, scene_type, status}
experiment-action.json opérateur -> Studium {session_id, scene_id, input} : une prédiction, un début, une observation ou une conclusion
experiment.json Studium -> opérateur le journal d'expérimentation privé (mode 0600), dès qu'il a des entrées
session-language.json opérateur -> Studium {session_id, presentation_language} : changer la langue de présentation
Le status d'une étape dans index.json vaut awaiting_response, graded, awaiting_run, ran
ou complete.
La boucle
- Studium écrit
task.md(la scène expurgée, plus la référence d'un vrai résultat exécuté quand la scène en a un) et consigne l'étape enawaiting_response. - L'opérateur lit
task.md, fait le travail dans l'espace de travail et écrit la réponse de l'apprenant dansresponse.json. - Studium la note, écrit
feedback.md, marque l'étapegradedet écrit letask.mdsuivant, ou une entréecompleteà la fin.
Un response.json mal formé ou décalé n'est pas bloquant : Studium le consomme et écrit un
feedback.md correctif, pour que l'opérateur réessaie.
Consignes pour un opérateur
Lis
.studium-session/task.md. Fais ce qu'il demande dans cet espace de travail (exécute le code, examine le vrai résultat que montre l'éditeur). Écris la réponse de l'apprenant dans.studium-session/response.jsonsous la forme{"text": "<le jugement, avec sa justification>"}, en écrivant d'abordresponse.json.tmppuis en le renommant, pour que Studium ne lise jamais un fichier à moitié écrit. Lis ensuite.studium-session/feedback.mdet, s'il y a un nouveautask.md, continue. Ne cherche pas la clé de réponse : elle n'est pas là.
Exécutions côté apprenant
Une scène reproduction peut porter un run_manifest : la capsule, l'installation et la commande,
les fichiers attendus et les vérifications à mener, jamais les valeurs attendues. Sur une telle
scène, Studium écrit run.json et un task.md « préparer et exécuter », et consigne
awaiting_run. L'opérateur prépare l'environnement, installe les dépendances, exécute la capsule
dans l'espace de travail et écrit run_result.json.
| Résultat | Ce que fait Studium |
|---|---|
ran et passed |
Enregistre l'exécution propre à l'apprenant (status: "ran", avec son repère et ses artefacts) et avance. |
| absent ou partiel | Continue d'attendre. |
ran: false ou vérifications échouées |
Le consomme et écrit un feedback.md correctif ; l'opérateur corrige et relance. |
Le repère de référence de l'auteur est retenu, pour que l'apprenant produise un résultat neuf. Par
MCP, le même échange passe par get_run_manifest puis submit_run_result.
Lancer le harnais
runStudiumSession(host, bundleRef, dir, operator) dans @studium/lesson-session-host pilote la
boucle avec un opérateur interchangeable. Le lanceur en ligne de commande l'enveloppe :
# Mode attente (par défaut) : Studium écrit task.md et attend que vous ou un assistant écriviez response.json
apps/lesson-mcp/node_modules/.bin/tsx apps/lesson-mcp/src/session-runner-cli.ts capsule-judgment-demo/lesson.json --dir=.studium-session
# Mode stub : un opérateur factice, sans clé, mène la boucle jusqu'au bout (test rapide)
STUDIUM_EPHEMERAL=1 apps/lesson-mcp/node_modules/.bin/tsx apps/lesson-mcp/src/session-runner-cli.ts capsule-judgment-demo/lesson.json --stub --dir=reports/session
Le dossier --dir doit être nouveau. Sans --stub, le runner attend de vraies réponses. Le
skill harnais décrit les formats.
Options : --bundles-root=DIR (par défaut BUNDLES_ROOT, sinon ./fixtures), --dir=DIR (par
défaut ./.studium-session), --language=BCP47 (langue de présentation).
| Opérateur | Comportement |
|---|---|
watchOperator({pollMs, timeoutMs}) |
Attend qu'un assistant extérieur écrive response.json ou run_result.json. Studium n'appelle jamais de modèle. |
stubOperator |
Un substitut déterministe ; sur une scène d'exécution, il écrit un résultat réussi sans rien exécuter. |
makeLlmOperator({llm, runCapsule}) |
Un opérateur adossé à un modèle, qui prend l'exécution en charge : il exécute la capsule d'une scène de reproduction et demande au modèle de juger la lecture IA de sa propre exécution. Les deux dépendances sont injectées. |
La démonstration avec modèle exécute la vraie capsule avec tools/capsule_runner.py et un modèle
factice, ou un vrai modèle avec --live et LITELLM_BASE_URL :
apps/lesson-mcp/node_modules/.bin/tsx apps/lesson-mcp/src/llm-operator-demo.ts capsule-loop-demo/lesson.json --dir=reports/session
L'exécution et l'affichage reviennent à l'éditeur
- L'exécution a lieu dans le terminal ou le noyau de notebook de l'espace de travail, pilotée par
l'opérateur.
tools/capsule_runner.pyproduit encore une fois l'exécution de référence de l'auteur, pour fonder une scène ; les exécutions de l'apprenant sont demandées parrun.json(ouget_run_manifest) et rapportées en retour. - L'affichage est natif : le contrôleur de notebook VS Code montre une figure
executed_resultou une image en ligne avec une légende, et le canal fichiers transporte la même référence.
Ce qui est couvert
L'aller-retour par fichiers est testé sur fixtures/capsule-judgment-demo, sans clé de réponse
dans aucun task.md, et l'exécution côté apprenant sur fixtures/capsule-run-demo : le manifeste
ne porte aucune réponse, le repère de l'auteur est retenu, et une exécution échouée ou absente se
rattrape. Une exécution réussie est enregistrée comme le résultat propre de l'apprenant, sur lequel
une scène spot_the_flaw ultérieure peut se fonder (reference_from_run dans le
format du bundle de leçon).