dsh-diagnostic-tutor 0.1.0

package/lib/handoff.js

@@ -0,0 +1,194 @@
+/**
+ * The handoff: what happens between pressing Continue and seeing a lesson.
+ *
+ * Moving from one node to another is not instant — the runtime records a focus,
+ * an agent is woken, a model turn runs, and only then does a lesson exist. That
+ * gap used to be silent, which is the worst thing a gap can be: the learner
+ * cannot tell "working" from "broken", and a seven-minute turn is
+ * indistinguishable from a dead button.
+ *
+ * So the handoff is a **persisted record with timestamps**, and everything the
+ * UI shows about progress is derived from it. Persisting it is what makes the
+ * behaviours that matter possible at all:
+ *
+ *   - **idempotent** — keyed by target node, so pressing Continue twice is one
+ *     handoff, not two;
+ *   - **refresh-proof** — a reload re-reads the same record;
+ *   - **restart-proof** — the record outlives the process;
+ *   - **retryable** — the attempt count and timestamps say whether the tutor
+ *     ever answered, so a retry is informed rather than blind;
+ *   - **non-destructive on timeout** — a timeout is a statement about the
+ *     *wait*, never about the focus. The record goes stale; the focus stands.
+ *
+ * The timestamps are also the measurement. `requestedAt → focusRecordedAt →
+ * promptedAt → firstActivityAt → lessonAt → observedAt` is the whole chain, so
+ * "where did the time go" is a question with an answer rather than an
+ * argument.
+ */
+import { z } from 'zod';
+/**
+ * Where a handoff has got to.
+ *
+ * `requested`  the button was pressed; nothing has been persisted yet
+ * `prompted`   the focus is recorded and the tutor was woken
+ * `working`    the agent has produced its first event since being woken
+ * `ready`      a lesson exists for the target node
+ * `failed`     the tutor could not be reached
+ *
+ * There is deliberately no `timeout` status: a timeout is the *reader's*
+ * judgement about a record that has stopped moving, and storing it would mean
+ * writing to a record because time passed. The UI derives it from `updatedAt`.
+ */
+export const HANDOFF_STATUSES = ['requested', 'prompted', 'working', 'ready', 'failed'];
+export const HandoffStatusSchema = z.enum(HANDOFF_STATUSES);
+export const HandoffSchema = z.object({
+    /** The node being moved to. The key, which is what makes this idempotent. */
+    targetNodeId: z.string().min(1),
+    courseId: z.string().min(1),
+    fromNodeId: z.string().min(1),
+    status: HandoffStatusSchema,
+    /** How many times the tutor has been asked. A retry increments this. */
+    attempts: z.number().int().min(1),
+    /**
+     * The session the tutor was asked in.
+     *
+     * Kept so the first-activity listener can ignore events from every other
+     * conversation: a busy session elsewhere must not make this handoff look like
+     * it has started.
+     */
+    sessionId: z.string().optional(),
+    /** When the request reached the host. */
+    requestedAt: z.string(),
+    /** When the focus was durably recorded. */
+    focusRecordedAt: z.string().optional(),
+    /** When `followup` was accepted. */
+    promptedAt: z.string().optional(),
+    /** The first session event after the prompt — the tutor actually started. */
+    firstActivityAt: z.string().optional(),
+    /** When a lesson for the target node was written. */
+    lessonAt: z.string().optional(),
+    /** When a surface first rendered that lesson. */
+    observedAt: z.string().optional(),
+    failedAt: z.string().optional(),
+    failureReason: z.string().optional(),
+    updatedAt: z.string(),
+});
+/* -------------------------------------------------------------------------- */
+/* Pure transitions                                                           */
+/* -------------------------------------------------------------------------- */
+/** Start (or restart) a handoff for a target node. */
+export function beginHandoff(input) {
+    return {
+        courseId: input.courseId,
+        fromNodeId: input.fromNodeId,
+        targetNodeId: input.targetNodeId,
+        status: 'requested',
+        attempts: (input.previous?.attempts ?? 0) + 1,
+        requestedAt: input.now,
+        updatedAt: input.now,
+        ...(input.sessionId === undefined ? {} : { sessionId: input.sessionId }),
+    };
+}
+export function withFocusRecorded(record, now) {
+    return { ...record, focusRecordedAt: now, updatedAt: now };
+}
+export function withPrompted(record, now) {
+    return { ...record, status: 'prompted', promptedAt: now, updatedAt: now };
+}
+export function withPromptFailure(record, now, reason) {
+    return { ...record, status: 'failed', failedAt: now, failureReason: reason, updatedAt: now };
+}
+/**
+ * Record the tutor's first sign of activity.
+ *
+ * Only the first one is kept: this answers "how long until it started", and a
+ * later event would answer a different question.
+ */
+export function withActivity(record, now) {
+    if (record.firstActivityAt !== undefined)
+        return record;
+    return { ...record, status: 'working', firstActivityAt: now, updatedAt: now };
+}
+export function withLesson(record, now) {
+    return {
+        ...record,
+        status: 'ready',
+        lessonAt: record.lessonAt ?? now,
+        firstActivityAt: record.firstActivityAt ?? now,
+        updatedAt: now,
+    };
+}
+export function withObserved(record, now) {
+    if (record.observedAt !== undefined)
+        return record;
+    return { ...record, observedAt: now, updatedAt: now };
+}
+/**
+ * How long a surface waits before calling a quiet handoff stalled.
+ *
+ * Long, on purpose: a real model turn on a large node has taken minutes here,
+ * and telling a learner the tutor is broken while it is still thinking is worse
+ * than a longer wait. A stall is a prompt to retry, never a verdict.
+ */
+export const STALL_AFTER_MS = 150_000;
+function offset(from, requestedMs) {
+    if (from === undefined)
+        return undefined;
+    const at = Date.parse(from);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - requestedMs);
+}
+/**
+ * Derive what a surface should show.
+ *
+ * `stalled` is computed, not stored: a record that has stopped moving is not a
+ * different record, and writing to it because time passed would make the store
+ * a clock.
+ *
+ * @param record - the handoff.
+ * @param nowMs - current time, injected so this is testable.
+ * @param hasLesson - whether a lesson for the target node already exists.
+ * @returns the phase, a label, the elapsed time and the stage breakdown.
+ */
+export function handoffView(record, nowMs, hasLesson) {
+    const stages = {};
+    const requested = Date.parse(record.requestedAt);
+    const add = (name, from) => {
+        if (Number.isNaN(requested))
+            return;
+        const offsetMs = offset(from, requested);
+        if (offsetMs !== undefined)
+            stages[name] = offsetMs;
+    };
+    add('toFocusRecorded', record.focusRecordedAt);
+    add('toPrompted', record.promptedAt);
+    add('toFirstActivity', record.firstActivityAt);
+    add('toLesson', record.lessonAt);
+    add('toObserved', record.observedAt);
+    const elapsedMs = Math.max(0, nowMs - (Number.isNaN(requested) ? nowMs : requested));
+    const base = { targetNodeId: record.targetNodeId, elapsedMs, attempts: record.attempts, stages };
+    if (record.status === 'failed') {
+        return {
+            ...base,
+            phase: 'failed',
+            label: 'Could not reach the tutor',
+            ...(record.failureReason === undefined ? {} : { detail: record.failureReason }),
+        };
+    }
+    if (hasLesson || record.status === 'ready') {
+        return { ...base, phase: 'lesson-ready', label: 'Lesson ready' };
+    }
+    if (record.status === 'working' || record.firstActivityAt !== undefined) {
+        if (nowMs - Date.parse(record.updatedAt) > STALL_AFTER_MS) {
+            return { ...base, phase: 'stalled', label: 'The tutor has gone quiet', detail: 'Still working, or stopped — you can ask again.' };
+        }
+        return { ...base, phase: 'tutor-working', label: 'Tutor working…' };
+    }
+    if (record.status === 'prompted') {
+        if (nowMs - Date.parse(record.updatedAt) > STALL_AFTER_MS) {
+            return { ...base, phase: 'stalled', label: 'No answer from the tutor yet', detail: 'You can ask again without losing your place.' };
+        }
+        return { ...base, phase: 'tutor-requested', label: 'Tutor requested…' };
+    }
+    return { ...base, phase: 'focus-recorded', label: 'Focus recorded' };
+}
+//# sourceMappingURL=handoff.js.map

