Agentic session protocol
An assistant working in the learner's workspace (Copilot, Claude Code, Codex, OpenCode) can drive a Studium lesson and run the real science itself. Studium stays the lesson's brain: it chooses the next scene, grades answers and updates mastery. The assistant, called the operator here, executes code in the workspace terminal or notebook, and the editor renders the figures. Studium itself never executes code and needs no sandbox per learner.
This page describes the two channels between Studium and an operator, and the file channel in full.
Two channels
| Channel | Surface | Best for |
|---|---|---|
| MCP (typed, live) | the MCP tools of 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 |
an assistant or editor that speaks MCP |
| Files (universal) | a .studium-session/ folder |
any assistant that can read and write plain files |
Both apply the same redaction: the answer key (claims, expected flaws, model answers, the correct quiz choice) is removed before anything reaches the operator. The operator audits an AI reading without being handed the solution.
The file channel
.studium-session/
task.md Studium -> operator the current step, redacted: what to do and the real artifact reference
response.json operator -> Studium the learner's answer, e.g. {"text": "..."} or {"kind": "flaw_report", "text": "..."}
run.json Studium -> operator a learner-time run manifest (reproduction scenes only)
run_result.json operator -> Studium {"ran": true, "passed": true, "landmark": "...", "artifacts": [...], "checks": [...]}
feedback.md Studium -> operator the graded outcome and whether the lesson advanced
index.json shared log one entry per step: {step, scene_id, scene_type, status}
experiment-action.json operator -> Studium {session_id, scene_id, input}: a prediction, begin, observation or conclusion
experiment.json Studium -> operator the private experiment journal (mode 0600), once it has entries
session-language.json operator -> Studium {session_id, presentation_language}: change the presentation language
A step's status in index.json is one of awaiting_response, graded, awaiting_run, ran
or complete.
The loop
- Studium writes
task.md(the redacted scene, plus the reference of a real executed result when the scene has one) and logs the step asawaiting_response. - The operator reads
task.md, does the work in the workspace, and writes the learner's answer toresponse.json. - Studium grades it, writes
feedback.md, marks the stepgradedand writes the nexttask.md, or acompleteentry at the end.
A malformed or mismatched response.json is not fatal: Studium consumes it and writes a corrective
feedback.md, so the operator can retry.
Instructions for an operator
Read
.studium-session/task.md. Do what it asks in this workspace (run the code, inspect the real result the editor shows). Write the learner's answer to.studium-session/response.jsonas{"text": "<the judgment, with its justification>"}, writingresponse.json.tmpfirst and then renaming it, so Studium never reads half a file. Then read.studium-session/feedback.mdand, if there is a newtask.md, continue. Do not look for the answer key: it is not there.
Learner-time runs
A reproduction scene can carry a run_manifest: the capsule, install and command, the files it
should produce and the checks to run, never the expected values. On such a scene Studium writes
run.json and a provision-and-run task.md, and logs awaiting_run. The operator provisions the
environment, installs the dependencies, runs the capsule in the workspace and writes
run_result.json.
| Result | What Studium does |
|---|---|
ran and passed |
Records the learner's own run (status: "ran", with its landmark and artifacts) and advances. |
| missing or partial | Keeps waiting. |
ran: false or failed checks |
Consumes it and writes a corrective feedback.md; the operator fixes and reruns. |
The author's reference landmark is withheld so the learner produces a fresh result. Over MCP the
same exchange is get_run_manifest then submit_run_result.
Run the harness
runStudiumSession(host, bundleRef, dir, operator) in @studium/lesson-session-host drives the
loop with a pluggable operator. The command-line runner wraps it:
# Watch mode (default): Studium writes task.md and waits for you or an assistant to write 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
# Stub mode: a key-free placeholder operator drives the loop to the end (a quick smoke test)
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
The --dir folder must be new. Without --stub, the runner waits for real answers. The
harness skill describes the formats.
Options: --bundles-root=DIR (default BUNDLES_ROOT, else ./fixtures), --dir=DIR (default
./.studium-session), --language=BCP47 (presentation language).
| Operator | Behaviour |
|---|---|
watchOperator({pollMs, timeoutMs}) |
Waits for an external assistant to write response.json or run_result.json. Studium never calls a model. |
stubOperator |
A deterministic placeholder; on a run scene it writes a passing result without executing anything. |
makeLlmOperator({llm, runCapsule}) |
An operator backed by a model that owns execution: it runs the capsule on a reproduction scene and asks the model to judge the AI reading of its own run. Both dependencies are injected. |
The model-backed demo runs the real capsule with tools/capsule_runner.py and a placeholder model,
or a live one with --live and 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
Execution and rendering belong to the editor
- Execution happens in the workspace terminal or notebook kernel, driven by the operator.
tools/capsule_runner.pystill produces an author's reference run once, to ground a scene; the learner's runs are requested throughrun.json(orget_run_manifest) and reported back. - Rendering is native: the VS Code notebook controller shows an
executed_resultor image figure inline with a caption, and the file channel carries the same reference.
What is covered
The file round trip is tested on fixtures/capsule-judgment-demo, with the answer key absent from
every task.md, and the learner-time run on fixtures/capsule-run-demo: the manifest carries no
answer, the author's landmark is withheld, and failed or missing runs recover. A passing run is
recorded as the learner's own result, which a later spot_the_flaw scene can be grounded on
(reference_from_run in the lesson bundle format).