eklavya 1.85.2 → 1.86.0

package/README.md

@@ -52,7 +52,7 @@ Code's learning loop.
 |---|---|
 | Learner state and concepts | `get_learner_profile`, `log_session_concepts`, `upsert_concepts`, `get_concept_graph` |
 | Questions and assessment (automatic questions wait for a code change, not a `git pull`; see `quiz.only_on_changes`) | `get_session_quiz_plan`, `record_attempt`, `get_gate_status` |
-| Quiz side panel (experimental) | `present_question` for the model; `panel_sync` and `panel_answer`, called only by the panel mod, never by the model; its header stacks the mark above the topic in a pane under 60 cells wide; on the desktop app each option's note is its own line under the option, and a click on the option picks it |
+| Quiz side panel (experimental) | `present_question` for the model; `panel_sync` and `panel_answer`, called only by the panel mod, never by the model; its header stacks the mark above the topic in a pane under 60 cells wide; on the desktop app each option's note is its own line under the option, and a click on the option picks it; `/eklavya-panel-demo` opens a mock question the panel answers itself, calling none of these tools |
 | Settings | `get_config`, `set_config` |
 | Find and read memory (`memory_status` includes a `health` verdict with reasons) | `memory_search`, `memory_get`, `memory_timeline`, `memory_file_history`, `memory_status` |
 | Maintain memory | `memory_write`, `memory_correct`, `memory_delete`, `memory_collections` |

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "eklavya",
   "displayName": "Eklavya",
