dsh-nerd-mode 0.4.0 → 0.4.4

package/lib/index.js

@@ -1,213 +1,223 @@
-/**
- * Nerd Mode: a per-session switch. While it is on, one prompt section joins
- * every request and the `study` skill becomes the default answer shape. State
- * folds from the session log, so it survives compaction, resume, and fork. The
- * tool set never changes.
- *
- * The section registers at the profile level, not inside a preset, so it
- * reaches every agent in every preset. See docs/adr/0008.
- */
-
-import { COMMAND, KEY, fold, init } from './fold.js'
-import z from '@deepseek-ai/schemastery'
-
-export const name = 'dsh-nerd-mode'
-export const PACKAGE_NAME = 'dsh-nerd-mode'
-export const inject = ['systemPrompt', 'sessionProjections']
-
-export const Config = z.object({
-  section: z.string().pattern(/\S/).required(),
-  recallSessionEnabled: z.boolean().default(false).volatile(),
-  unseenQuestionCount: z.number().step(1).min(0).max(10).default(3).volatile(),
-  unseenQuestionType: z.union([
-    z.const('short-answer'),
-    z.const('multiple-choice'),
-    z.const('mixed'),
-  ]).default('short-answer').volatile(),
-})
-
-const SECTION = 'study:policy'
-// Between PLAN_POLICY (500) and TEAM_POLICY (600).
-const SECTION_ORDER = 550
-const studyPlusDefaultsBySession = new WeakMap()
-const directStudyPlusBySession = new WeakMap()
-// A PTC skill load leaves no message in the history, so keep its id for later
-// turns the way an injected skill message would.
-const ptcStudyPlusBySession = new WeakMap()
-const SKILL_COMMAND = /(^|\s)\/([a-z0-9]+(?:-[a-z0-9]+)*)(?=\s|$)/g
-
-// shortcut: parse-only schemas, no zod. The projection registry calls `parse`
-// and nothing else. Upgrade to zod if the host starts introspecting schemas.
-const stateSchema = {
-  parse: (value) => ({
-    active: value?.active === true,
-    running:
-      value?.running && typeof value.running.commandId === 'string'
-        ? { commandId: value.running.commandId, wanted: value.running.wanted === true }
-        : null,
-  }),
-}
-
-const viewSchema = { parse: (value) => ({ active: value?.active === true }) }
-
-function studyPlusSettings(config, session, invocationId) {
-  let defaults = studyPlusDefaultsBySession.get(session)
-  if (defaults?.invocationId !== invocationId) {
-    defaults = {
-      invocationId,
-      recallSessionEnabled: config.recallSessionEnabled?.get?.() ?? false,
-      unseenQuestionCount: config.unseenQuestionCount?.get?.() ?? 3,
-      unseenQuestionType: config.unseenQuestionType?.get?.() ?? 'short-answer',
-    }
-    studyPlusDefaultsBySession.set(session, defaults)
-  }
-
-  return [
-    '',
-    '',
-    'Study-plus profile defaults for this tracked session:',
-    `- Recall Session: ${defaults.recallSessionEnabled ? 'enabled' : 'disabled'}.`,
-    `- Post-lecture questions: ${defaults.unseenQuestionCount}; type: ${defaults.unseenQuestionType}.`,
-    'Apply these defaults only during tracked study-plus sessions. Ignore them for ordinary study and all other requests.',
-    'An explicit preference in the current /study-plus request overrides its profile default for this session and does not update the profile.',
-  ].join('\n')
-}
-
-/** Return the message id when the message is a direct /study-plus command, else undefined. */
-function directStudyPlusId(message) {
-  if (message?.source?.kind !== 'user') return undefined
-  const text = (message.content ?? [])
-    .filter((block) => block.type === 'text')
-    .map((block) => block.text)
-    .join('\n')
-  return [...text.matchAll(SKILL_COMMAND)].at(-1)?.[2] === 'study-plus' ? message.id : undefined
-}
-
-function studyPlusInvocation(session) {
-  const directInvocation = directStudyPlusBySession.get(session)
-  if (directInvocation !== undefined) return directInvocation
-  const ptcInvocation = ptcStudyPlusBySession.get(session)
-  if (ptcInvocation !== undefined) return ptcInvocation
-
-  // The host returns the full surface history here, not just this turn. See docs/agents/dsh-session-api.md.
-  const invocation = session.deriveMessages().findLast((message) => message.source?.kind === 'skill-invocation')
-  if (invocation?.source.name === 'study-plus') return invocation.id
-
-  const completedCalls = new Set()
-  let loadedId
-  let directId
-  let skillCall
-  let ptcSkillCall
-  for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
-    const event = session.eventAt(seq)
-    if (event?.type === 'turn/start') break
-    // A resumed, forked, or seeded log may carry a partial event payload, so
-    // every nested read here is guarded. One bad record must not fail a turn.
-    if (event?.type === 'tool/result') {
-      const result = event.data?.message
-      if (result !== undefined && result.isError !== true && result.source?.callId !== undefined) {
-        completedCalls.add(result.source.callId)
-      }
-    } else if (event?.type === 'tool/call' && event.data?.name === 'skill') {
-      try {
-        if (JSON.parse(event.data.arguments).name === 'study-plus') skillCall = event.data.callId
-      } catch {}
-    } else if (event?.type === 'tool/ptc-dispatch' && event.data?.name === 'skill') {
-      // PTC records a skill call made inside run_code as a dispatch, not as a
-      // `tool/call`, and the dispatch event itself carries the outcome.
-      if (event.data.isError !== true && event.data.arguments?.name === 'study-plus') {
-        ptcSkillCall = event.data.subCallId
-      }
-    } else if (event?.type === 'user/message') {
-      // `user/message` stores the message fields directly in `data`; only
-      // `tool/result` and `system/message` wrap them under `data.message`.
-      const message = event.data
-      if (message?.source?.kind === 'skill-invocation') {
-        if (message.source.name === 'study-plus') loadedId = message.id
-      } else {
-        directId = directStudyPlusId(message) ?? directId
-      }
-    }
-  }
-
-  // A skill load counts only when its tool call completed. A typed command counts at once.
-  if (skillCall !== undefined) {
-    return completedCalls.has(skillCall) ? loadedId ?? directId ?? skillCall : undefined
-  }
-  if (ptcSkillCall !== undefined) {
-    ptcStudyPlusBySession.set(session, ptcSkillCall)
-    return loadedId ?? directId ?? ptcSkillCall
-  }
-  return loadedId ?? directId
-}
-
-const projection = {
-  key: KEY,
-  stateVersion: 1,
-  stateSchema,
-  init,
-  apply: fold,
-  wire: {
-    viewSchema,
-    view: (state) => ({ active: state.active }),
-  },
-}
-
-/**
- * @param config - `section` is the overlay text, required and non-empty.
- */
-export function apply(ctx, config) {
-  const section = config?.section
-  if (typeof section !== 'string' || section.trim() === '') {
-    throw new Error('dsh-nerd-mode needs a non-empty string `section`')
-  }
-
-  ctx.sessionProjections.register(projection)
-
-  ctx.effect(
-    () => ctx.on('agent/inbox/claimed', ({ agent, message }) => {
-      directStudyPlusBySession.set(agent.session, directStudyPlusId(message))
-    }),
-    'dsh-nerd-mode: study-plus claim',
-  )
-
-  ctx.effect(
-    () =>
-      ctx.systemPrompt.section({
-        name: SECTION,
-        order: SECTION_ORDER,
-        text: (context) => {
-          if (context.agent === undefined) return ''
-          if (!ctx.sessionProjections.stateOf(context.agent.session, KEY).active) return ''
-          const session = context.agent.session
-          const invocationId = studyPlusInvocation(session)
-          if (invocationId === undefined) return section
-          return section + studyPlusSettings(config ?? {}, session, invocationId)
-        },
-      }),
-    'dsh-nerd-mode: section',
-  )
-
-  ctx.inject(['commands'], (commandCtx) => {
-    commandCtx.commands.register({
-      name: COMMAND,
-      description: 'Turn Nerd Mode on or off for this conversation',
-      input: { hint: '[on|off]' },
-      handler: ({ agent, rawInput }) => {
-        const arg = rawInput.trim().toLowerCase()
-        const active = ctx.sessionProjections.stateOf(agent.session, KEY).active
-
-        if (arg === 'off') {
-          return { kind: 'success', text: active ? 'Nerd Mode off.' : 'Nerd Mode is already off.' }
-        }
-        if (arg !== '' && arg !== 'on') {
-          return { kind: 'error', text: `Unknown argument "${arg}". Use /nerd-mode on or /nerd-mode off.` }
-        }
-        return {
-          kind: 'success',
-          text: active ? 'Nerd Mode is already on.' : 'Nerd Mode on. /study guides a concept or a task.',
-        }
-      },
-    })
-  })
-}
+/**
+ * Nerd Mode: a per-session switch. While it is on, one prompt section joins
+ * every request and the `study` skill becomes the default answer shape. State
+ * folds from the session log, so it survives compaction, resume, and fork. The
+ * tool set never changes.
+ *
+ * The section registers at the profile level, not inside a preset, so it
+ * reaches every agent in every preset. See docs/adr/0008.
+ */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { COMMAND, KEY, fold, init } from './fold.js'
+import z from '@deepseek-ai/schemastery'
+
+export const name = 'dsh-nerd-mode'
+export const PACKAGE_NAME = 'dsh-nerd-mode'
+export const inject = ['systemPrompt', 'sessionProjections']
+
+// The prompt text ships with the package. Keeping it out of the config stops
+// every profile patch from carrying a stale copy of it.
+const BUNDLED_SECTION = readFileSync(
+  fileURLToPath(new URL('../assets/section.md', import.meta.url)),
+  'utf8',
+).trim()
+
+export const Config = z.object({
+  section: z.string().pattern(/\S/).default(BUNDLED_SECTION),
+  recallSessionEnabled: z.boolean().default(false).volatile(),
+  unseenQuestionCount: z.number().step(1).min(0).max(10).default(3).volatile(),
+  unseenQuestionType: z.union([
+    z.const('short-answer'),
+    z.const('multiple-choice'),
+    z.const('mixed'),
+  ]).default('short-answer').volatile(),
+})
+
+const SECTION = 'study:policy'
+// Between PLAN_POLICY (500) and TEAM_POLICY (600).
+const SECTION_ORDER = 550
+const studyPlusDefaultsBySession = new WeakMap()
+const directStudyPlusBySession = new WeakMap()
+// A PTC skill load leaves no message in the history, so keep its id for later
+// turns the way an injected skill message would.
+const ptcStudyPlusBySession = new WeakMap()
+const SKILL_COMMAND = /(^|\s)\/([a-z0-9]+(?:-[a-z0-9]+)*)(?=\s|$)/g
+
+// shortcut: parse-only schemas, no zod. The projection registry calls `parse`
+// and nothing else. Upgrade to zod if the host starts introspecting schemas.
+const stateSchema = {
+  parse: (value) => ({
+    active: value?.active === true,
+    running:
+      value?.running && typeof value.running.commandId === 'string'
+        ? { commandId: value.running.commandId, wanted: value.running.wanted === true }
+        : null,
+  }),
+}
+
+const viewSchema = { parse: (value) => ({ active: value?.active === true }) }
+
+function studyPlusSettings(config, session, invocationId) {
+  let defaults = studyPlusDefaultsBySession.get(session)
+  if (defaults?.invocationId !== invocationId) {
+    defaults = {
+      invocationId,
+      recallSessionEnabled: config.recallSessionEnabled?.get?.() ?? false,
+      unseenQuestionCount: config.unseenQuestionCount?.get?.() ?? 3,
+      unseenQuestionType: config.unseenQuestionType?.get?.() ?? 'short-answer',
+    }
+    studyPlusDefaultsBySession.set(session, defaults)
+  }
+
+  return [
+    '',
+    '',
+    'Study-plus profile defaults for this tracked session:',
+    `- Recall Session: ${defaults.recallSessionEnabled ? 'enabled' : 'disabled'}.`,
+    `- Post-lecture questions: ${defaults.unseenQuestionCount}; type: ${defaults.unseenQuestionType}.`,
+    'Apply these defaults only during tracked study-plus sessions. Ignore them for ordinary study and all other requests.',
+    'An explicit preference in the current /study-plus request overrides its profile default for this session and does not update the profile.',
+  ].join('\n')
+}
+
+/** Return the message id when the message is a direct /study-plus command, else undefined. */
+function directStudyPlusId(message) {
+  if (message?.source?.kind !== 'user') return undefined
+  const text = (message.content ?? [])
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n')
+  return [...text.matchAll(SKILL_COMMAND)].at(-1)?.[2] === 'study-plus' ? message.id : undefined
+}
+
+function studyPlusInvocation(session) {
+  const directInvocation = directStudyPlusBySession.get(session)
+  if (directInvocation !== undefined) return directInvocation
+  const ptcInvocation = ptcStudyPlusBySession.get(session)
+  if (ptcInvocation !== undefined) return ptcInvocation
+
+  // The host returns the full surface history here, not just this turn. See docs/agents/dsh-session-api.md.
+  const invocation = session.deriveMessages().findLast((message) => message.source?.kind === 'skill-invocation')
+  if (invocation?.source.name === 'study-plus') return invocation.id
+
+  const completedCalls = new Set()
+  let loadedId
+  let directId
+  let skillCall
+  let ptcSkillCall
+  for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+    const event = session.eventAt(seq)
+    if (event?.type === 'turn/start') break
+    // A resumed, forked, or seeded log may carry a partial event payload, so
+    // every nested read here is guarded. One bad record must not fail a turn.
+    if (event?.type === 'tool/result') {
+      const result = event.data?.message
+      if (result !== undefined && result.isError !== true && result.source?.callId !== undefined) {
+        completedCalls.add(result.source.callId)
+      }
+    } else if (event?.type === 'tool/call' && event.data?.name === 'skill') {
+      try {
+        if (JSON.parse(event.data.arguments).name === 'study-plus') skillCall = event.data.callId
+      } catch {}
+    } else if (event?.type === 'tool/ptc-dispatch' && event.data?.name === 'skill') {
+      // PTC records a skill call made inside run_code as a dispatch, not as a
+      // `tool/call`, and the dispatch event itself carries the outcome.
+      if (event.data.isError !== true && event.data.arguments?.name === 'study-plus') {
+        ptcSkillCall = event.data.subCallId
+      }
+    } else if (event?.type === 'user/message') {
+      // `user/message` stores the message fields directly in `data`; only
+      // `tool/result` and `system/message` wrap them under `data.message`.
+      const message = event.data
+      if (message?.source?.kind === 'skill-invocation') {
+        if (message.source.name === 'study-plus') loadedId = message.id
+      } else {
+        directId = directStudyPlusId(message) ?? directId
+      }
+    }
+  }
+
+  // A skill load counts only when its tool call completed. A typed command counts at once.
+  if (skillCall !== undefined) {
+    return completedCalls.has(skillCall) ? loadedId ?? directId ?? skillCall : undefined
+  }
+  if (ptcSkillCall !== undefined) {
+    ptcStudyPlusBySession.set(session, ptcSkillCall)
+    return loadedId ?? directId ?? ptcSkillCall
+  }
+  return loadedId ?? directId
+}
+
+const projection = {
+  key: KEY,
+  stateVersion: 1,
+  stateSchema,
+  init,
+  apply: fold,
+  wire: {
+    viewSchema,
+    view: (state) => ({ active: state.active }),
+  },
+}
+
+/**
+ * @param config - `section` is an optional overlay text; a missing value uses
+ * the bundled `assets/section.md`.
+ */
+export function apply(ctx, config) {
+  const section = config?.section
+  if (typeof section !== 'string' || section.trim() === '') {
+    throw new Error('dsh-nerd-mode needs a non-empty string `section`')
+  }
+
+  ctx.sessionProjections.register(projection)
+
+  ctx.effect(
+    () => ctx.on('agent/inbox/claimed', ({ agent, message }) => {
+      directStudyPlusBySession.set(agent.session, directStudyPlusId(message))
+    }),
+    'dsh-nerd-mode: study-plus claim',
+  )
+
+  ctx.effect(
+    () =>
+      ctx.systemPrompt.section({
+        name: SECTION,
+        order: SECTION_ORDER,
+        text: (context) => {
+          if (context.agent === undefined) return ''
+          if (!ctx.sessionProjections.stateOf(context.agent.session, KEY).active) return ''
+          const session = context.agent.session
+          const invocationId = studyPlusInvocation(session)
+          if (invocationId === undefined) return section
+          return section + studyPlusSettings(config ?? {}, session, invocationId)
+        },
+      }),
+    'dsh-nerd-mode: section',
+  )
+
+  ctx.inject(['commands'], (commandCtx) => {
+    commandCtx.commands.register({
+      name: COMMAND,
+      description: 'Turn Nerd Mode on or off for this conversation',
+      input: { hint: '[on|off]' },
+      handler: ({ agent, rawInput }) => {
+        const arg = rawInput.trim().toLowerCase()
+        const active = ctx.sessionProjections.stateOf(agent.session, KEY).active
+
+        if (arg === 'off') {
+          return { kind: 'success', text: active ? 'Nerd Mode off.' : 'Nerd Mode is already off.' }
+        }
+        if (arg !== '' && arg !== 'on') {
+          return { kind: 'error', text: `Unknown argument "${arg}". Use /nerd-mode on or /nerd-mode off.` }
+        }
+        return {
+          kind: 'success',
+          text: active ? 'Nerd Mode is already on.' : 'Nerd Mode on. /study guides a concept or a task.',
+        }
+      },
+    })
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-nerd-mode",
-  "version": "0.4.0",
+  "version": "0.4.4",
   "description": "A study switch and study skills for DeepSeek Harness.",
   "license": "MIT",
   "type": "module",

package/skills/diagram/SKILL.md

@@ -29,8 +29,6 @@ Write the SVG file first, then talk about it.
 3. Put one caption sentence after it that states the point the picture makes. Keep the prose around it short; the figure carries the detail.
 4. Embed the figure in the section whose step it illustrates, not in a gallery at the end.
 
-Inside a `/teach` workspace, write the file to that workspace's `assets/` and reference it from the lesson file instead, with the same relative form.
-
 The Markdown path is resolved against the working directory and served from disk, so it must be a file that exists when the message renders. Write the file before the sentence that shows it. No query string, no fragment, no `data:` URL: the renderer rejects all three and shows the alt text instead. To revise a figure, overwrite the file; if the learner still sees the old picture, write a new name.
 
 ## File contract

package/skills/study/SKILL.md

@@ -48,7 +48,7 @@ For `advanced`:
 
 Accuracy rules outrank the level. No level removes a symbol definition, a justification for a derivation step, a stated assumption or approximation, or a bound. No level adds filler, repeated explanation, or a section the concept does not need. The level affects the lecture only.
 
-For a one-off request with no graph, derive the level from the request and the supplied material. When neither states a goal or a background, ask one combined question before teaching: what the learner wants to reach and whether they have met the topic before. State the derived level in one line, then teach. Write no file.
+For a one-off request with no graph, derive the level from the brief the upper layer supplies and from the request and the supplied material. A brief from an upper layer is final: never ask again for a goal or a background it leaves out. A bare topic, or "I want to learn X", states no goal. When no brief arrives and neither the request nor the supplied material states a goal or a background, ask one combined question before teaching: what the learner wants to reach and whether they have met the topic before. State the derived level in one line, then teach. Write no file.
 
 ## Format the answer
 
@@ -73,6 +73,6 @@ The upper layer may hand you an approved concept graph, the relevant supplied ma
 
 Default to chat output. If the learner asks to save a lecture or other artifact, save it to the requested path and show the same content in chat when practical.
 
-When an SVG would materially clarify a relationship, create it by default at `diagrams/<topic>/<name>.svg`. Load `diagram` for its visual authoring rules, but use this study-specific path instead of its generic default. Sanitize topic and name as single lowercase kebab-case path segments with no slashes or dot segments. If either is unclear, choose a safe fallback. Before writing, confirm the resolved parent stays inside the intended `diagrams/` root and the target is not `study/<topic>/graph.md`, `state.md`, `log.md`, or `plan.md`. Compute plotted points rather than placing them by eye. Before replacing an SVG with the same name, copy the old file to `<name>.svg.bak`, replacing any older backup.
+When an SVG would materially clarify a relationship, create it by default. When the upper layer scopes a Course, write `study/<course>/diagrams/<name>.svg`. When the guide runs alone, write `diagrams/<name>.svg` and create no folder under `study/`. Load `diagram` for its visual authoring rules, but use this study-specific path instead of its generic default. Sanitize `course` and `name` as single lowercase kebab-case path segments with no slashes or dot segments. If either is unclear, choose a safe fallback. Before writing, confirm the resolved parent stays inside the intended `diagrams/` root and the target is not `study/<course>/graph.md`, `state.md`, `log.md`, or `plan.md`. Compute plotted points rather than placing them by eye. Before replacing an SVG with the same name, copy the old file to `<name>.svg.bak`, replacing any older backup.
 
-Never read or write `study/<topic>/graph.md`, `state.md`, `log.md`, or `plan.md`. Do not read or change tracker state. Study-plus owns the choice of lecture paths and the automatic lecture save during tracked sessions. Study may read or write ordinary artifacts, including lectures, drafts, and figures, at paths the user or the upper layer gives it.
+Never read or write `study/<course>/graph.md`, `state.md`, `log.md`, or `plan.md`. Do not read or change tracker state. Study-plus owns the choice of lecture paths and the automatic lecture save during tracked sessions. Study may read or write ordinary artifacts, including lectures, drafts, and figures, at paths the user or the upper layer gives it.