dsh-diagnostic-tutor 0.1.0 → 0.2.0

package/lib/tools.js

@@ -18,9 +18,37 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { MAX_NODES_PER_UPDATE, acceptNewNodes, recordEvidence, setNodeState } from './diagnosis.js';
 import { withLesson } from './handoff.js';
-import { BLOCK_SCHEMAS, BlockSchema, LESSON_ORIGINS, MAX_BLOCKS_PER_LESSON, MAX_BLOCKS_PER_UPDATE, LessonSchema, } from './lesson.js';
-import { newNode } from './state.js';
+import { BLOCK_SCHEMAS, KnownBlockSchema, LESSON_ORIGINS, MAX_BLOCKS_PER_LESSON, MAX_BLOCKS_PER_UPDATE, MAX_LESSON_BYTES, LessonSchema, } from './lesson.js';
+import { renderMathFragments, renderTexToMathML } from './math.js';
+import { blocksMarkdown } from './lesson-markdown.js';
+import { AnswerSubmissionSchema, recordBlockResponse } from './interactions.js';
+import { newNode, PROJECT_BINDINGS, PROJECT_SELECTIONS } from './state.js';
 import { EVIDENCE_KINDS, NODE_RELATIONS, NODE_STATES, READINESS_OUTCOMES, targetRequirement, } from './vocabulary.js';