-  "version": "1.85.2",
+  "version": "1.86.0",
   "description": "Learn while your agent works. Turns coding-agent generation time into adaptive, Socratic learning grounded in the code being written.",
   "author": {
     "name": "Ajay Kumar"

package/dist/plugin/hooks/CLAUDE.md

@@ -56,6 +56,7 @@ returns `{disabled: true}` and the mod opens and draws nothing. `presentation` i
 the Stop sweep and the delegation lines (`delegation-lib.ts`) read it, and an
 open panel question silences the checkpoint and the Stop sweep. Read
 `docs/verified-schemas.md` (mods section) before changing anything it records.
+`/eklavya-panel-demo` (`DEMO_COMMAND`) is the maintainer's shortcut for trying the pane: it seeds `PanelState.demo` with a mock question and never calls the server, so it works with `quiz.panel` off. While `demo` is set the heartbeat (`beat`) does not sync, `submit` grades locally with `demoResult` (no `panel_answer`, grader or explainer) and Next restarts the mock; `/eklavya-panel` and a real `present_question` sync replace it. On a non-terminal surface it also offers the Answer cards switch: `button` is the production layout, `client` draws each option as a `Client` region from `card.tsx` that posts `{pick}` to the `ui.message` hook, which accepts only an id of the open question. The switch is demo-only until the whole-card press is observed on Desktop; then make it the default and say so in `docs/verified-schemas.md`.
 Run `scripts/test-panel-mod.sh`: it stages the mod as its own plugin, validates
 it, runs `claude plugin test`, then validates the distributed plugin.
 

package/dist/plugin/hooks/panel/card.tsx

@@ -0,0 +1,47 @@
+import type { ClientModule } from 'claude-code'
+
+/**
+ * One answer card drawn as a `Client` region, so a press anywhere on it (border,
+ * padding, title or note) picks it. A `Button` is only as large as its label, and a
+ * `Box` takes no press, so this is the one way to make the whole card the target.
+ *
+ * It gets no mods API: it holds only its hover and posts `{ pick: id }` to the hooks
+ * module, whose `ui.message` hook validates the id and records the pick. The colours
+ * come in as props, so the module imports nothing.
+ */
+export type CardProps = {
+  id: string
+  label: string
+  note: string
+  chosen: boolean
+  locked: boolean
+  brand: string
+  fill: string
+  text: string
+  noteText: string
+}
+
+const Card: ClientModule<CardProps, { hover: boolean }> = (p, s) => {
+  const { Box, Text } = s.elements
+  const hover = s.state?.hover ?? false
+  // One listener, replaced on each call, so it always reads this render's props.
+  s.onPointer(e => {
+    if (e.type === 'enter' && !hover) s.setState({ hover: true })
+    else if (e.type === 'leave' && hover) s.setState({ hover: false })
+    else if (e.type === 'up' && !p.locked && (e.button === undefined || e.button === 'left')) s.post({ pick: p.id })
+  })
+  return Box({
+    flexDirection: 'column',
+    paddingX: 2,
+    paddingY: 1,
+    borderStyle: p.chosen ? 'bold' : 'single',
+    borderColor: p.chosen || (hover && !p.locked) ? p.brand : 'inactive',
+    backgroundColor: p.chosen ? p.fill : undefined,
+    children: [
+      Text({ wrap: 'wrap', bold: p.chosen, color: p.chosen ? p.text : undefined, children: [p.label] }),
+      Text({ wrap: 'wrap', dimColor: !p.chosen, color: p.chosen ? p.noteText : undefined, children: [p.note] }),
+    ],
+  })
+}
+
+export default Card

package/dist/plugin/hooks/panel/model.ts

@@ -1,4 +1,4 @@
-import type { PanelQuestion, PanelState } from './types'
+import type { PanelQuestion, PanelResult, PanelState } from './types'
 
 /** The pane's id, as `$.ui.open` and the `ui.render` hook both name it. */
 export const PANE = 'eklavya-quiz'
@@ -162,6 +162,15 @@ export const STR = {
   focus: 'Ctrl+X then Tab moves the keys here.',
   keys: '1–4 pick · o other · s submit · k skip · t teach me · Esc back to prompt',
   off: 'The quiz panel is off. Turn it on with: eklavya config set quiz.panel true',
+  demoBanner: 'DEMO · a mock question. Nothing here is graded by the server or recorded.',
+  demoReady: 'Last click: none yet',
+  demoOpened: 'Eklavya quiz panel opened with a mock question. Nothing you answer is recorded.',
+  demoFailed: 'The demo panel could not open. Try /eklavya-panel-demo again.',
+  demoStyleLabel: 'Answer cards:',
+  demoStyleButton: 'Native button',
+  demoStyleClient: 'Whole card',
+  demoExplanation: 'A rename inside one folder is atomic: the poller sees the finished file or none, never half of it. (This is a mock, so it was not recorded.)',
+  demoTyped: 'Typed answers are not graded in the demo. (Nothing was sent or recorded.)',
 } as const
 
 /** The explainer agent the panel starts itself, so no prompt lands in the transcript. */
@@ -202,6 +211,39 @@ export function explainerBrief(x: ExplainBlock): string {
 
 export const answerWas = (label: string): string => `The answer was: ${label}`
 
+/** The command that opens the mock question; it never reaches the server, so it needs no question to be waiting. */
+export const DEMO_COMMAND = 'eklavya-panel-demo'
+
+/** The mock question: long answers, each with a note, as real questions have. `o3` is the right one. */
+export const DEMO_QUESTION: PanelQuestion = {
+  question_id: 'demo',
+  repo: '*',
+  stem: 'A job writes a text file into a shared folder that another system polls every minute. Why is it safer to write the file under a temporary name and then rename it into place, rather than writing it directly under its final name?',
+  options: [
+    { id: 'o1', label: 'Renaming makes the write faster', note: 'A rename skips the disk write, so the final file appears sooner than a direct write would.' },
+    { id: 'o2', label: 'Renaming encrypts the file in transit', note: 'The temporary name keeps the contents protected until the rename publishes the finished file.' },
+    { id: 'o3', label: 'The poller never sees a half-written file', note: 'A rename within one folder is atomic, so the file appears complete or not at all to the reader.' },
+    { id: 'o4', label: 'Renaming lets two jobs write at once', note: 'Each job writes its own temporary name, so both can write the same final file without any conflict.' },
+  ],
+  concept_name: 'Atomic file replace',
+  tier: 2,
+  more: true,
+}
+
+export const DEMO_RIGHT = 'o3'
+
+/** What the server would reply, made here: a demo answer is graded on this machine and recorded nowhere. */
+export function demoResult(kind: 'choice' | 'text' | 'skip' | 'dont_know', optionId: string | null): PanelResult {
+  const right = DEMO_QUESTION.options.find(o => o.id === DEMO_RIGHT)!.label
+  if (kind === 'skip') return { phase: 'skipped', attempt_id: 0 }
+  if (kind === 'dont_know') return { phase: 'answered', attempt_id: 0, taught: true, correct: false, correct_label: right, explanation: STR.demoExplanation }
+  const correct = kind === 'choice' && optionId === DEMO_RIGHT
+  return { phase: 'answered', attempt_id: 0, correct, correct_label: right, explanation: kind === 'text' ? STR.demoTyped : STR.demoExplanation }
+}
+
+/** The tester's line of what was just clicked, and how the click arrived. */
+export const demoLast = (what: string): string => `Last click: ${what}`
+
 /**
  * The key hints. Only the terminal gets them: there Ctrl+X then Tab moves the keys into the pane. The
  * desktop app keeps typing in its prompt even after a click on the pane (seen 2026-10-16), so a mod's

package/dist/plugin/hooks/panel/register.tsx

@@ -13,7 +13,10 @@ import {
   STR,
   WORDMARK,
   CLOSE_MS,
+  DEMO_QUESTION,
   answerWas,
+  demoLast,
+  demoResult,
   explainerBrief,
   codify,
   gradingRequest,
@@ -30,6 +33,7 @@ import {
   hintLines,
 } from './model'
 import type { PanelPending, PanelQuestion, PanelState } from './types'
+import type { CardProps } from './card'
 
 /**
  * The Eklavya quiz panel: a pane that shows the question the tutor model handed
@@ -168,9 +172,24 @@ async function sync($: EngineInterface): Promise<'disabled' | 'none' | 'question
 /** A throttled sync for busy events: the heartbeat, and the way a question presented elsewhere finds its pane. */
 async function beat($: EngineInterface): Promise<void> {
   if (Date.now() - lastSyncAt < HEARTBEAT_MS) return
+  // A mock question is not in the database: a sync would find nothing waiting and clear it.
+  if (await inDemo($)) return
   await sync($)
 }
 
+async function inDemo($: EngineInterface): Promise<boolean> {
+  const s: PanelState = (await $.state.get(REF)).value ?? EMPTY
+  return s.demo !== undefined
+}
+
+/** The mock question, drawn with the given answer-card style. Opened from the person's own command, so at any width. */
+async function startDemo($: EngineInterface, style: 'button' | 'client'): Promise<void> {
+  disarm()
+  openedFor = null
+  await update($, quiz, () => ({ ...EMPTY, step: 'awaiting', question: DEMO_QUESTION, demo: { style, last: STR.demoReady } }))
+  await $.ui.open({ id: PANE, title: STR.brand, closeOnEscape: true })
+}
+
 /** Says what went wrong, in words, and keeps whatever the learner had written. */
 async function fail($: EngineInterface, message: string): Promise<void> {
   await update($, quiz, (s: PanelState) => ({ ...s, step: 'error', message }))
@@ -203,6 +222,21 @@ async function submit($: EngineInterface, wanted: PanelPending | null): Promise<
       }
     }
 
+    // The mock question is answered here: nothing is sent, graded by the server or recorded.
+    if (state.demo) {
+      const kind = pending ? pending.kind : state.draft.other ? 'text' : 'choice'
+      const result = demoResult(kind, pending ? null : state.draft.picked)
+      await update($, quiz, (s: PanelState) => ({
+        ...s,
+        step: result.phase === 'skipped' ? 'skipped' : 'feedback',
+        result,
+        pending: null,
+        message: null,
+        demo: s.demo && { ...s.demo, last: demoLast(`${kind} answer submitted`) },
+      }))
+      return
+    }
+
     await update($, quiz, (s: PanelState) => ({ ...s, step: 'grading', message: null }))
     const where = await whereAmI($)
     if (epoch !== mine) return
@@ -284,6 +318,11 @@ export const register: Register = on => {
     } catch {
       /* Without the command the pane still opens by itself; only reopening is lost. */
     }
+    try {
+      await $.command.register({ name: 'eklavya-panel-demo', description: 'Open the Eklavya quiz panel with a mock question, to try its clicks' })
+    } catch {
+      /* Only the test shortcut is lost. */
+    }
     try {
       await sync($)
     } catch {
@@ -348,6 +387,8 @@ export const register: Register = on => {
   on('command.run', { command: 'eklavya-panel' }, async $ => {
     try {
       openedFor = null
+      // A mock question on screen gives way to the real state.
+      if (await inDemo($)) await update($, quiz, () => EMPTY)
       // The person typed this, so the pane is seated at any width. Off is inert:
       // the server says so and nothing is opened.
       const found = await sync($)
@@ -359,6 +400,30 @@ export const register: Register = on => {
     }
   })
 
+  // The mock question: opens at once, answered on this machine, so a card or a click can be tried with no real question waiting.
+  on('command.run', { command: 'eklavya-panel-demo' }, async $ => {
+    try {
+      await startDemo($, 'button')
+      return { text: STR.demoOpened }
+    } catch {
+      return { text: STR.demoFailed }
+    }
+  })
+
+  // A press on a whole-card `Client` (card.tsx) arrives here as data, never as a fact: only an id of the open question counts.
+  on('ui.message', { component: 'Pane' }, async ($, e, next) => {
+    if (e.requestId === PANE) {
+      try {
+        const id = (e.data as { pick?: unknown } | null)?.pick
+        const s: PanelState = (await $.state.get(REF)).value ?? EMPTY
+        if (typeof id === 'string' && s.question?.options.some(o => o.id === id)) await pick($, id, 'whole card')
+      } catch {
+        /* Fail open: the card stays as it was. */
+      }
+    }
+    return next(e)
+  })
+
   // The mod's queued prompts are instructions for the model, not words for the
   // learner: their transcript row shows one short line, as a tool call does.
   // Only the drawing changes; the model still reads the whole message.
@@ -373,7 +438,7 @@ export const register: Register = on => {
   on('ui.render', { component: 'Pane', requestId: 'eklavya-quiz' }, async ($, e, next) => {
     // Only our pane: every other pane, and everything else, is the host's.
     if (e.requestId !== PANE) return next(e)
-    const { Box, Text, Button, Input, Markdown } = $.ui.resolve(e) as any
+    const { Box, Text, Button, Input, Markdown, Client } = $.ui.resolve(e) as any
     const s: PanelState = await read($, quiz)
     const q = s.question
 
@@ -454,9 +519,24 @@ export const register: Register = on => {
         {body}
       </Box>
     )
+    // The mock question's tester bar: what it is, the last click, and (desktop only) how the answer cards are drawn.
+    const demoBar = s.demo ? (
+      <Box key="demo-bar" flexDirection="column" gap={app ? 1 : 0}>
+        <Text color="warning">{STR.demoBanner}</Text>
+        <Text dimColor>{s.demo.last}</Text>
+        {app ? (
+          <Box flexDirection="row" gap={2} alignItems="center">
+            <Text dimColor>{STR.demoStyleLabel}</Text>
+            <Button key="style-button" label={STR.demoStyleButton} variant={s.demo.style === 'button' ? 'primary' : 'secondary'} onPress={() => setStyle($, 'button')} />
+            <Button key="style-client" label={STR.demoStyleClient} variant={s.demo.style === 'client' ? 'primary' : 'secondary'} onPress={() => setStyle($, 'client')} />
+          </Box>
+        ) : null}
+      </Box>
+    ) : null
     const frame = (...body: unknown[]) => (
       <Box flexDirection="column" paddingX={1} gap={1}>
         {head(q ? topicLabel(q) : undefined)}
+        {demoBar}
         {body}
         {hint}
       </Box>
@@ -520,8 +600,14 @@ export const register: Register = on => {
         {note && !app ? <Text wrap="wrap" dimColor={!chosen} color={chosen ? PICKED.note : undefined}>{`\n   ${note}`}</Text> : null}
       </Button>
     )
+    const wholeCard = app && s.demo?.style === 'client'
     const options = q.options.map((o, i) => {
       const chosen = !s.draft.other && s.draft.picked === o.id
+      // The whole card is one pressable region, so a click on its padding or note picks too (card.tsx).
+      if (wholeCard) {
+        const props: CardProps = { id: o.id, label: plainLabel(o.label), note: o.note ? plainLabel(o.note) : '', chosen, locked, brand: BRAND, fill: PICKED.bg, text: PICKED.text, noteText: PICKED.note }
+        return <Client key={`card-${o.id}`} module="./card.tsx" width="100%" props={props} />
+      }
       return card(
         o.id,
         chosen,
@@ -591,9 +677,18 @@ export const register: Register = on => {
   })
 }
 
+/** The demo's switch between the two ways of drawing an answer card on the desktop. */
+async function setStyle($: EngineInterface, style: 'button' | 'client'): Promise<void> {
+  await update($, quiz, (s: PanelState) => (s.demo ? { ...s, demo: { ...s.demo, style, last: demoLast(`card style set to ${style}`) } } : s))
+}
+
 /** Selecting an option records a draft and nothing else: it never submits, grades or skips. */
-async function pick($: EngineInterface, id: string): Promise<void> {
-  await update($, quiz, (s: PanelState) => (s.step === 'awaiting' || s.step === 'error' ? { ...s, draft: { ...s.draft, picked: id, other: false }, message: null } : s))
+async function pick($: EngineInterface, id: string, via = 'button'): Promise<void> {
+  await update($, quiz, (s: PanelState) =>
+    s.step === 'awaiting' || s.step === 'error'
+      ? { ...s, draft: { ...s.draft, picked: id, other: false }, message: null, ...(s.demo ? { demo: { ...s.demo, last: demoLast(`${id} picked (${via})`) } } : {}) }
+      : s,
+  )
   try {
     // The host's focus mark follows the pick, so the highlighted answer is the chosen one even after a hotkey.
     await $.ui.focus({ requestId: PANE, key: `opt-${id}` })
@@ -675,6 +770,9 @@ async function askNext($: EngineInterface): Promise<void> {
   disarm()
   try {
     openedFor = null
+    const now: PanelState = (await $.state.get(REF)).value ?? EMPTY
+    // Next in the demo starts the mock again: it must not ask the model for a real question.
+    if (now.demo) return await startDemo($, now.demo.style)
     await update($, quiz, () => ({ ...EMPTY, step: 'loading' }))
     await $.prompt.submit({ text: NEXT_PROMPT })
   } catch {

package/dist/plugin/hooks/panel/types/index.d.ts

@@ -55,6 +55,11 @@ export type PanelState = {
   result: PanelResult | null
   /** Words for the learner: why the pane is in `error`, or a one-line notice in `none`. */
   message: string | null
+  /**
+   * Set only by `/eklavya-panel-demo`: the question is a mock, answered on this machine and never sent to the
+   * server. `style` is how the desktop draws the answer cards; `last` is the latest click, for the tester.
+   */
+  demo?: { style: 'button' | 'client'; last: string }
 }
 
 declare module 'claude-code' {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eklavya",
-  "version": "1.85.2",
+  "version": "1.86.0",
   "description": "Learn while your agent works — local knowledge graph, spaced repetition, and quiz gating for agent-assisted development.",
   "license": "MIT",
   "repository": {