dsh-diagnostic-tutor 0.1.1 → 0.2.0

package/lib/diagnostics.js

@@ -0,0 +1,170 @@
+/**
+ * Read-only health report for the tutoring runtime.
+ *
+ * The report is what "doctor" shows and what the local `/diagnostics` route
+ * returns. It is computed from durable state plus the recent event journal; it
+ * never writes, never calls a model and never includes lesson or chat content.
+ */
+import { briefReady } from './path.js';
+const STALE_REQUEST_MINUTES = 10;
+const STALLED_ATTEMPT_MINUTES = 15;
+function minutesBetween(now, iso) {
+    const at = Date.parse(iso);
+    return Number.isFinite(at) ? Math.max(0, Math.round((now - at) / 60_000)) : 0;
+}
+function assessmentReady(path) {
+    return path.assessment !== null
+        && path.assessment.briefRevision === path.briefRevision
+        && (path.assessment.status === 'ready' || path.assessment.status === 'skipped');
+}
+function unresolved(request, path) {
+    if (request.kind === 'diagnosis') {
+        const assessment = path.assessment;
+        return assessment === null || assessment.status === 'in-progress' || assessment.updatedAt < request.createdAt;
+    }
+    return !path.curricula.some((entry) => entry.createdAt >= request.createdAt);
+}
+/**
+ * Build one diagnostics report.
+ *
+ * @param state - open state handle.
+ * @param journal - journal whose recent events are included.
+ * @param options - clock and plugin identity for tests.
+ * @returns the report.
+ */
+export async function buildDiagnostics(state, journal, options = {}) {
+    const now = options.now ?? new Date().toISOString();
+    const nowMs = Date.parse(now);
+    const exported = state.exportState(now);
+    const paths = new Map(exported.learningPaths.map((path) => [path.courseId, path]));
+    const runs = new Map(exported.courseRuns.map((run) => [run.courseId, run]));
+    const issues = [];
+    const projects = [];
+    for (const course of [...exported.courses].sort((left, right) => left.id.localeCompare(right.id))) {
+        const path = paths.get(course.id);
+        if (path === undefined) {
+            projects.push({
+                courseId: course.id, title: course.title, status: course.status, stage: 'legacy',
+                briefRevision: 0, assessment: null, curricula: 0, acceptedVersion: null,
+                requests: [], activeAttempt: null, completedItems: 0, totalItems: 0,
+            });
+            continue;
+        }
+        const ready = assessmentReady(path);
+        const accepted = path.acceptedVersion !== null
+            && path.curricula.some((entry) => entry.version === path.acceptedVersion);
+        const stage = !briefReady(path.brief)
+            ? 'goal'
+            : !ready
+                ? 'diagnosis'
+                : accepted
+                    ? 'learning'
+                    : 'route';
+        const run = runs.get(course.id);
+        const attempt = run?.attempts.find((entry) => entry.id === run.activeAttemptId);
+        const activeAttempt = attempt === undefined ? null : {
+            attemptId: attempt.id,
+            itemId: attempt.itemId,
+            status: attempt.status,
+            startedAt: attempt.startedAt,
+            ageMinutes: minutesBetween(nowMs, attempt.startedAt),
+            units: attempt.units.length,
+            nodeId: attempt.nodeId,
+        };
+        const pending = path.requests
+            .filter((request) => request.prompted
+            && ((request.failure !== null && request.failure !== undefined) || unresolved(request, path)))
+            .map((request) => ({
+            id: request.id,
+            kind: request.kind,
+            sessionId: request.sessionId,
+            createdAt: request.createdAt,
+            ageMinutes: minutesBetween(nowMs, request.createdAt),
+            prompted: request.prompted,
+            failure: request.failure ?? null,
+        }));
+        const acceptedPlan = path.curricula.find((entry) => entry.version === path.acceptedVersion) ?? path.curricula.at(-1);
+        const completedItems = new Set((run?.attempts ?? []).filter((entry) => entry.status === 'completed').map((entry) => entry.itemId)).size;
+        projects.push({
+            courseId: course.id,
+            title: course.title,
+            status: course.status,
+            stage,
+            briefRevision: path.briefRevision,
+            assessment: path.assessment?.status ?? null,
+            curricula: path.curricula.length,
+            acceptedVersion: path.acceptedVersion,
+            requests: pending,
+            activeAttempt,
+            completedItems,
+            totalItems: acceptedPlan?.items.length ?? 0,
+        });
+        for (const request of pending) {
+            if (request.failure !== null) {
+                issues.push({
+                    code: 'failed-turn',
+                    severity: 'error',
+                    courseId: course.id,
+                    message: `${request.kind} request ${request.id.slice(0, 8)} failed after waking the tutor: ${request.failure.slice(0, 240)}`,
+                });
+            }
+            else if (request.ageMinutes >= STALE_REQUEST_MINUTES) {
+                issues.push({
+                    code: 'stale-request',
+                    severity: 'warn',
+                    courseId: course.id,
+                    message: `${request.kind} request ${request.id.slice(0, 8)} has been waiting for ${request.ageMinutes} min without advancing`,
+                });
+            }
+        }
+        if (path.acceptedVersion !== null && !accepted) {
+            issues.push({
+                code: 'accepted-route-missing',
+                severity: 'error',
+                courseId: course.id,
+                message: `acceptedVersion ${path.acceptedVersion} has no matching curriculum revision`,
+            });
+        }
+        if (activeAttempt !== null && activeAttempt.status !== 'completed' && activeAttempt.units === 0
+            && activeAttempt.ageMinutes >= STALLED_ATTEMPT_MINUTES) {
+            issues.push({
+                code: 'stalled-attempt',
+                severity: 'warn',
+                courseId: course.id,
+                message: `lesson attempt ${activeAttempt.attemptId.slice(0, 8)} has no teaching units after ${activeAttempt.ageMinutes} min`,
+            });
+        }
+    }
+    const courseIds = new Set(exported.courses.map((course) => course.id));
+    for (const project of exported.projects) {
+        if (project.courseId !== undefined && !courseIds.has(project.courseId)) {
+            issues.push({
+                code: 'orphan-project-selection',
+                severity: 'warn',
+                message: `session ${project.sessionId} is bound to missing project ${project.courseId}`,
+            });
+        }
+    }
+    return {
+        ok: true,
+        generatedAt: now,
+        plugin: { name: 'dsh-diagnostic-tutor', version: options.pluginVersion ?? 'unknown' },
+        domain: exported.domain,
+        counts: {
+            courses: exported.courses.length,
+            nodes: exported.nodes.length,
+            lessons: exported.lessons.length,
+            focus: exported.focus.length,
+            projects: exported.projects.length,
+            learningPaths: exported.learningPaths.length,
+            courseRuns: exported.courseRuns.length,
+        },
+        issues,
+        projects,
+        journal: {
+            file: journal.file,
+            recent: await journal.tail(options.events ?? 40),
+        },
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/lib/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"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"}

package/lib/index.js

@@ -6,17 +6,23 @@
  * on unload.
  *
  * ---------------------------------------------------------------------------
- * v0.0.3 scope (see docs/planning/PLAN.md §7)
+ * Scope in v0.2.0 (content/input/review loop on top of the published learning runtime)
  * ---------------------------------------------------------------------------
- * Goal → detection → diagnosis map. The runtime now carries real product
- * semantics: it records a learning goal in the learner's words, plants a map
- * root, and lets a map grow one diagnosis at a time under rules that make
- * unverified mastery impossible to store.
+ * The runtime owns learner state and the surfaces that show it; it owns no
+ * teaching decisions. What it registers:
  *
- * Still deliberately absent:
- *   - no lesson generation, no quiz system -> v0.0.4+
- *   - no client half / UI                  -> v0.0.4
- *   - no resource ingestion, no RAG        -> out of scope for v0.1
+ *   - a goal → diagnosis map (courses, nodes, evidence) per project;
+ *   - one learning focus, next step and handoff per conversation;
+ *   - versioned course routes (goal brief, evidence-referenced assessment,
+ *     immutable curriculum revisions, explicit learner acceptance);
+ *   - session-scoped course runs: an attempt, teaching snapshots and the
+ *     evidence that completion is allowed to cite;
+ *   - the browser half: one "Learning map" main page, one "Current lesson"
+ *     docked tab, and the HTTP routes both read through.
+ *
+ * Still deliberately absent: resource ingestion and RAG (out of scope), and
+ * any rule that decides what to teach. The Universal Diagnostic Tutor skill is
+ * the teaching brain; this plugin only records what it did.
  *
  * ---------------------------------------------------------------------------
  * Cross-version discipline (see PLAN.md 2.12 #9 / #16)
@@ -40,6 +46,9 @@
  */
 import { API_PREFIX, registerApi } from './api.js';
 import { withActivity } from './handoff.js';
+import { openJournal } from './journal.js';
+import { stampPathRequestFailure } from './path-runtime.js';
+import { packageVersion } from './version.js';
 import { promptSession } from './prompt.js';
 import { UDT_DOMAIN_NAME, openUdState } from './state.js';
 import { registerTools } from './tools.js';
@@ -107,6 +116,9 @@ export async function apply(ctx) {
     // rejects new writes, drains queued ones, and releases the backend unit) and
     // Cordis awaits the returned promise before the plugin counts as unloaded.
     ctx.effect(() => () => state.close());
+    // Local, content-free monitoring. Disabled under the test runner and never
+    // allowed to fail the runtime (all writes are best-effort).
+    const journal = openJournal();
     // Mount the browser API if this profile has a web surface.
     //
     // Resolved eagerly first: a profile's web server is mounted by the base and
@@ -120,8 +132,19 @@ export async function apply(ctx) {
             return;
         ctx.effect(() => registerApi(server, {
             state,
-            prompt: (sessionId, text) => promptSession(ctx, sessionId, text),
+            prompt: (sessionId, text) => {
+                const result = promptSession(ctx, sessionId, text);
+                journal.append('tutor.prompt', {
+                    sessionId: sessionId ?? null,
+                    prompted: result.prompted,
+                    ...(result.reason === undefined ? {} : { reason: result.reason.slice(0, 240) }),
+                });
+                return result;
+            },
             teachingBrain: (sessionId) => teachingBrainForSession(ctx, sessionId),
+            journal,
+            pluginVersion: packageVersion(),
+            onEvent: (event, fields) => journal.append(event, fields),
         }));
         ctx.logger.debug(`[diagnostic-tutor] browser API mounted at ${API_PREFIX}`);
     };
@@ -137,12 +160,50 @@ export async function apply(ctx) {
     // happening". Only the first event counts, and only from the session the
     // handoff asked in, so a busy conversation elsewhere cannot make a quiet
     // handoff look alive.
+    // A prompted turn can fail after the request was accepted (a provider error,
+    // for example). The browser snapshot that would show it is memory-only, so
+    // stamp the durable request record here; the map page can then explain and
+    // retry even after a restart.
+    ctx.on('agent/error', ({ agent, error }) => {
+        const reason = error instanceof Error ? error.message : String(error);
+        journal.append('agent.error', { sessionId: String(agent.session.id), error: reason.slice(0, 240) });
+        void stampPathRequestFailure(state, String(agent.session.id), reason).catch(() => { });
+    });
+    const toolCalls = new Map();
     ctx.on('session/event', (session, event) => {
+        const sessionId = String(session.id);
+        // Tool metadata only: the name, the operation and the duration. Arguments
+        // stay out of the journal, so no lesson or goal text is recorded.
+        if (event.type === 'tool/call') {
+            const data = event.data;
+            if (typeof data.name === 'string' && data.name.startsWith('udt_')) {
+                let operation;
+                try {
+                    const parsed = JSON.parse(data.arguments ?? '');
+                    if (typeof parsed.op === 'string')
+                        operation = parsed.op;
+                    else if (typeof parsed.action === 'string')
+                        operation = parsed.action;
+                }
+                catch { /* the tool gets to explain its own arguments */ }
+                journal.append('tool.call', { sessionId, tool: data.name, ...(operation === undefined ? {} : { op: operation }) });
+                if (data.callId !== undefined)
+                    toolCalls.set(`${sessionId}:${data.callId}`, { name: data.name, start: Date.now() });
+            }
+        }
+        else if (event.type === 'tool/result') {
+            const message = event.data.message;
+            const key = message?.toolCallId === undefined ? undefined : `${sessionId}:${message.toolCallId}`;
+            const tracked = key === undefined ? undefined : toolCalls.get(key);
+            if (tracked !== undefined && key !== undefined) {
+                toolCalls.delete(key);
+                journal.append('tool.result', { sessionId, tool: tracked.name, durationMs: Math.max(0, Date.now() - tracked.start) });
+            }
+        }
         // The event says which conversation produced it, so the handoff is looked
         // up in that conversation rather than in the course at large. A busy
         // conversation elsewhere cannot make a quiet handoff look alive — and two
         // conversations working on the same target keep separate records.
-        const sessionId = String(session.id);
         const handoff = state.activeHandoff(sessionId);
         if (handoff === undefined || handoff.status !== 'prompted')
             return;
@@ -154,7 +215,8 @@ export async function apply(ctx) {
             .updateHandoff(sessionId, handoff.targetNodeId, (current) => current.status === 'prompted' ? withActivity(current, new Date().toISOString()) : current)
             .catch(() => { });
     });
-    registerTools({ tools }, state);
-    ctx.logger.debug(`[diagnostic-tutor] ready — domain "${state.name}" v${state.version}, 4 tools registered`);
+    const toolCount = registerTools({ tools }, state);
+    journal.append('plugin.ready', { tools: toolCount, version: packageVersion() });
+    ctx.logger.debug(`[diagnostic-tutor] ready — domain "${state.name}" v${state.version}, ${toolCount} tools registered`);
 }
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAKH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAElD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA;AAElD;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,kBAAkB,CAAA;AAEtC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,eAAe,CAAC,CAAA;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,GAAY;IACtC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAA;IAErD,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC9B,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,CAAA;IACzC,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;QACxB,mEAAmE;QACnE,GAAG,CAAC,MAAM,CAAC,KAAK,CACd,kDAAkD,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAC7G,CAAA;QACD,OAAM;IACR,CAAC;IAED,0EAA0E;IAC1E,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;IACvE,yEAAyE;IACzE,6DAA6D;IAC7D,EAAE;IACF,4EAA4E;IAC5E,wEAAwE;IACxE,6EAA6E;IAC7E,kCAAkC;IAClC,IAAI,KAAK,CAAA;IACT,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAA;QACnC,sEAAsE;QACtE,MAAM,KAAK,CAAC,aAAa,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAA;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,GAAG,CAAC,MAAM,CAAC,KAAK,CACd,qDAAqD,eAAe,MAAO,KAAe,CAAC,OAAO,IAAI;YACpG,6DAA6D;YAC7D,iGAAiG,CACpG,CAAA;QACD,OAAM;IACR,CAAC;IAED,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAA;IAErC,2EAA2E;IAC3E,4DAA4D;IAC5D,MAAM,OAAO,GAAG,WAAW,EAAE,CAAA;IAE7B,2DAA2D;IAC3D,EAAE;IACF,4EAA4E;IAC5E,2EAA2E;IAC3E,6EAA6E;IAC7E,4EAA4E;IAC5E,0EAA0E;IAC1E,4CAA4C;IAC5C,MAAM,QAAQ,GAAG,CAAC,MAAe,EAAQ,EAAE;QACzC,IAAI,CAAC,MAAM;YAAE,OAAM;QACnB,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CACd,WAAW,CAAC,MAAuB,EAAE;YACnC,KAAK;YACL,MAAM,EAAE,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE;gBAC1B,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,CAAA;gBAClD,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE;oBAC7B,SAAS,EAAE,SAAS,IAAI,IAAI;oBAC5B,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;iBAChF,CAAC,CAAA;gBACF,OAAO,MAAM,CAAA;YACf,CAAC;YACD,aAAa,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,uBAAuB,CAAC,GAAG,EAAE,SAAS,CAAC;YACrE,OAAO;YACP,aAAa,EAAE,cAAc,EAAE;YAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;SAC1D,CAAC,CACH,CAAA;QACD,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,6CAA6C,UAAU,EAAE,CAAC,CAAA;IAC7E,CAAC,CAAA;IACD,MAAM,SAAS,GAAG,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;IACtC,IAAI,SAAS;QAAE,QAAQ,CAAC,SAAS,CAAC,CAAA;;QAC7B,GAAG,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAA;IAE7E,qCAAqC;IACrC,EAAE;IACF,8EAA8E;IAC9E,qEAAqE;IACrE,yEAAyE;IACzE,yEAAyE;IACzE,sBAAsB;IACtB,6EAA6E;IAC7E,2EAA2E;IAC3E,2EAA2E;IAC3E,8BAA8B;IAC9B,GAAG,CAAC,EAAE,CAAC,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;QACzC,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACrE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;QACnG,KAAK,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IACvF,CAAC,CAAC,CAAA;IAEF,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2C,CAAA;IACpE,GAAG,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;QACzC,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QACpC,0EAA0E;QAC1E,kEAAkE;QAClE,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,IAA8D,CAAA;YACjF,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClE,IAAI,SAA6B,CAAA;gBACjC,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAuC,CAAA;oBACrF,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ;wBAAE,SAAS,GAAG,MAAM,CAAC,EAAE,CAAA;yBACnD,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;wBAAE,SAAS,GAAG,MAAM,CAAC,MAAM,CAAA;gBACvE,CAAC;gBAAC,MAAM,CAAC,CAAC,gDAAgD,CAAC,CAAC;gBAC5D,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAA;gBAClH,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;oBAAE,SAAS,CAAC,GAAG,CAAC,GAAG,SAAS,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;YACrH,CAAC;QACH,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACxC,MAAM,OAAO,GAAI,KAAK,CAAC,IAA8C,CAAC,OAAO,CAAA;YAC7E,MAAM,GAAG,GAAG,OAAO,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAA;YAChG,MAAM,OAAO,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAClE,IAAI,OAAO,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBAC/C,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBACrB,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;YACvH,CAAC;QACH,CAAC;QACD,0EAA0E;QAC1E,qEAAqE;QACrE,0EAA0E;QAC1E,kEAAkE;QAClE,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,CAAC,SAAS,CAAC,CAAA;QAC9C,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU;YAAE,OAAM;QAClE,KAAK,KAAK,CAAA;QACV,2EAA2E;QAC3E,4EAA4E;QAC5E,4BAA4B;QAC5B,KAAK,KAAK;aACP,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CAC1D,OAAO,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAC1F;aACA,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IACpB,CAAC,CAAC,CAAA;IAEF,MAAM,SAAS,GAAG,aAAa,CAAC,EAAE,KAAK,EAAE,EAAE,KAAK,CAAC,CAAA;IACjD,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC,CAAA;IAC/E,GAAG,CAAC,MAAM,CAAC,KAAK,CACd,sCAAsC,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,OAAO,KAAK,SAAS,mBAAmB,CACrG,CAAA;AACH,CAAC"}

package/lib/insights.js

@@ -0,0 +1,82 @@
+/**
+ * Read-only facts for the Insights tab.
+ *
+ * Nothing here scores, ranks mastery or invents a weakness: every field is a
+ * count or a direct projection of stored evidence, review history and attempts.
+ */
+import { dueCards } from './review.js';
+const DAY_MS = 86_400_000;
+function sortByAtDesc(items) {
+    return [...items].sort((left, right) => right.at.localeCompare(left.at));
+}
+/** Build one course's Insights view from stored facts. */
+export function buildInsights(state, course, nowIso) {
+    const now = new Date(nowIso);
+    const cards = state.listReviewCards().filter((card) => card.courseId === course.id);
+    const cardsById = new Map(cards.map((card) => [card.id, card]));
+    const due = dueCards(cards, now);
+    const logs = state.listReviewLog().filter((log) => cardsById.has(log.cardId));
+    const recentReviews = sortByAtDesc(logs).slice(0, 8).map((log) => ({
+        at: log.at, rating: log.rating, front: cardsById.get(log.cardId)?.front ?? '',
+    }));
+    const lapsed = [...cards]
+        .filter((card) => card.lapses > 0)
+        .sort((left, right) => right.lapses - left.lapses)
+        .slice(0, 5)
+        .map((card) => ({ id: card.id, front: card.front, lapses: card.lapses, dueAt: card.dueAt }));
+    const nodes = state.listNodes(course.id);
+    const evidence = nodes.flatMap((node) => node.evidence);
+    const weekAgo = now.getTime() - 7 * DAY_MS;
+    const byKind = new Map();
+    for (const entry of evidence)
+        byKind.set(entry.kind, (byKind.get(entry.kind) ?? 0) + 1);
+    const weakNodes = nodes
+        .filter((node) => node.state === 'weak' || node.state === 'blocked')
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+        .slice(0, 8)
+        .map((node) => ({
+        id: node.id, title: node.title, state: node.state,
+        evidenceCount: node.evidence.length, updatedAt: node.updatedAt,
+    }));
+    const attempts = state.listCourseRuns()
+        .filter((run) => run.courseId === course.id)
+        .flatMap((run) => run.attempts)
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+        .slice(0, 6)
+        .map((attempt) => ({
+        attemptId: attempt.id, status: attempt.status, updatedAt: attempt.updatedAt,
+        units: attempt.units.length, responses: attempt.responses?.length ?? 0,
+    }));
+    const today = nowIso.slice(0, 10);
+    const courseTasks = state.listTasks().filter((task) => task.courseId === undefined || task.courseId === course.id);
+    const sources = state.listSources();
+    return {
+        ok: true,
+        courseId: course.id,
+        courseTitle: course.title,
+        generatedAt: nowIso,
+        review: {
+            due: due.length,
+            overdue: due.filter((card) => Date.parse(card.dueAt) < now.getTime()).length,
+            total: cards.length,
+            lapsed,
+        },
+        recentReviews,
+        evidence: {
+            total: evidence.length,
+            last7Days: evidence.filter((entry) => Date.parse(entry.at) >= weekAgo).length,
+            byKind: [...byKind.entries()].map(([kind, count]) => ({ kind, count })).sort((left, right) => right.count - left.count),
+        },
+        weakNodes,
+        recentAttempts: attempts,
+        tasks: {
+            open: courseTasks.filter((task) => task.status === 'open').length,
+            dueToday: courseTasks.filter((task) => task.status === 'open' && task.dueAt !== undefined && task.dueAt.slice(0, 10) === today).length,
+        },
+        sources: {
+            count: sources.length,
+            bytes: sources.reduce((sum, source) => sum + source.bytes, 0),
+        },
+    };
+}
+//# sourceMappingURL=insights.js.map

package/lib/insights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.js","sourceRoot":"","sources":["../src/insights.ts"],"names":[],"mappings":"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"}

package/lib/interactions.js

@@ -0,0 +1,70 @@
+/** Recording learner submissions. No grading, no mastery, no automatic next step. */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { isKnownBlock } from './block-types.js';
+import { BlockAnswerSchema } from './path.js';
+import { pathView, requireAttempt } from './path-runtime.js';
+export const AnswerSubmissionSchema = z.object({
+    attemptId: z.string().min(1).max(200),
+    blockId: z.string().min(1).max(200),
+    answers: z.array(BlockAnswerSchema).min(1).max(16),
+}).strict();
+/**
+ * Persist a quiz/flashcard submission on the active attempt and append a neutral
+ * practice observation to its bound node. The node's state is never changed.
+ */
+export async function recordBlockResponse(state, input) {
+    const path = state.readPath(input.courseId);
+    if (path === undefined)
+        throw new Error('no-learning-path: ask for a route first');
+    if (path.revision !== input.expectedRevision)
+        throw new Error('revision-conflict: refresh the learning path');
+    const attempt = requireAttempt(state, input.courseId, input.sessionId, input.attemptId);
+    const lesson = [...attempt.units].reverse()[0]?.lesson;
+    const block = lesson?.blocks.find((candidate) => candidate.id === input.blockId);
+    if (block === undefined || !isKnownBlock(block))
+        throw new Error('unknown-block: refresh the lesson');
+    if (block.type !== 'quiz' && block.type !== 'flashcard')
+        throw new Error('not-an-interactive-block: this block does not take an answer');
+    if (block.type === 'quiz') {
+        const questions = new Map(block.content.questions.map((question) => [question.id, question]));
+        for (const answer of input.answers) {
+            const question = questions.get(answer.questionId);
+            if (question === undefined)
+                throw new Error(`unknown-question: no question "${answer.questionId}"`);
+            if (question.options !== undefined && !question.options.includes(answer.value) && question.kind === 'mcq') {
+                throw new Error('invalid-answer-option: choose one of the offered options');
+            }
+        }
+    }
+    else if (input.answers.length !== 1 || input.answers[0]?.questionId !== block.id) {
+        throw new Error('invalid-flashcard-answer: answer the card itself');
+    }
+    const response = {
+        id: randomUUID(),
+        blockId: block.id,
+        kind: block.type,
+        answers: input.answers,
+        submittedAt: new Date().toISOString(),
+    };
+    await state.mutateCourseRun(input.courseId, input.sessionId, (run) => {
+        const current = requireAttempt(state, input.courseId, input.sessionId, input.attemptId);
+        return {
+            ...run,
+            attempts: run.attempts.map((entry) => entry.id === current.id
+                ? { ...entry, responses: [...(entry.responses ?? []).filter((entryResponse) => entryResponse.blockId !== block.id), response], updatedAt: response.submittedAt }
+                : entry),
+            updatedAt: response.submittedAt,
+        };
+    });
+    if (attempt.nodeId !== null) {
+        const at = response.submittedAt;
+        await state.mutateNode(input.courseId, attempt.nodeId, (node) => ({
+            ...node,
+            evidence: [...node.evidence, { kind: 'practice', at, note: `Submitted ${block.type} response for ${block.id}.`, sessionId: input.sessionId, attemptId: attempt.id }],
+            updatedAt: at,
+        }));
+    }
+    return pathView(state, input.courseId, input.sessionId);
+}
+//# sourceMappingURL=interactions.js.map

package/lib/interactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactions.js","sourceRoot":"","sources":["../src/interactions.ts"],"names":[],"mappings":"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"}

package/lib/journal.js

@@ -0,0 +1,122 @@
+/**
+ * Local, content-free event journal for the tutoring flow.
+ *
+ * Monitoring has to answer "where did it get stuck?" without harvesting the
+ * learner's chat. This journal therefore stores only lifecycle facts: the
+ * event name, ids, stage/op names, durations and error messages — never lesson
+ * text, goals, evidence notes or model replies.
+ *
+ * The file is local to the machine, size-capped and rotated once. Writing is
+ * best-effort and serialised: monitoring must never fail the thing it observes.
+ */
+import { appendFile, mkdir, readFile, rename, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Environment override: a file path, or `off` to disable the journal. */
+export const JOURNAL_ENV = 'DSH_DIAGNOSTIC_TUTOR_EVENTS';
+/** Default cap per file, and the file kept beside it after rotation. */
+export const JOURNAL_MAX_BYTES = 1_000_000;
+/**
+ * Resolve the default journal file.
+ *
+ * `VITEST`/`NODE_ENV=test` disable the journal so the test suite never writes
+ * into the developer's real `~/.dsh`. Explicit configuration always wins.
+ *
+ * @param env - environment to read.
+ * @returns the file to append to, or `null` when disabled.
+ */
+export function defaultJournalFile(env = process.env) {
+    const explicit = env[JOURNAL_ENV];
+    if (explicit === 'off' || explicit === '0')
+        return null;
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    if (env.VITEST !== undefined || env.NODE_ENV === 'test')
+        return null;
+    const home = env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(home, 'logs', 'diagnostic-tutor-events.jsonl');
+}
+/** Best-effort rotation: keep one previous file, reset the current one. */
+async function rotate(file, bytes, maxBytes) {
+    if (bytes < maxBytes)
+        return bytes;
+    try {
+        await rename(file, `${file}.1`);
+    }
+    catch {
+        // Missing current file (or a concurrent rotation) is fine.
+    }
+    return 0;
+}
+/**
+ * Open the journal.
+ *
+ * @param options - file/maxBytes/clock overrides for tests.
+ * @returns the journal handle; a disabled journal is a no-op.
+ */
+export function openJournal(options = {}) {
+    const file = options.file === undefined ? defaultJournalFile() : options.file;
+    if (file === null) {
+        return { file: null, append: () => { }, tail: async () => [] };
+    }
+    const maxBytes = options.maxBytes ?? JOURNAL_MAX_BYTES;
+    const now = options.now ?? (() => new Date());
+    let bytes = null;
+    let chain = Promise.resolve();
+    const write = async (event, fields) => {
+        let line;
+        try {
+            line = JSON.stringify({ at: now().toISOString(), event, ...fields }) + '\n';
+        }
+        catch {
+            return; // A non-serialisable field must not break monitoring.
+        }
+        try {
+            await mkdir(dirname(file), { recursive: true });
+            if (bytes === null) {
+                try {
+                    bytes = (await stat(file)).size;
+                }
+                catch {
+                    bytes = 0;
+                }
+            }
+            bytes = await rotate(file, bytes, maxBytes);
+            await appendFile(file, line, 'utf8');
+            bytes += Buffer.byteLength(line);
+        }
+        catch {
+            // Local diagnostics are never allowed to fail the runtime.
+        }
+    };
+    return {
+        file,
+        append(event, fields = {}) {
+            chain = chain.then(() => write(event, fields));
+        },
+        async tail(limit = 50) {
+            await chain;
+            let text;
+            try {
+                text = await readFile(file, 'utf8');
+            }
+            catch {
+                return [];
+            }
+            const lines = text.split('\n').filter((line) => line.length > 0);
+            const events = [];
+            for (const line of lines.slice(-Math.max(1, limit))) {
+                try {
+                    const parsed = JSON.parse(line);
+                    if (typeof parsed.event === 'string')
+                        events.push(parsed);
+                }
+                catch {
+                    // A torn line is skipped; the rest of the journal still reads.
+                }
+            }
+            return events;
+        },
+    };
+}
+//# sourceMappingURL=journal.js.map

package/lib/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"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"}