+import { planningTools } from './path-tools.js';
+import { sourceTools } from './source-tools.js';
+import { planTools } from './plan-tools.js';
+import { reviewTools } from './review-tools.js';
+import { syncLessonFlashcards } from './review-sync.js';
+import { activeAttempt } from './path.js';
+import { requireAttempt, writeCourseTeaching } from './path-runtime.js';
+/**
+ * The conversation a tool call belongs to.
+ *
+ * `udt_decide_next` is called by the model, which has no idea which
+ * conversation it is running in — but the harness does: every execution carries
+ * the agent on whose behalf it runs, and an agent is session-backed, so
+ * `agent.id` IS the session id. Without this the decision would be stored
+ * course-wide and one conversation's decision would overwrite another's, which
+ * is the bug this keying exists to fix.
+ *
+ * @param exec - the execution context the registry hands the tool.
+ * @returns the session id, or undefined when the call has no agent.
+ */
+function sessionOf(exec) {
+    const agent = exec?.agent;
+    const id = agent?.id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
 /* -------------------------------------------------------------------------- */
 /* Helpers                                                                    */
 /* -------------------------------------------------------------------------- */
@@ -63,16 +91,29 @@ function nowIso() {
 function violationMessage(violations) {
     return violations.map((entry) => `${entry.code}: ${entry.message}`).join(' | ');
 }
-/** Resolve the course a call refers to, defaulting to the learner's active goal. */
-function resolveCourseId(state, requested) {
-    const courseId = requested ?? state.readLearner().activeCourseId;
+/** Resolve an explicit shared course or this conversation's selected project. */
+function resolveCourseId(state, requested, project) {
+    const courseId = requested ?? project.course?.id;
     if (!courseId) {
-        throw new Error('no course given and the learner has no active goal; call udt_goal_create first or pass courseId');
+        throw new Error('no course given and this conversation has no selected project; call udt_goal_create for a new goal or pass courseId explicitly');
     }
     if (!state.readCourse(courseId))
         throw new Error(`no course "${courseId}"`);
     return courseId;
 }
+/** A tool write cannot silently work outside the conversation's selected project. */
+function requireProjectMatch(project, courseId) {
+    if (project.course !== undefined && project.course.id !== courseId) {
+        throw new Error(`this conversation selected course "${project.course.id}"; cannot write course "${courseId}" without selecting it first`);
+    }
+}
+const PROJECT_BINDING_PROPERTIES = {
+    projectAdopted: { type: 'boolean', required: true, description: 'Whether this write newly selected the project for this conversation.' },
+    projectBinding: {
+        type: 'string', required: true, enum: [...PROJECT_BINDINGS],
+        description: 'adopted | already-selected | not-selected | missing-session-id. Shared data can be stored without a conversation binding.',
+    },
+};
 /**
  * Project the state snapshot onto the tool's canonical output.
  *
@@ -83,8 +124,9 @@ function resolveCourseId(state, requested) {
  * location and version are internal diagnostics and must not become text a
  * model can echo back to a learner.
  */
-function statusValue(state) {
+function statusValue(state, sessionId) {
     const snapshot = state.snapshot();
+    const project = state.resolveProject(sessionId);
     const value = {
         domain: snapshot.domain,
         version: snapshot.version,
@@ -92,18 +134,30 @@ function statusValue(state) {
         courseCount: snapshot.courseCount,
         nodeCount: snapshot.nodeCount,
         courses: snapshot.courses.map((course) => ({ ...course })),
+        selection: project.selection,
+        sessionAvailable: project.sessionAvailable,
     };
-    const { preferredLanguage, mode, activeCourseId } = snapshot.learner;
+    if (project.course) {
+        const path = state.readPath(project.course.id);
+        const run = sessionId ? state.readCourseRun(project.course.id, sessionId) : undefined;
+        if (path || run)
+            value.learningPathContext = JSON.stringify({
+                tool: 'udt_path_get', courseId: project.course.id, revision: path?.revision ?? 0,
+                briefRevision: path?.briefRevision ?? 0, acceptedVersion: path?.acceptedVersion ?? null,
+                activeAttempt: (() => { const entry = activeAttempt(run); return entry ? { id: entry.id, itemId: entry.itemId, version: entry.version, nodeId: entry.nodeId, status: entry.status } : null; })(),
+            });
+    }
+    const { preferredLanguage, mode } = snapshot.learner;
     if (preferredLanguage !== undefined)
         value.preferredLanguage = preferredLanguage;
     if (mode !== undefined)
         value.mode = mode;
-    if (activeCourseId !== undefined)
-        value.activeCourseId = activeCourseId;
+    if (project.course !== undefined)
+        value.courseId = project.course.id;
     // The focus is how the tutor learns which node the learner asked to work on.
     // It is reported here rather than in a tool of its own: it is one fact about
     // the runtime, not a separate concern.
-    const focused = state.activeFocus();
+    const focused = sessionId === undefined ? undefined : state.activeFocus(sessionId);
     if (focused !== undefined) {
         value.focus = {
             courseId: focused.course.id,
@@ -115,8 +169,17 @@ function statusValue(state) {
     }
     // A recommendation the learner has not acted on yet. Reported so the tutor
     // can see its own last decision instead of re-deciding from scratch.
-    const courseId = focused?.course.id ?? state.readLearner().activeCourseId;
-    const pending = courseId === undefined ? undefined : state.latestNextStep(courseId);
+    //
+    // Read from the focus RECORD, not from the active focus: a decision that
+    // names a target ends the focus, so keying this off `activeFocus` would hide
+    // the recommendation in exactly the case it matters most — the tutor having
+    // just said where to go next.
+    const focusRecord = sessionId === undefined || project.course === undefined
+        ? undefined
+        : state.readFocus(sessionId, project.course.id);
+    const pending = sessionId === undefined || focusRecord?.nextStepId === undefined
+        ? undefined
+        : state.readNextStep(sessionId, focusRecord.nextStepId);
     if (pending !== undefined) {
         const from = state.readNode(pending.fromNodeId);
         const target = pending.targetNodeId === undefined ? undefined : state.readNode(pending.targetNodeId);
@@ -141,6 +204,11 @@ function udtStatusTool(state) {
             'initialized, the learner profile, the registered learning goals and how many diagnosis-map nodes exist. ' +
             'Call this before starting a session to see whether there is existing state to continue from, and after ' +
             'changing state to confirm what was stored. ' +
+            '`courses`, counts and preferences are learner-shared; `selection`, `courseId`, focus and next step belong only to this conversation. ' +
+            '`none` means no project selected; `new` means the learner asked to start a new project: use udt_goal_create for that goal, ' +
+            'and do not reuse a historical project as the current one. `project` names the selected course. ' +
+            'If sessionAvailable is false, conversation binding is unavailable. ' +
+            'If learningPathContext exists, read udt_path_get to continue goal setup, assessment, route or active planned teaching. ' +
             'Read-only: it records no teaching decision.',
         parameters: {},
         output: {
@@ -171,12 +239,15 @@ function udtStatusTool(state) {
                             },
                         },
                     },
+                    learningPathContext: { type: 'string', description: 'Stored curriculum/attempt context as JSON. Read udt_path_get before planned teaching, even when no node focus exists.' },
                     preferredLanguage: { type: 'string', description: 'Learner preference, when recorded.' },
                     mode: {
                         type: 'string',
                         description: 'Teaching mode preference: auto | zero-base | standard | advanced.',
                     },
-                    activeCourseId: { type: 'string', description: 'The learning goal currently in focus.' },
+                    selection: { type: 'string', required: true, enum: [...PROJECT_SELECTIONS], description: 'This conversation\'s project selection: none | new | project.' },
+                    sessionAvailable: { type: 'boolean', required: true, description: 'Whether this tool call has a reliable conversation id.' },
+                    courseId: { type: 'string', description: 'Only present for selection=project: this conversation\'s selected course.' },
                     focus: {
                         type: 'object',
                         additionalProperties: false,
@@ -214,11 +285,13 @@ function udtStatusTool(state) {
             render: (_args, value) => [
                 {
                     type: 'text',
-                    text: `Learning runtime: domain "${value.domain}" v${value.version}, ${value.courseCount} goal(s), ${value.nodeCount} map node(s), ${value.initialized ? 'learner state present' : 'first run (no learner state yet)'}.`,
+                    // Native tool messages carry render content, not the execute value.
+                    // The tutor must see the conversation selection and usable ids.
+                    text: JSON.stringify(value),
                 },
             ],
         },
-        execute: () => Promise.resolve(statusValue(state)),
+        execute: (_args, exec) => Promise.resolve(statusValue(state, sessionOf(exec))),
         presentCall: () => ({
             card: 'generic',
             title: 'Read learning-runtime status',
@@ -241,6 +314,10 @@ function udtStatusTool(state) {
  * active. Pausing is reversible and never touches the other goal's map.
  */
 function udtGoalCreateTool(state) {
+    // ID allocation must see the preceding creation's course, and activation
+    // must finish before another creation pauses it. A failed write releases
+    // the queue so later calls can still create goals.
+    let goalWrites = Promise.resolve();
     return defineTool({
         name: 'udt_goal_create',
         description: 'Record a learning goal and start its diagnosis map. ' +
@@ -248,7 +325,10 @@ function udtGoalCreateTool(state) {
             'This creates ONLY the goal and the single root node of the map — it never generates a course outline, ' +
             'syllabus or list of topics. Further nodes are added later, one at a time, as diagnosis reveals ' +
             'prerequisites or blockers (see udt_map_update). ' +
-            'Creating a goal focuses it and pauses any previously active goal.',
+            'Creating a goal marks it active in the shared library and pauses any previously active goal. ' +
+            'It selects this conversation\'s project only for none/new selection; an existing project choice is preserved. ' +
+            'Read projectBinding in the result to confirm whether the conversation is bound. ' +
+            'Then read udt_path_get. Interactively clarify purpose, observable target outcomes, time horizon and budget before initial diagnosis and a proposed course route. Planning has its own tools; never put an undiagnosed syllabus into the diagnosis map.',
         parameters: {
             title: {
                 type: 'string',
@@ -278,54 +358,65 @@ function udtGoalCreateTool(state) {
                         description: 'Goals that were active and are now paused.',
                         items: { type: 'string' },
                     },
+                    ...PROJECT_BINDING_PROPERTIES,
                 },
             },
             render: (_args, value) => [
                 {
                     type: 'text',
-                    text: `Goal recorded: "${value.title}" (${value.courseId}). Map starts with its root node only.`,
+                    text: JSON.stringify(value),
                 },
             ],
         },
-        execute: async (args) => {
+        execute: async (args, exec) => {
             const { title, goal } = args;
             const now = nowIso();
-            const taken = new Set(state.listCourses().map((course) => course.id));
-            const courseId = allocateId(slugify(title), taken);
-            const previouslyActive = state
-                .listCourses()
-                .filter((course) => course.status === 'active' && course.id !== courseId)
-                .map((course) => course.id);
-            await state.writeCourse({
-                id: courseId,
-                title,
-                goal,
-                status: 'active',
-                createdAt: now,
-                updatedAt: now,
-            });
-            // Focus it (this pauses the others) and point the learner at it.
-            await state.activateCourse(courseId, now);
-            const goalNode = newNode({
-                id: `${courseId}:goal`,
-                courseId,
-                title,
-                relation: 'goal',
-                // The goal node carries the learner's statement as evidence, yet stays
-                // `unconfirmed`: a goal is the frame of the map, not a mastery claim.
-                evidence: [{ kind: 'goal-stated', at: now, note: goal }],
-                now,
+            const sessionId = sessionOf(exec);
+            const project = state.resolveProject(sessionId);
+            // Capture the conversation choice before waiting: a choice made while
+            // this call is queued must invalidate its eventual adoption too.
+            const result = goalWrites.then(async () => {
+                const taken = new Set(state.listCourses().map((course) => course.id));
+                const courseId = allocateId(slugify(title), taken);
+                const previouslyActive = state
+                    .listCourses()
+                    .filter((course) => course.status === 'active' && course.id !== courseId)
+                    .map((course) => course.id);
+                await state.writeCourse({
+                    id: courseId,
+                    title,
+                    goal,
+                    status: 'active',
+                    createdAt: now,
+                    updatedAt: now,
+                });
+                // Focus it (this pauses the others) and point the learner at it.
+                await state.activateCourse(courseId, now);
+                const goalNode = newNode({
+                    id: `${courseId}:goal`,
+                    courseId,
+                    title,
+                    relation: 'goal',
+                    // The goal node carries the learner's statement as evidence, yet stays
+                    // `unconfirmed`: a goal is the frame of the map, not a mastery claim.
+                    evidence: [{ kind: 'goal-stated', at: now, note: goal }],
+                    now,
+                });
+                await state.writeNode(goalNode);
+                const binding = await state.adoptProject(sessionId, courseId, now, project, true);
+                return {
+                    courseId,
+                    title,
+                    goal,
+                    status: 'active',
+                    createdAt: now,
+                    goalNodeId: goalNode.id,
+                    pausedCourseIds: previouslyActive,
+                    ...binding,
+                };
             });
-            await state.writeNode(goalNode);
-            return {
-                courseId,
-                title,
-                goal,
-                status: 'active',
-                createdAt: now,
-                goalNodeId: goalNode.id,
-                pausedCourseIds: previouslyActive,
-            };
+            goalWrites = result.catch(() => undefined);
+            return result;
         },
         presentCall: (args) => ({
             card: 'generic',
@@ -345,9 +436,9 @@ function udtMapGetTool(state) {
             'recorded against it. Use this to decide the next diagnostic step. ' +
             'A node state is one of: unconfirmed (no evidence yet), explained, practiced, checked, weak, blocked, ' +
             'confirmed. Nothing here is a progress percentage or a score. ' +
-            'Omit courseId to read the learner\'s active goal.',
+            'Omit courseId to read this conversation\'s selected project. An explicit courseId reads shared data without selecting it.',
         parameters: {
-            courseId: { type: 'string', description: 'Goal to read; defaults to the active goal.' },
+            courseId: { type: 'string', description: 'Goal to read; defaults only to this conversation\'s selected project.' },
         },
         output: {
             schema: {
@@ -400,14 +491,12 @@ function udtMapGetTool(state) {
             render: (_args, value) => [
                 {
                     type: 'text',
-                    text: `Map for "${value.title}": ${value.nodes.length} node(s) — ${value.nodes
-                        .map((node) => `${node.title} [${node.state}]`)
-                        .join(', ')}`,
+                    text: JSON.stringify(value),
                 },
             ],
         },
-        execute: (args) => {
-            const courseId = resolveCourseId(state, args.courseId);
+        execute: (args, exec) => {
+            const courseId = resolveCourseId(state, args.courseId, state.resolveProject(sessionOf(exec)));
             const map = state.readMap(courseId);
             if (!map)
                 throw new Error(`no course "${courseId}"`);
@@ -451,11 +540,14 @@ function udtMapUpdateTool(state) {
             '(part-of | prerequisite | related | goal). Nodes are born "unconfirmed" unless you pass `state`.\n' +
             '• "set-state" — move one node to a new state. "confirmed" is REFUSED unless the node already carries a ' +
             'check or transfer evidence entry; explanation or practice alone never confirms.\n' +
-            '• "add-evidence" — append one observation to a node. Record what happened, not how good it was.\n' +
+            '• "add-evidence" — append one observation to a node. Record what happened, not how good it was. ' +
+            'During an active planned lesson, supply its explicit attemptId and bound nodeId; the runtime stamps the conversation/attempt provenance. Stale attempts are refused.\n' +
             'A single call may add at most 8 nodes and a map holds at most 40. Never use this to plant a whole ' +
-            'syllabus: add only what the current diagnosis justifies.',
+            'syllabus: add only what the current diagnosis justifies. ' +
+            'An explicit courseId/nodeId write may select the project only when this conversation has no selection. ' +
+            'Historical writes never replace new/project selection; check projectBinding in the result.',
         parameters: {
-            courseId: { type: 'string', description: 'Goal to update; defaults to the active goal.' },
+            courseId: { type: 'string', description: 'Goal to update; defaults to this conversation\'s selected project, or the explicitly named node\'s course.' },
             op: {
                 type: 'string',
                 required: true,
@@ -476,7 +568,8 @@ function udtMapUpdateTool(state) {
                     },
                 },
             },
-            nodeId: { type: 'string', description: 'For op=set-state / add-evidence: the target node.' },
+            nodeId: { type: 'string', description: 'For op=set-state / add-evidence: the target node. Planned evidence must use the active attempt\'s bound node.' },
+            attemptId: { type: 'string', description: 'For op=add-evidence during planned learning: required active attemptId from udt_path_get. Provenance is stamped by the runtime.' },
             state: { type: 'string', enum: [...NODE_STATES], description: 'For op=set-state: the new state.' },
             evidenceKind: {
                 type: 'string',
@@ -508,20 +601,24 @@ function udtMapUpdateTool(state) {
                     state: { type: 'string', description: 'The node\'s state after this call.' },
                     evidenceCount: { type: 'integer', description: 'Evidence entries on the node after this call.' },
                     nodeCount: { type: 'integer', required: true, description: 'Total nodes in the course after this call.' },
+                    ...PROJECT_BINDING_PROPERTIES,
                 },
             },
             render: (_args, value) => [
                 {
                     type: 'text',
-                    text: value.op === 'add-nodes'
-                        ? `Added ${value.addedNodeIds.length} node(s); the map now has ${value.nodeCount}.`
-                        : `Node ${value.nodeId ?? ''} is now "${value.state ?? ''}" with ${value.evidenceCount ?? 0} evidence entr(ies).`,
+                    text: JSON.stringify(value),
                 },
             ],
         },
-        execute: async (args) => {
+        execute: async (args, exec) => {
             const input = args;
-            const courseId = resolveCourseId(state, input.courseId);
+            const sessionId = sessionOf(exec);
+            const project = state.resolveProject(sessionId);
+            const nodeCourseId = input.op === 'add-nodes' || input.nodeId === undefined
+                ? undefined : state.readNode(input.nodeId)?.courseId;
+            const courseId = resolveCourseId(state, input.courseId ?? nodeCourseId, project);
+            requireProjectMatch(project, courseId);
             const now = input.at ?? nowIso();
             const existing = state.listNodes(courseId);
             if (input.op === 'add-nodes') {
@@ -562,6 +659,7 @@ function udtMapUpdateTool(state) {
                     op: input.op,
                     addedNodeIds: structured.map((node) => node.id),
                     nodeCount: existing.length + structured.length,
+                    ...await state.adoptProject(sessionId, courseId, now, project),
                 };
             }
             // Both remaining ops target exactly one node.
@@ -591,6 +689,7 @@ function udtMapUpdateTool(state) {
                     state: stored.state,
                     evidenceCount: stored.evidence.length,
                     nodeCount: existing.length,
+                    ...await state.adoptProject(sessionId, courseId, now, project),
                 };
             }
             // op === 'add-evidence'
@@ -602,13 +701,23 @@ function udtMapUpdateTool(state) {
                 ...(input.evidenceNote === undefined ? {} : { note: input.evidenceNote }),
                 ...(input.readiness === undefined ? {} : { readiness: input.readiness }),
             };
-            const result = recordEvidence(node, evidence, {
-                now,
-                ...(input.state === undefined ? {} : { state: input.state }),
+            const stored = await state.mutateNode(courseId, nodeId, (current) => {
+                requireProjectMatch(state.resolveProject(sessionId), courseId);
+                const planned = sessionId ? activeAttempt(state.readCourseRun(courseId, sessionId)) : undefined;
+                if (planned && ['requested', 'working'].includes(planned.status) && !input.attemptId)
+                    throw new Error('planned-evidence-needs-attemptId: read udt_path_get and bind its diagnosed node');
+                const attempt = input.attemptId ? requireAttempt(state, courseId, sessionId, input.attemptId) : undefined;
+                if (attempt && attempt.nodeId !== current.id)
+                    throw new Error('bind-the-node-before-recording-planned-evidence');
+                const trusted = attempt ? { ...evidence, sessionId: sessionId, attemptId: attempt.id } : evidence;
+                const result = recordEvidence(current, trusted, {
+                    now,
+                    ...(input.state === undefined ? {} : { state: input.state }),
+                });
+                if (!result.ok)
+                    throw new Error(violationMessage(result.violations));
+                return result.node;
             });
-            if (!result.ok)
-                throw new Error(violationMessage(result.violations));
-            const stored = await state.writeNode(result.node);
             return {
                 courseId,
                 op: input.op,
@@ -617,6 +726,7 @@ function udtMapUpdateTool(state) {
                 state: stored.state,
                 evidenceCount: stored.evidence.length,
                 nodeCount: existing.length,
+                ...await state.adoptProject(sessionId, courseId, now, project),
             };
         },
         presentCall: (args) => ({
@@ -645,6 +755,17 @@ const BLOCK_PARAM_SPEC = {
             additionalProperties: false,
             properties: {
                 id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
                 type: { type: 'string', required: true, enum: ['text'] },
                 content: {
                     type: 'object',
@@ -658,6 +779,17 @@ const BLOCK_PARAM_SPEC = {
             additionalProperties: false,
             properties: {
                 id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
                 type: { type: 'string', required: true, enum: ['example'] },
                 content: {
                     type: 'object',
@@ -675,6 +807,17 @@ const BLOCK_PARAM_SPEC = {
             additionalProperties: false,
             properties: {
                 id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
                 type: { type: 'string', required: true, enum: ['diagram'] },
                 content: {
                     type: 'object',
@@ -692,6 +835,17 @@ const BLOCK_PARAM_SPEC = {
             additionalProperties: false,
             properties: {
                 id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
                 type: { type: 'string', required: true, enum: ['check'] },
                 content: {
                     type: 'object',
@@ -704,6 +858,200 @@ const BLOCK_PARAM_SPEC = {
                 },
             },
         },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
+                type: { type: 'string', required: true, enum: ['formula'] },
+                content: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        tex: { type: 'string', required: true, description: 'TeX source without delimiters.' },
+                        display: { type: 'boolean' },
+                        caption: { type: 'string' },
+                    },
+                },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
+                type: { type: 'string', required: true, enum: ['code'] },
+                content: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        language: { type: 'string' },
+                        source: { type: 'string', required: true },
+                        caption: { type: 'string' },
+                    },
+                },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
+                type: { type: 'string', required: true, enum: ['quiz'] },
+                content: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        title: { type: 'string' },
+                        questions: {
+                            type: 'array', required: true,
+                            items: {
+                                type: 'object', additionalProperties: false,
+                                properties: {
+                                    id: { type: 'string', required: true },
+                                    sourceRefs: {
+                                        type: 'array',
+                                        items: {
+                                            type: 'object',
+                                            additionalProperties: false,
+                                            properties: {
+                                                sourceId: { type: 'string', required: true },
+                                                locator: { type: 'string', required: true },
+                                            },
+                                        },
+                                    },
+                                    kind: { type: 'string', required: true, enum: ['mcq', 'short'] },
+                                    prompt: { type: 'string', required: true },
+                                    options: { type: 'array', items: { type: 'string' } },
+                                    answer: { type: 'string' },
+                                    rubric: { type: 'string' },
+                                    explanation: { type: 'string' },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
+                type: { type: 'string', required: true, enum: ['flashcard'] },
+                content: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        front: { type: 'string', required: true },
+                        back: { type: 'string', required: true },
+                        tags: { type: 'array', items: { type: 'string' } },
+                    },
+                },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
+                type: { type: 'string', required: true, enum: ['resource'] },
+                content: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        title: { type: 'string', required: true },
+                        sourceId: { type: 'string' },
+                        locator: { type: 'string' },
+                        url: { type: 'string' },
+                        note: { type: 'string' },
+                    },
+                },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                id: { type: 'string', required: true },
+                sourceRefs: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            sourceId: { type: 'string', required: true },
+                            locator: { type: 'string', required: true },
+                        },
+                    },
+                },
+                type: { type: 'string', required: true, enum: ['comparison'] },
+                content: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        columns: { type: 'array', required: true, items: { type: 'string' } },
+                        rows: { type: 'array', required: true, items: { type: 'array', items: { type: 'string' } } },
+                        caption: { type: 'string' },
+                    },
+                },
+            },
+        },
     ],
 };
 /**
@@ -718,6 +1066,54 @@ const BLOCK_PARAM_SPEC = {
  * and the next unit follows. `replace` exists for revising a unit that was
  * wrong, not for regenerating a course.
  */
+/**
+ * Attach host-rendered MathML to the two block types that carry formulas.
+ *
+ * This runs before `BlockSchema.parse`, so an invalid formula block is refused
+ * with the block index, while a bad inline expression in a text block is left
+ * as source for the client's styled fallback.
+ */
+function prepareMath(candidate, index) {
+    if (candidate === null || typeof candidate !== 'object')
+        return candidate;
+    const block = candidate;
+    if (block.type === 'text' && block.content !== null && typeof block.content === 'object') {
+        const content = block.content;
+        if (typeof content.md !== 'string')
+            return candidate;
+        const math = renderMathFragments(content.md);
+        const { math: _old, ...rest } = content;
+        return { ...block, content: math.length === 0 ? rest : { ...rest, math } };
+    }
+    if (block.type === 'formula' && block.content !== null && typeof block.content === 'object') {
+        const content = block.content;
+        if (typeof content.tex !== 'string')
+            return candidate;
+        const mathml = renderTexToMathML(content.tex, content.display === true);
+        return { ...block, content: { ...content, mathml } };
+    }
+    return candidate;
+}
+/**
+ * Source references are cross-table facts: the block schema can only check
+ * their shape, so the write boundary checks that every cited source exists.
+ * A dangling citation is refused rather than rendered as a broken footnote.
+ */
+function assertSources(state, block, index) {
+    const references = block.sourceRefs ?? [];
+    for (const reference of references) {
+        const source = state.readSource(reference.sourceId);
+        if (source === undefined || source.status !== 'ready') {
+            throw new Error(`block[${index}] references unknown source "${reference.sourceId}" — add it with udt_source_add first`);
+        }
+    }
+    if (block.type === 'resource' && block.content.sourceId !== undefined) {
+        const source = state.readSource(block.content.sourceId);
+        if (source === undefined || source.status !== 'ready') {
+            throw new Error(`block[${index}] references unknown source "${block.content.sourceId}" — add it with udt_source_add first`);
+        }
+    }
+}
 function udtLessonUpdateTool(state) {
     return defineTool({
         name: 'udt_lesson_update',
@@ -725,19 +1121,26 @@ function udtLessonUpdateTool(state) {
             'The blocks appear in the panel beside the diagnosis map, so the learner reads them while ' +
             'answering in the chat — write for that surface, not as a chat message.\n' +
             'Block types: **text** {md}, **example** {title, steps[], takeaway?}, ' +
-            '**diagram** {format: ascii|mermaid, spec, caption?}, **check** {prompt, expect?, hint?}.\n' +
+            '**diagram** {format: ascii|mermaid, spec, caption?}, **check** {prompt, expect?, hint?}, ' +
+            '**formula** {tex, display?, caption?}, **code** {language?, source, caption?}, ' +
+            '**quiz** {title?, questions[]}, **flashcard** {front, back, tags?}, ' +
+            '**resource** {title, sourceId?, locator?, url?, note?}, **comparison** {columns[], rows[][], caption?}.\n' +
             `At most ${MAX_BLOCKS_PER_UPDATE} blocks per call and ${MAX_BLOCKS_PER_LESSON} per lesson; a teaching unit is a few ` +
             'blocks, not a chapter.\n' +
             '**Write your first unit as soon as you know it** rather than composing the whole thing first: ' +
             'the blocks appear in the learner\'s surface the moment you send them, so a short first unit ' +
             'turns a silent wait into visible progress. Send more later with append.\n' +
             'Default mode "append" adds to the current lesson; use "replace" only to correct what is there.\n' +
-            'A check block has no input box: the surface displays the question and the learner answers in the chat.',
+            'A check block has no input box: the surface displays the question and the learner answers in the chat. ' +
+            'An explicit nodeId write may select its project only when this conversation has no selection. ' +
+            'It never replaces new/project selection; check projectBinding in the result. ' +
+            'For planned teaching, read udt_path_get, explicitly bind its node with udt_course_run_update and supply active attemptId. Content is saved per conversation/attempt with history; stale attempts are rejected.',
         parameters: {
             nodeId: {
                 type: 'string',
-                description: 'Node to write for. Omit to use the learner\'s current focus (see udt_status).',
+                description: 'Node to write for. Omit to use this conversation\'s current focus (see udt_status).',
             },
+            attemptId: { type: 'string', description: 'Required for planned teaching: active attemptId from udt_path_get.' },
             title: { type: 'string', description: 'Lesson title; defaults to the node title.' },
             mode: {
                 type: 'string',
@@ -762,34 +1165,40 @@ function udtLessonUpdateTool(state) {
                     mode: { type: 'string', required: true },
                     blockCount: { type: 'integer', required: true, description: 'Blocks in the lesson after this call.' },
                     addedCount: { type: 'integer', required: true },
+                    reviewCardCount: { type: 'integer', required: true, description: 'Flashcards now linked to review cards.' },
+                    markdown: { type: 'string', required: true, description: 'Plain Markdown projection for harnesses without the panel.' },
                     origin: { type: 'string', required: true },
+                    ...PROJECT_BINDING_PROPERTIES,
                 },
             },
             render: (_args, value) => [
                 {
                     type: 'text',
-                    text: `Learning surface updated: ${value.addedCount} block(s) ${value.mode === 'replace' ? 'replacing' : 'added to'} the lesson for "${value.nodeId}" (now ${value.blockCount}).`,
+                    text: JSON.stringify(value),
                 },
             ],
         },
-        execute: async (args) => {
+        execute: async (args, exec) => {
             const input = args;
             const mode = input.mode ?? 'append';
-            const focused = state.activeFocus();
-            const courseId = focused?.course.id ?? state.readLearner().activeCourseId;
-            if (courseId === undefined) {
-                throw new Error('no active course; record a goal and start learning on a node first');
-            }
-            const nodeId = input.nodeId ?? focused?.node.id;
+            const sessionId = sessionOf(exec);
+            const project = state.resolveProject(sessionId);
+            const focused = sessionId === undefined ? undefined : state.activeFocus(sessionId);
+            const planned = sessionId && project.course ? activeAttempt(state.readCourseRun(project.course.id, sessionId)) : undefined;
+            if (planned && ['requested', 'working'].includes(planned.status) && !input.attemptId)
+                throw new Error('planned-lesson-needs-attemptId: read udt_path_get and bind its diagnosed node');
+            const attempt = input.attemptId && project.course ? requireAttempt(state, project.course.id, sessionId, input.attemptId) : undefined;
+            if (input.attemptId && !attempt)
+                throw new Error('no-active-course-attempt');
+            const nodeId = input.nodeId ?? attempt?.nodeId ?? focused?.node.id;
             if (nodeId === undefined) {
                 throw new Error('no nodeId given and no learning focus is active; call udt_status to see the focus');
             }
             const node = state.readNode(nodeId);
             if (node === undefined)
                 throw new Error(`no node "${nodeId}"`);
-            if (node.courseId !== courseId) {
-                throw new Error(`node "${nodeId}" belongs to course "${node.courseId}", not "${courseId}"`);
-            }
+            const courseId = resolveCourseId(state, node.courseId, project);
+            requireProjectMatch(project, courseId);
             if (!Array.isArray(input.blocks) || input.blocks.length === 0) {
                 throw new Error('`blocks` must be a non-empty array');
             }
@@ -798,9 +1207,11 @@ function udtLessonUpdateTool(state) {
                     'Write one teaching unit, not a chapter.');
             }
             // Strict, and it names the offending block: a model that sent one bad
-            // block should not have to guess which.
-            const parsed = input.blocks.map((candidate, index) => {
-                const result = BlockSchema.safeParse(candidate);
+            // block should not have to guess which. Host-owned MathML is generated
+            // here so the model never supplies markup the client would trust.
+            const prepared = input.blocks.map((candidate, index) => prepareMath(candidate, index));
+            const parsed = prepared.map((candidate, index) => {
+                const result = KnownBlockSchema.safeParse(candidate);
                 if (!result.success) {
                     const issue = result.error.issues[0];
                     const where = issue === undefined ? '' : `${issue.path.join('.') || '(root)'}: ${issue.message}`;
@@ -808,31 +1219,44 @@ function udtLessonUpdateTool(state) {
                 }
                 return result.data;
             });
-            const now = nowIso();
-            const existing = state.lessonForNode(nodeId);
-            const blocks = mode === 'replace' ? parsed : [...(existing?.blocks ?? []), ...parsed];
-            if (blocks.length > MAX_BLOCKS_PER_LESSON) {
-                throw new Error(`a lesson holds at most ${MAX_BLOCKS_PER_LESSON} blocks; this would make ${blocks.length}. ` +
-                    'Replace the lesson or start a new node.');
+            parsed.forEach((block, index) => assertSources(state, block, index));
+            if (Buffer.byteLength(JSON.stringify(parsed), 'utf8') > MAX_LESSON_BYTES) {
+                throw new Error(`blocks are too large; the whole unit must stay under ${MAX_LESSON_BYTES} bytes`);
             }
-            const lesson = LessonSchema.parse({
-                id: existing?.id ?? `${nodeId}:lesson`,
-                courseId,
-                nodeId,
-                title: input.title ?? existing?.title ?? node.title,
-                blocks,
-                // Real teaching, written by the tutor — never the v0.0.4 scaffold.
-                origin: 'tutor',
-                createdAt: existing?.createdAt ?? now,
-                updatedAt: now,
-            });
-            await state.writeLesson(lesson);
+            const buildLesson = (existing) => {
+                const blocks = mode === 'replace' ? parsed : [...(existing?.blocks ?? []), ...parsed];
+                if (blocks.length > MAX_BLOCKS_PER_LESSON) {
+                    throw new Error(`a lesson holds at most ${MAX_BLOCKS_PER_LESSON} blocks; this would make ${blocks.length}. ` +
+                        'Replace the lesson or start a new node.');
+                }
+                const now = nowIso();
+                return LessonSchema.parse({
+                    id: existing?.id ?? (attempt ? `${attempt.id}:${nodeId}:lesson` : `${nodeId}:lesson`),
+                    courseId,
+                    nodeId,
+                    title: input.title ?? existing?.title ?? state.readNode(nodeId).title,
+                    blocks,
+                    origin: 'tutor',
+                    createdAt: existing?.createdAt ?? now,
+                    updatedAt: now,
+                });
+            };
+            const lesson = attempt && sessionId
+                ? await writeCourseTeaching(state, courseId, sessionId, attempt.id, nodeId, buildLesson)
+                : await state.mutateLesson(courseId, nodeId, (existing) => {
+                    requireProjectMatch(state.resolveProject(sessionId), courseId);
+                    const current = sessionId ? activeAttempt(state.readCourseRun(courseId, sessionId)) : undefined;
+                    if (current && ['requested', 'working'].includes(current.status))
+                        throw new Error('planned-lesson-needs-attemptId: read udt_path_get and bind its diagnosed node');
+                    return buildLesson(existing);
+                });
+            const now = lesson.updatedAt;
             // The tutor has produced teaching for this node: the handoff that was
             // waiting on it is now ready, and its timing chain closes.
             // Atomic and monotonic: a lesson can only move a handoff forward, never
             // back, so a late activity event cannot undo it.
-            if (state.readHandoff(nodeId) !== undefined) {
-                await state.updateHandoff(nodeId, (current) => withLesson(current, now));
+            if (sessionId !== undefined && state.readHandoff(sessionId, nodeId) !== undefined) {
+                await state.updateHandoff(sessionId, nodeId, (current) => withLesson(current, now));
             }
             return {
                 lessonId: lesson.id,
@@ -841,7 +1265,10 @@ function udtLessonUpdateTool(state) {
                 mode,
                 blockCount: lesson.blocks.length,
                 addedCount: parsed.length,
+                reviewCardCount: (await syncLessonFlashcards(state, { courseId, nodeId, lesson, now })).length,
+                markdown: blocksMarkdown(lesson.blocks),
                 origin: lesson.origin,
+                ...await state.adoptProject(sessionId, courseId, now, project),
             };
         },
         presentCall: (args) => ({
@@ -853,6 +1280,59 @@ function udtLessonUpdateTool(state) {
     });
 }
 /* -------------------------------------------------------------------------- */
+/* udt_quiz_update                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Record a learner's quiz/flashcard submission. This is storage, not judgement:
+ * it never changes a node state, never marks mastery and never advances a lesson.
+ * The tutor can read the submission through udt_path_get and decide what to say.
+ */
+function udtQuizUpdateTool(state) {
+    return defineTool({
+        name: 'udt_quiz_update',
+        description: 'Record the learner\'s answers for a quiz or flashcard block on the active course attempt. ' +
+            'This only records what was submitted; it does NOT grade, does not change a node state, and does not advance the lesson. ' +
+            'Use the active attemptId from udt_path_get; stale or inactive attempts are refused. ' +
+            'For a quiz, answer each question id with one of the offered options (or free text for a short question). ' +
+            'For a flashcard, answer with the card block id and value again | got-it.',
+        parameters: {
+            attemptId: { type: 'string', required: true },
+            blockId: { type: 'string', required: true },
+            answers: {
+                type: 'array', required: true,
+                items: {
+                    type: 'object', additionalProperties: false,
+                    properties: {
+                        questionId: { type: 'string', required: true },
+                        value: { type: 'string', required: true },
+                    },
+                },
+            },
+        },
+        output: { schema: { type: 'object', additionalProperties: true }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] },
+        execute: async (args, exec) => {
+            const input = args;
+            const sessionId = sessionOf(exec);
+            if (sessionId === undefined)
+                throw new Error('quiz-write-requires-a-conversation');
+            const project = state.resolveProject(sessionId);
+            if (project.course === undefined)
+                throw new Error('no-selected-project: open a project first');
+            const path = state.readPath(project.course.id);
+            if (path === undefined)
+                throw new Error('no-learning-path: ask for a route first');
+            const submission = AnswerSubmissionSchema.parse(input);
+            const view = await recordBlockResponse(state, {
+                courseId: project.course.id,
+                sessionId,
+                expectedRevision: path.revision,
+                ...submission,
+            });
+            return JSON.parse(JSON.stringify(view));
+        },
+    });
+}
+/* -------------------------------------------------------------------------- */
 /* udt_decide_next                                                            */
 /* -------------------------------------------------------------------------- */
 /**
@@ -928,12 +1408,16 @@ function udtDecideNextTool(state) {
                 },
             ],
         },
-        execute: async (args) => {
+        execute: async (args, exec) => {
             const input = args;
-            const focused = state.activeFocus();
-            const courseId = focused?.course.id ?? state.readLearner().activeCourseId;
+            const sessionId = sessionOf(exec);
+            if (sessionId === undefined) {
+                throw new Error('this call has no conversation; a decision must be recorded in one');
+            }
+            const focused = state.activeFocus(sessionId);
+            const courseId = state.resolveProject(sessionId).course?.id;
             if (courseId === undefined) {
-                throw new Error('no active course; record a goal and start learning on a node first');
+                throw new Error('this conversation has no selected project; record a goal or select a project and start learning on a node first');
             }
             const fromNodeId = input.fromNodeId ?? focused?.node.id;
             if (fromNodeId === undefined) {
@@ -957,6 +1441,7 @@ function udtDecideNextTool(state) {
                 ...(input.targetNodeId === undefined ? {} : { targetNodeId: input.targetNodeId }),
                 reason: input.reason,
                 now: nowIso(),
+                sessionId,
             });
             return {
                 fromNodeId: nextStep.fromNodeId,
@@ -982,13 +1467,25 @@ function udtDecideNextTool(state) {
  *
  * @param host - the context slice carrying the tools registry.
  * @param state - the open persistence handle the tools read from and write to.
+ * @returns how many tools were registered, so the loader log cannot drift from
+ *   the registry itself (it used to say "4" while nine were registered).
  */
 export function registerTools(host, state) {
-    host.tools.register(udtStatusTool(state));
-    host.tools.register(udtGoalCreateTool(state));
-    host.tools.register(udtMapGetTool(state));
-    host.tools.register(udtMapUpdateTool(state));
-    host.tools.register(udtLessonUpdateTool(state));
-    host.tools.register(udtDecideNextTool(state));
+    const core = [
+        udtStatusTool(state),
+        udtGoalCreateTool(state),
+        udtMapGetTool(state),
+        udtMapUpdateTool(state),
+        udtLessonUpdateTool(state),
+        udtQuizUpdateTool(state),
+        udtDecideNextTool(state),
+    ];
+    const planning = planningTools(state);
+    const sources = sourceTools(state);
+    const plan = planTools(state);
+    const review = reviewTools(state);
+    for (const tool of [...core, ...planning, ...sources, ...plan, ...review])
+        host.tools.register(tool);
+    return core.length + planning.length + sources.length + plan.length + review.length;
 }
 //# sourceMappingURL=tools.js.map