package/lib/handoff.js.map

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

package/lib/index.js

@@ -0,0 +1,186 @@
+/**
+ * dsh-diagnostic-tutor — DeepSeek Harness plugin entry point.
+ *
+ * A DSH plugin is a module exporting `apply(ctx, config)`. Cordis calls it at
+ * load time and everything registered through `ctx` is disposed automatically
+ * on unload.
+ *
+ * ---------------------------------------------------------------------------
+ * v0.0.3 scope (see docs/planning/PLAN.md §7)
+ * ---------------------------------------------------------------------------
+ * 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.
+ *
+ * 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
+ *
+ * ---------------------------------------------------------------------------
+ * Cross-version discipline (see PLAN.md 2.12 #9 / #16)
+ * ---------------------------------------------------------------------------
+ * Three harness cohorts can be resolvable at once (the running host, the
+ * shared profile fallback, and this package's own store). Therefore:
+ *
+ *   1. never `export default` — Cordis' `unwrapExports` prefers `.default` and
+ *      would silently DROP `inject`, so only named exports appear here.
+ *   2. every *type* coming from `@deepseek-ai/*` is imported with `import type`
+ *      (enforced by `verbatimModuleSyntax`), so no second runtime copy is
+ *      resolved for anything that merely describes a shape.
+ *   3. services and instances — `tools`, `storageDomain`, `skills`,
+ *      `systemPrompt`, the opened `Domain` — are always taken from `ctx` via
+ *      `ctx.get(...)`, never constructed and never `instanceof`-checked. A
+ *      cross-cohort copy would make such a check silently false.
+ *
+ * Pure *builder* helpers (`defineTool`, `defineDomain`, `domainTable`) are the
+ * one documented exception: they take plain data and return plain data, so
+ * they are imported as values. See the header of `state.ts`.
+ */
+import { API_PREFIX, registerApi } from './api.js';
+import { withActivity } from './handoff.js';
+import { promptSession } from './prompt.js';
+import { UDT_DOMAIN_NAME, openUdState } from './state.js';
+import { registerTools } from './tools.js';
+import { describeUdtStatus, detectUdtSkill } from './udt.js';
+/**
+ * Plugin module name. Stable kebab-case, equal to the loader row `id` in
+ * cordis.patch.yml and distinct from the npm package name.
+ */
+export const name = 'diagnostic-tutor';
+/**
+ * Services this plugin requires before it may load.
+ *
+ * Only services the standard profiles guarantee are declared here — both come
+ * from `@deepseek-ai/dsh-base`. Everything optional (the skill catalog, the
+ * system prompt) is resolved lazily with `ctx.get(...)`, so a profile without
+ * them loses the corresponding enhancement instead of leaving the whole plugin
+ * tree pending. A pending plugin prints nothing at all, which is hard to
+ * diagnose.
+ */
+export const inject = ['tools', 'storageDomain'];
+/**
+ * Load the plugin.
+ *
+ * `apply` is async, and Cordis keeps the fiber in `LOADING` until the returned
+ * promise settles — so `await ctx.plugin(...)` genuinely waits for the storage
+ * domain to be open, for first-run initialization to be durable, and for the
+ * tools to be registered. A nested `ctx.inject(...)` would return its own
+ * fiber, letting the outer fiber report ACTIVE while the domain was still
+ * opening.
+ *
+ * @param ctx - the Cordis context the loader hands to this plugin.
+ */
+export async function apply(ctx) {
+    ctx.logger.debug('[diagnostic-tutor] plugin loading');
+    const tools = ctx.get('tools');
+    const facility = ctx.get('storageDomain');
+    if (!tools || !facility) {
+        // Never degrade silently: a missing seam is a configuration error.
+        ctx.logger.error(`[diagnostic-tutor] missing required service(s):${tools ? '' : ' tools'}${facility ? '' : ' storageDomain'}`);
+        return;
+    }
+    // A storage failure must not take the whole plugin tree down with it. The
+    // loader treats a rejection from `apply` as a fatal composition error, so an
+    // unreadable, partial or version-mismatched store file would otherwise stop
+    // every unrelated plugin in the profile from loading — and would do it
+    // silently, because nothing is registered to report it. Degrade instead:
+    // report the cause loudly, register nothing, and stay inert.
+    //
+    // First-run initialization is inside this guard on purpose. It is the first
+    // *read* of the stored document, so it is where a partial file actually
+    // throws — a domain can open successfully and still fail on the first record
+    // that does not match its schema.
+    let state;
+    try {
+        state = await openUdState(facility);
+        // First run writes the learner record; later runs leave it untouched.
+        await state.ensureLearner(new Date().toISOString());
+    }
+    catch (error) {
+        ctx.logger.error(`[diagnostic-tutor] could not open storage domain "${UDT_DOMAIN_NAME}": ${error.message}. ` +
+            'The plugin is loaded but inert — no tools were registered. ' +
+            'This usually means a stored document written by an incompatible version, or one edited by hand.');
+        return;
+    }
+    // Unloading must leave no residue: this disposer closes the domain (which
+    // 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());
+    // Is the teaching brain present? Resolved lazily and never fatal: the
+    // runtime is useful without it, and a missing skill is a degraded mode, not
+    // an error. The result stays internal — it is logged, never surfaced to a
+    // learner through a tool, because the skill's own protocol forbids naming
+    // its files and versions in learner-facing text.
+    //
+    // Nothing is installed on the strength of it. Until v0.0.8 this gated a
+    // runtime-semantics system-prompt section that explained the storage model to
+    // a skill whose guardrails read as forbidding it; UDT v2.1's
+    // `learning_runtime_contract.md` now says all of that in the skill's own
+    // words, so the bridge was deleted rather than kept as a second voice.
+    const udt = await detectUdtSkill(ctx.get('skills'));
+    if (udt.available) {
+        ctx.logger.debug(`[diagnostic-tutor] teaching brain: ${describeUdtStatus(udt)}`);
+    }
+    else {
+        // Not debug: without the skill nothing will ever be taught, and a learner
+        // staring at an empty panel deserves a reason in the log. The panel says
+        // the same thing in its own words; neither names the skill's files or
+        // version, because its protocol forbids that in learner-facing text.
+        ctx.logger.warn(`[diagnostic-tutor] no teaching brain in this profile: ${describeUdtStatus(udt)}. ` +
+            'The runtime will record and display state, but no lesson will be written until the ' +
+            'Universal Diagnostic Tutor skill is installed for this workspace.');
+    }
+    // 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
+    // web-app bundles, which always precede a user bundle, so it is present by
+    // the time this runs. The deferred `ctx.inject` is the fallback for the rare
+    // case where the service arrives later — awaiting the outer fiber would not
+    // wait for that nested fiber, so preferring the eager path also keeps the
+    // load deterministic for callers and tests.
+    const mountApi = (server) => {
+        if (!server)
+            return;
+        ctx.effect(() => registerApi(server, {
+            state,
+            prompt: (sessionId, text) => promptSession(ctx, sessionId, text),
+            // Three states, because two would be a lie. `null` means this scope
+            // cannot see the catalog well enough to say — the normal case in a web
+            // profile, where skills are mounted per agent — and a surface must not
+            // turn that into "no tutor installed".
+            teachingBrain: udt.available ? true : udt.catalogVisible ? false : null,
+        }));
+        ctx.logger.debug(`[diagnostic-tutor] browser API mounted at ${API_PREFIX}`);
+    };
+    const webServer = ctx.get('webServer');
+    if (webServer)
+        mountApi(webServer);
+    else
+        ctx.inject(['webServer'], (webCtx) => mountApi(webCtx.get('webServer')));
+    // First sign of life from the tutor.
+    //
+    // The handoff records when the tutor was asked; this records when it actually
+    // started, which is the difference between "waiting" and "nothing is
+    // 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.
+    ctx.on('session/event', (session, event) => {
+        const handoff = state.activeHandoff();
+        if (handoff === undefined || handoff.status !== 'prompted')
+            return;
+        if (handoff.sessionId !== undefined && String(session.id) !== handoff.sessionId)
+            return;
+        void event;
+        // Atomic, and re-checked inside the transform: the lesson write races this
+        // listener, and a plain read-modify-write here would clobber a handoff that
+        // had already become ready.
+        void state
+            .updateHandoff(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`);
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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