dsh-diagnostic-tutor 0.1.0

package/lib/lesson.js

@@ -0,0 +1,285 @@
+/**
+ * Learning Block and Lesson schemas.
+ *
+ * The data schema lives here (host side, zod-validated at the durable
+ * boundary). The **renderers live in the client half** and are keyed by
+ * `block.type`, so adding Formula, Code, Comparison, Practice or Resource later
+ * means adding one renderer entry — never rewriting the lesson renderer.
+ *
+ * A block is `{ id, type, content, metadata? }`: the envelope is uniform and
+ * `content` is shaped per type. The envelope is what the renderer registry
+ * dispatches on; `content` is what a renderer understands. An unrecognised
+ * `type` is not an error — the client falls back to a readable placeholder, so
+ * a lesson authored by a newer host still renders in an older browser half.
+ *
+ * ---------------------------------------------------------------------------
+ * What v0.0.4 deliberately does NOT do
+ * ---------------------------------------------------------------------------
+ * There is no model-generated lesson here. `buildPrototypeLesson` is a
+ * **deterministic projection of state the runtime already holds** — the node's
+ * own title, relation, state and evidence — assembled into the four block
+ * types. It exists to prove the schema and the renderer end to end.
+ *
+ * That is why every lesson carries `origin`. A prototype lesson can never be
+ * mistaken for teaching content, and when real generation arrives it will be
+ * distinguishable in the stored record rather than by convention.
+ */
+import { z } from 'zod';
+/* -------------------------------------------------------------------------- */
+/* Size limits                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * A teaching unit is a few blocks, not a chapter.
+ *
+ * The cap is what makes "never generate a whole course in one call" structural
+ * rather than advisory — the same reasoning as the diagnosis map's node caps.
+ * Six leaves room for a real unit (orient, example, diagram, check) plus a
+ * correction.
+ */
+export const MAX_BLOCKS_PER_UPDATE = 6;
+/**
+ * A lesson accumulates across a session, so its ceiling is higher than one
+ * call's — but it is still a ceiling. Past this the lesson has stopped being a
+ * learning surface and become a document.
+ */
+export const MAX_BLOCKS_PER_LESSON = 24;
+/**
+ * Per-field length caps, enforced by zod at the durable boundary.
+ *
+ * Structural validation alone would accept a single 5 MB text block; these make
+ * "oversized payload" a rejection rather than a rendering problem.
+ */
+export const MAX_TEXT_CHARS = 6000;
+export const MAX_DIAGRAM_CHARS = 4000;
+export const MAX_PROMPT_CHARS = 1000;
+export const MAX_TITLE_CHARS = 200;
+export const MAX_STEP_CHARS = 400;
+export const MAX_STEPS = 12;
+/* -------------------------------------------------------------------------- */
+/* Blocks                                                                     */
+/* -------------------------------------------------------------------------- */
+/** Fields every block carries, whatever its type. */
+const blockBase = {
+    id: z.string().min(1),
+    /** Renderer-free annotations; never interpreted by the schema. */
+    metadata: z.record(z.string(), z.unknown()).optional(),
+};
+export const TextBlockSchema = z.object({
+    ...blockBase,
+    type: z.literal('text'),
+    content: z.object({
+        /** Markdown. Math uses the skill's convention: `\(...\)` / `\[...\]`. */
+        md: z.string().min(1).max(MAX_TEXT_CHARS),
+    }),
+});
+export const ExampleBlockSchema = z.object({
+    ...blockBase,
+    type: z.literal('example'),
+    content: z.object({
+        title: z.string().min(1).max(MAX_TITLE_CHARS),
+        steps: z.array(z.string().min(1).max(MAX_STEP_CHARS)).min(1).max(MAX_STEPS),
+        takeaway: z.string().min(1).max(MAX_STEP_CHARS).optional(),
+    }),
+});
+export const DiagramBlockSchema = z.object({
+    ...blockBase,
+    type: z.literal('diagram'),
+    content: z.object({
+        /**
+         * `ascii` renders as preformatted text and needs no dependency.
+         * `mermaid` is carried by the schema from the start so a lesson authored
+         * for a mermaid-capable client stays valid here; this client renders it as
+         * a labelled source block rather than pulling in a renderer.
+         */
+        format: z.enum(['ascii', 'mermaid']),
+        spec: z.string().min(1).max(MAX_DIAGRAM_CHARS),
+        caption: z.string().min(1).max(MAX_TITLE_CHARS).optional(),
+    }),
+});
+export const CheckBlockSchema = z.object({
+    ...blockBase,
+    type: z.literal('check'),
+    content: z.object({
+        prompt: z.string().min(1).max(MAX_PROMPT_CHARS),
+        /** What the check is really probing; a hint for the teaching brain. */
+        expect: z.enum(['reasoning', 'answer']).optional(),
+        hint: z.string().min(1).max(MAX_PROMPT_CHARS).optional(),
+    }),
+});
+/** Every block type this version understands. */
+export const BLOCK_SCHEMAS = [
+    TextBlockSchema,
+    ExampleBlockSchema,
+    DiagramBlockSchema,
+    CheckBlockSchema,
+];
+export const BlockSchema = z.discriminatedUnion('type', [
+    TextBlockSchema,
+    ExampleBlockSchema,
+    DiagramBlockSchema,
+    CheckBlockSchema,
+]);
+/** The block types this build can render, for diagnostics and tests. */
+export const SUPPORTED_BLOCK_TYPES = BLOCK_SCHEMAS.map((schema) => schema.shape.type.value);
+/* -------------------------------------------------------------------------- */
+/* Lesson                                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * `tutor` is what the runtime writes now: blocks the teaching brain submitted
+ * through `udt_lesson_update`.
+ *
+ * `prototype` is retained rather than removed because v0.0.4 wrote records with
+ * it, and the domain version cannot be bumped to invalidate them (the `single`
+ * layout rejects a version mismatch outright — see `state.ts`). It is no longer
+ * produced by the runtime.
+ */
+export const LESSON_ORIGINS = ['prototype', 'tutor'];
+export const LessonOriginSchema = z.enum(LESSON_ORIGINS);
+export const LessonSchema = z.object({
+    id: z.string().min(1),
+    courseId: z.string().min(1),
+    nodeId: z.string().min(1),
+    title: z.string().min(1),
+    blocks: z.array(BlockSchema).min(1).max(MAX_BLOCKS_PER_LESSON),
+    /** Who produced the blocks: the teaching brain, or the v0.0.4 scaffold. */
+    origin: LessonOriginSchema,
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+/* -------------------------------------------------------------------------- */
+/* Deterministic prototype lesson                                             */
+/* -------------------------------------------------------------------------- */
+/** Render the node's position in the map as an indented tree. */
+function asciiTree(nodes, focusId) {
+    const childrenOf = new Map();
+    for (const node of nodes) {
+        const bucket = childrenOf.get(node.parentId) ?? [];
+        bucket.push(node);
+        childrenOf.set(node.parentId, bucket);
+    }
+    const lines = [];
+    const walk = (node, depth, isLast) => {
+        const marker = depth === 0 ? '' : isLast ? '└─ ' : '├─ ';
+        const focus = node.id === focusId ? '   ◀ this node' : '';
+        lines.push(`${'   '.repeat(Math.max(0, depth - 1))}${marker}${node.title} [${node.state}]${focus}`);
+        const children = childrenOf.get(node.id) ?? [];
+        children.forEach((child, index) => walk(child, depth + 1, index === children.length - 1));
+    };
+    for (const root of childrenOf.get(undefined) ?? [])
+        walk(root, 0, true);
+    return lines.join('\n');
+}
+/** One readable line per evidence entry, newest last. */
+function evidenceSteps(node) {
+    if (node.evidence.length === 0) {
+        return ['No observation has been recorded against this node yet.'];
+    }
+    return node.evidence.map((entry) => {
+        const readiness = entry.readiness === undefined ? '' : ` — readiness: ${entry.readiness}`;
+        const note = entry.note === undefined ? '' : `: ${entry.note}`;
+        return `${entry.kind}${readiness}${note}`;
+    });
+}
+/** How a node came to be on the map, in the map's own terms. */
+function relationExplanation(node) {
+    switch (node.relation) {
+        case 'goal':
+            return 'This is the goal itself — the frame the rest of the map hangs from. A goal is never marked confirmed, because it is not a claim about what you can do.';
+        case 'prerequisite':
+            return 'This was recorded as a **prerequisite**: something diagnosed as blocking the node above it.';
+        case 'part-of':
+            return 'This is a **part of** the node above it — a component the diagnosis separated out.';
+        case 'related':
+            return 'This is **related** to the node above it: useful context, but not a component and not a blocker.';
+    }
+}
+/**
+ * Build a prototype lesson for one node.
+ *
+ * **Not on the runtime path any more.** v0.0.5 teaches through the tutor, and
+ * `udt_lesson_update` is how blocks arrive. This builder is kept for two
+ * honest reasons: v0.0.4 wrote `origin: 'prototype'` records that must still
+ * parse, and it is a convenient deterministic fixture for the preview and the
+ * block-renderer tests.
+ *
+ * It projects stored state into the four block types — it does not invent
+ * teaching content.
+ *
+ * @param input.course - the course the node belongs to.
+ * @param input.node - the node to build for.
+ * @param input.nodes - every node of the course, for the map diagram.
+ * @param input.now - ISO timestamp.
+ * @returns a validated lesson record.
+ */
+export function buildPrototypeLesson(input) {
+    const { course, node, nodes, now } = input;
+    const evidenceCount = node.evidence.length;
+    return LessonSchema.parse({
+        id: `${node.id}:prototype`,
+        courseId: course.id,
+        nodeId: node.id,
+        title: node.title,
+        origin: 'prototype',
+        createdAt: now,
+        updatedAt: now,
+        blocks: [
+            {
+                id: 'where',
+                type: 'text',
+                content: {
+                    md: `**${node.title}** is on your map for *${course.title}* in the state \`${node.state}\`, ` +
+                        `with ${evidenceCount} recorded observation${evidenceCount === 1 ? '' : 's'}.\n\n` +
+                        relationExplanation(node),
+                },
+                metadata: { role: 'orientation' },
+            },
+            {
+                id: 'evidence',
+                type: 'example',
+                content: {
+                    title: 'What the runtime has actually recorded',
+                    steps: evidenceSteps(node),
+                    takeaway: 'A node only moves off `unconfirmed` because something was observed — never because it was asserted.',
+                },
+                metadata: { role: 'evidence' },
+            },
+            {
+                id: 'map',
+                type: 'diagram',
+                content: {
+                    format: 'ascii',
+                    spec: asciiTree(nodes, node.id),
+                    caption: `Where ${node.title} sits in the diagnosis map.`,
+                },
+                metadata: { role: 'context' },
+            },
+            {
+                id: 'check',
+                type: 'check',
+                content: {
+                    prompt: `Before any teaching starts: in your own words, what do you already know about **${node.title}**, ` +
+                        'and where does it stop being clear?',
+                    expect: 'reasoning',
+                    hint: 'A rough answer is more useful than a polished one — the gaps are the point.',
+                },
+                metadata: { role: 'check', stopAndWait: true },
+            },
+        ],
+    });
+}
+/**
+ * Read a block's type without trusting the value.
+ *
+ * Used by the client's renderer registry so an unknown type degrades instead of
+ * throwing.
+ *
+ * @param value - any parsed block-shaped value.
+ * @returns the declared type, or `undefined`.
+ */
+export function blockTypeOf(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const type = value.type;
+    return typeof type === 'string' ? type : undefined;
+}
+//# sourceMappingURL=lesson.js.map

package/lib/lesson.js.map

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

package/lib/prompt.js

@@ -0,0 +1,96 @@
+/**
+ * Waking the teaching brain.
+ *
+ * "Start learning" is a UI act, but teaching happens in the chat — so the panel
+ * needs a way to tell the tutor that a node is now in focus. This module is
+ * that hand-off: it composes one ordinary user-role turn from the plugin and
+ * delivers it to the agent that owns the learner's session.
+ *
+ * Why a user-role message rather than injected context: `agent.inject()` adds
+ * model-visible context but **does not wake an idle agent**, so nothing would
+ * happen until the learner typed something. `followup()` opens a turn, which is
+ * exactly the intent of pressing the button. `@deepseek-ai/dsh-command-goal`
+ * and `dsh-headless` do the same thing for the same reason.
+ *
+ * The source is `{ kind: 'diagnostic-tutor' }` — the plugin declares its own
+ * kind. Harness 0.1.7 removed the shared catch-all `plugin` kind: a producer now
+ * merges its own entry into `MessageSourceMap`, and the augmentation below is
+ * that declaration. It is also what makes the value type-check at all, so a
+ * future rename cannot drift out of sync silently.
+ *
+ * Note what this module does **not** do: it does not decide what to teach. It
+ * reports which node the learner selected and asks the tutor to begin. Every
+ * teaching decision stays with the teaching brain.
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+/**
+ * Attribution for every turn this plugin opens.
+ *
+ * Must equal the declared kind below; TypeScript enforces it, because the value
+ * is passed where the augmented union is expected.
+ */
+export const PLUGIN_SOURCE = 'diagnostic-tutor';
+/**
+ * Compose the turn text.
+ *
+ * Written in the learner's voice, because it lands in the transcript they are
+ * reading: it should look like the button they just pressed, not like a system
+ * directive. It states the node and the expected shape of the reply, and stops
+ * — the tool descriptions carry the detail about blocks and caps.
+ *
+ * @param course - the course being learned.
+ * @param node - the node put in focus.
+ * @returns the message text.
+ */
+export function focusPromptText(course, node) {
+    return (`Let's start on **${node.title}** (${node.relation} of ${course.title}).\n\n` +
+        'Please teach me this node. Put the teaching itself in the Learning Surface beside the map, ' +
+        'end with a check I can answer here in the chat, and stop there.');
+}
+/**
+ * Deliver one turn to the agent that owns a session.
+ *
+ * Never throws for a missing agent: the focus has already been recorded by the
+ * time this runs, and the tutor can pick it up on the next turn regardless. A
+ * graceful "not prompted" keeps the button useful in every configuration.
+ *
+ * @param ctx - the plugin's context.
+ * @param sessionId - the session the panel is showing, when it knows one.
+ * @param text - the turn text.
+ * @returns whether a turn was opened, and why not when it was not.
+ */
+export function promptSession(ctx, sessionId, text) {
+    if (sessionId === undefined || sessionId.length === 0) {
+        return { prompted: false, reason: 'the panel did not report a session' };
+    }
+    const agents = ctx.get('agents');
+    if (!agents) {
+        return { prompted: false, reason: 'this profile has no agent registry' };
+    }
+    // The requested session is the right target. DSH creates an agent lazily —
+    // a brand-new session has none until something is said in it — so fall back
+    // to the registry only when doing so is unambiguous, and never guess between
+    // several conversations.
+    let agent = agents.get(sessionId);
+    if (!agent) {
+        const live = agents.list();
+        if (live.length === 1 && live[0] !== undefined) {
+            agent = live[0];
+        }
+        else {
+            return {
+                prompted: false,
+                reason: live.length === 0
+                    ? 'that session has no live agent yet — say anything in the chat and the tutor will pick the focus up'
+                    : `that session has no live agent, and ${live.length} other conversations are open`,
+            };
+        }
+    }
+    const target = agent;
+    target.followup(createUserMessage({
+        content: [{ type: 'text', text }],
+        source: { kind: PLUGIN_SOURCE },
+    }));
+    return { prompted: true };
+}
+//# sourceMappingURL=prompt.js.map

package/lib/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAIxD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,CAAA;AA2B/C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB,EAAE,IAAgB;IACpE,OAAO,CACL,oBAAoB,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,QAAQ,OAAO,MAAM,CAAC,KAAK,QAAQ;QAC7E,6FAA6F;QAC7F,iEAAiE,CAClE,CAAA;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY,EAAE,SAA6B,EAAE,IAAY;IACrF,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,EAAE,CAAA;IAC1E,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAChC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,EAAE,CAAA;IAC1E,CAAC;IAED,2EAA2E;IAC3E,4EAA4E;IAC5E,6EAA6E;IAC7E,yBAAyB;IACzB,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,SAAkB,CAAC,CAAA;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;QAC1B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YAC/C,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;aAAM,CAAC;YACN,OAAO;gBACL,QAAQ,EAAE,KAAK;gBACf,MAAM,EACJ,IAAI,CAAC,MAAM,KAAK,CAAC;oBACf,CAAC,CAAC,oGAAoG;oBACtG,CAAC,CAAC,uCAAuC,IAAI,CAAC,MAAM,+BAA+B;aACxF,CAAA;QACH,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAA;IACpB,MAAM,CAAC,QAAQ,CACb,iBAAiB,CAAC;QAChB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QACjC,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE;KAChC,CAAC,CACH,CAAA;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;AAC3B,CAAC"}