@danypops/pi-papyrus 0.55.5 → 0.55.7

package/README.md

@@ -17,7 +17,7 @@ Agent-facing domain tools own lifecycle invariants and sit above this store API.
 - **docs** (`docs_create`, `docs_list`, `docs_show`, `docs_activate`, `docs_archive`, `docs_reopen`, `docs_link`, `docs_assign_project`, `docs_update`) — activate/archive/reopen and document-safe graph links; Note mutations remain behind the Notes facade
 - **rules** (`rules_create`, `rules_list`, `rules_show`, `rules_preview`, `rules_enable`, `rules_disable`, `rules_gate`, `rules_assign_project`, `rules_update`) — enable/disable and attach governance gates to tasks
 - **playbooks** (`playbooks_create`, `playbooks_list`, `playbooks_show`, `playbooks_invoke`, `playbooks_preview`, `playbooks_enable`, `playbooks_disable`, `playbooks_assign_project`, `playbooks_update`, `playbooks_contain`, `playbooks_uncontain`, `playbooks_depend`, `playbooks_undepend`) — a trigger and an ordered list of steps. Each step is a plain prose string (a task), or a structured object: `{kind:'doc',title,body?,subtype?,labels?}` creates a Doc, `{kind:'rule',title,body?,condition?,action?,severity?,labels?}` creates a Rule, `{kind:'call',title,playbookId,arguments?}` nests another Playbook's own run as a pipeline step gated in the same sequence, `{kind:'task',title?,body}` is an explicit task step. `playbooks_invoke` recycles the shared blueprint materialization engine: it compiles the steps and any `contain`/`depend` composition into real artifacts (a Task per plain/task step, a Doc/Rule per doc/rule step, a nested run per call step), wires task-like steps with `dependsOn` so completing one auto-focuses the next, and focuses the first real task. No text dump — one step surfaces at a time, as it becomes the focused task, same as any other Task. `playbooks_contain`/`playbooks_uncontain` nest a child Playbook inside a parent (its steps run after the parent's own, as part of it); `playbooks_depend`/`playbooks_undepend` chain a prerequisite Playbook before another (it must fully complete first) -- both are whole-Playbook composition, distinct from a `call` step's finer-grained, single-step nesting. `playbooks_preview` renders the whole tree as text with no side effects, for reading before invoking. A Playbook can declare named arguments (`{name, description?, required?, type?('string'|'number'|'boolean', default 'string'), enum?, default?}`, required defaults true; referenced in step text/call arguments as `{{name}}`); invoking with a required one unsupplied creates nothing and reports exactly which are still missing, directing the agent to ask via `discuss_open`/`discuss_reply` with `live:true` rather than guess
-- **discuss** (`discuss_open`, `discuss_reply`, `discuss_defer`, `discuss_resume`, `discuss_settle`, `discuss_block`, `discuss_unblock`, `discuss_show`, `discuss_rounds`, `discuss_list`) — a Discussion persists across multiple rounds and can genuinely block a Task's completion until settled or deferred (`discuss_block`/`discuss_unblock`). `discuss_reply` is refused once deferred or settled -- `discuss_resume` first. `discuss_open`/`discuss_reply` can pose a structured choice via `options` (2-10 entries, each a bare string or `{title, description}`) + `options_mode` (`single`/`multi`); a later `discuss_reply` answers it via `selected`, validated against it. `live: true` on either gets the human's answer synchronously in the same tool call -- the operation itself always durably records the round first (exactly like every other Vehicle operation), then an optional local prompt (the pending choice's picker if one was posed, otherwise a freeform question) runs via a per-operation `interactiveFollowUps` resolver (see `@danypops/vehicle-client-pi`), degrading silently to the plain async round when there's no interactive UI
+- **discuss** (`discuss_open`, `discuss_reply`, `discuss_defer`, `discuss_resume`, `discuss_settle`, `discuss_block`, `discuss_unblock`, `discuss_show`, `discuss_rounds`, `discuss_list`) — a Discussion persists across multiple rounds and can genuinely block a Task's completion until settled or deferred (`discuss_block`/`discuss_unblock`). `discuss_reply` is refused once deferred or settled -- `discuss_resume` first. `discuss_open`/`discuss_reply` can pose a structured choice via `options` (2-10 entries, each a bare string or `{title, description}`) + `options_mode` (`single`/`multi`); a later `discuss_reply` answers it via `selected`, validated against it. Adding `correct_options` + `explanation` turns that same choice into a graded quiz/knowledge assessment -- see "Quiz assessments" below. `live: true` on either gets the human's answer synchronously in the same tool call -- the operation itself always durably records the round first (exactly like every other Vehicle operation), then an optional local prompt (the pending choice's picker if one was posed, otherwise a freeform question) runs via a per-operation `interactiveFollowUps` resolver (see `@danypops/vehicle-client-pi`), degrading silently to the plain async round when there's no interactive UI
 
 Every tool operation is registered in the daemon's `/api/v1/ops` registry; parity is verified in tests. The task consumer uses the `tasks.graph` operation, which returns task nodes with explicit parent, child, and dependency IDs rather than leaking SQLite rows or asking the UI to reconstruct relationships.
 
@@ -61,7 +61,7 @@ Blocking is real: `tasks.complete` is refused while any `active` Discussion has
 
 `open`/`reply` can also pose a structured choice instead of (or alongside) free text: `options` (2-10 entries) plus `options_mode` -- `single` is mutually exclusive (exactly one pick), `multi` allows several. The Discussion remembers the pending choice (`extra.discussion.pendingOptions`/`pendingOptionsMode`) until a `reply` answers it with `selected`, validated against exactly what was offered and the mode's cardinality; a reply can also pose the *next* round's choice in the same call.
 
-Run `/discuss` for the interactive panel: browse every Discussion (the real `active`/`deferred`/`settled` state shown per row, alongside any choice awaiting an answer), open a scrollable transcript showing what was posed and picked in each round, and reply/defer/resume/settle or block/unblock a task without leaving the TUI. Replying to a pending choice shows a real picker -- the native single-select list for `single`, or a checkbox multi-select for `multi`, since no built-in multi-select exists in the Pi extension UI. Both modes append a numbered "type your own answer" row -- a genuinely open answer is exactly as valid as any posed option. The multi-select picker supports a number key as a direct quick-select (jump straight to that row instead of scrolling), and steadily highlights checked rows while dimming the rest so the eye reads "what's chosen" independent of cursor position; its cursor row blinks to mark focus. It also auto-cancels after 30s of zero input -- the very first keystroke of any kind stops that countdown permanently for that prompt. Opening a *new* Discussion is left to the agent (same as Docs/Rules/Playbooks) -- `/discuss` browses and drives existing ones.
+Run `/discuss` for the interactive panel: browse every Discussion (the real `active`/`deferred`/`settled` state shown per row, alongside any choice awaiting an answer), open a scrollable transcript showing what was posed and picked in each round, and reply/defer/resume/settle or block/unblock a task without leaving the TUI. Replying to a pending choice shows a real picker -- the native single-select list for `single`, or a checkbox multi-select for `multi`, since no built-in multi-select exists in the Pi extension UI. Both modes append a numbered "type your own answer" row -- a genuinely open answer is exactly as valid as any posed option. The multi-select picker supports a number key as a direct quick-select (jump straight to that row instead of scrolling), and steadily highlights checked rows while dimming the rest so the eye reads "what's chosen" independent of cursor position; its cursor row blinks to mark focus. It also auto-cancels after 30s of zero input -- the very first keystroke of any kind stops that countdown permanently for that prompt. A quiz's options display lettered (A, B, C, ...) in this same picker. Opening a *new* Discussion is left to the agent (same as Docs/Rules/Playbooks) -- `/discuss` browses and drives existing ones.
 
 ```bash
 papyrus discuss open --title "Naming" --actor alice --content "Should we rename this?" --blocks-json '["task-id"]' --json
@@ -74,6 +74,34 @@ papyrus discuss settle <discussion-id> --settlement "Agreed: renaming to X" --js
 papyrus discuss show <discussion-id> --json
 ```
 
+### Quiz assessments
+
+A posed choice becomes a graded knowledge assessment by adding `correct_options` (one or more entries drawn verbatim from `options` -- exact text, never an index or a display letter) + `explanation` (**required**, always shown after grading -- especially when the answer is wrong) to `discuss_open`/`discuss_reply`. Options are dynamic (any count from 2 up to the enforced 10-option ceiling, not hard-coded to four) and display lettered A, B, C, ... in every surface (the live picker, the `/discuss` transcript, the tool-call card) -- single letters always suffice since the 10-option ceiling sits well under the 26-letter limit.
+
+- A `"single"` quiz (the participant can only pick one) must have exactly one correct option; a `"multi"` quiz may have several, graded correct iff the reply's `selected` set exactly matches the correct set -- no partial credit.
+- The correct answer is never exposed before submission: `discuss_open`'s own response, and every `discuss_show`/`discuss_rounds` read of an unanswered quiz, carries only a `quiz: true` marker on that round -- never the answer. Server-side, it's held in dedicated hidden storage that Discuss's own general-purpose read queries structurally cannot select, not merely omitted at the API layer.
+- Once answered, the round that carries `selected` also carries `quizResult: { correct, correctOptions, explanation }` -- the durable, permanent record of what was asked, what was picked, and whether it was right, so a later turn can adapt to demonstrated knowledge.
+- Malformed quizzes are rejected: too few options (below the existing 2-option floor), a duplicate/unknown `correct_options` entry, more than one correct option under `"single"` mode, or `correct_options`/`explanation` given without the other.
+
+```bash
+# A four-option quiz with one correct answer.
+papyrus discuss open --title "Geography check" --actor agent \
+  --content "What is the capital of France?" \
+  --options-json '["Paris","London","Berlin","Madrid"]' --options-mode single \
+  --correct-options-json '["Paris"]' \
+  --explanation "Paris has been the capital of France since 987 AD." --json
+
+# A "select all that apply" quiz with more than one correct option.
+papyrus discuss open --title "Primes check" --actor agent \
+  --content "Which of these are prime numbers?" \
+  --options-json '["2","3","4","9"]' --options-mode multi \
+  --correct-options-json '["2","3"]' \
+  --explanation "2 and 3 are prime; 4 and 9 are not." --json
+
+# The participant answers like any other posed choice -- grading and the explanation come back in the same call.
+papyrus discuss reply <discussion-id> --actor human --content "Paris" --selected-json '["Paris"]' --json
+```
+
 ## Tasks
 
 Run `/tasks` for the interactive task panel:

package/extension/src/discuss/discuss.ts

@@ -15,7 +15,7 @@
  * human-authored inbox.
  */
 
-import { type Artifact, type DiscussionAndRounds, readDiscussionExtra } from "@danypops/papyrus";
+import { type Artifact, type DiscussionAndRounds, quizOptionLabel, readDiscussionExtra } from "@danypops/papyrus";
 import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import { showArtifactBrowser } from "../artifact/artifact-browser.ts";
 import { DISCUSSION_STATE_PRESENTATION, DOC_STATUS_PRESENTATION } from "../artifact/artifact-status-presentation.ts";
@@ -111,27 +111,37 @@ export async function showDiscussions(ctx: ExtensionCommandContext): Promise<voi
 				const transcript = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.show", { id: discussion.id });
 				const question = transcript.rounds.at(-1)?.content?.trim() || `Reply to "${discussion.title}":`;
 				const subtitle = discussion.title;
+				// A quiz's options display lettered (A, B, C, ...) in the picker -- the correct answer itself
+				// never reaches this client before submission (see domain/discussion.ts's own comment on why).
 				const answer =
 					pending?.pendingOptions && pending.pendingOptions.length > 0 && pending.pendingOptionsMode
 						? await askQuestion(commandCtx, {
 								question,
 								subtitle,
 								options: pending.pendingOptions.map((title, index) => ({
-									title,
+									title: pending.pendingIsQuiz ? `${quizOptionLabel(index)}. ${title}` : title,
 									description: pending.pendingOptionDescriptions?.[index] || undefined,
 								})),
 								allowMultiple: pending.pendingOptionsMode === "multi",
 							})
 						: await askQuestion(commandCtx, { question, subtitle });
 				if (!answer) return; // canceled
-				await callService("discuss.reply", {
+				const replied = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.reply", {
 					id: discussion.id,
 					actor: ACTOR,
 					content: answer.content,
 					...(answer.selected ? { selected: answer.selected } : {}),
 					source: SOURCE,
 				});
-				commandCtx.ui.notify(answer.selected ? `Selected: ${answer.selected.join(", ")}` : "Reply added.", "info");
+				const quizResult = replied.rounds[0]?.quizResult;
+				const message = quizResult
+					? quizResult.correct
+						? `✅ Correct! ${quizResult.explanation}`
+						: `❌ Incorrect -- correct answer(s): ${quizResult.correctOptions.join(", ")}. ${quizResult.explanation}`
+					: answer.selected
+						? `Selected: ${answer.selected.join(", ")}`
+						: "Reply added.";
+				commandCtx.ui.notify(message, "info");
 				return;
 			}
 			if (choice === "Defer") {

package/extension/src/discuss/discussion-detail-view.ts

@@ -15,6 +15,7 @@ import {
 	ARTIFACT_DETAIL_RESERVED_ROWS,
 	type Artifact,
 	type DiscussionRound,
+	quizOptionLabel,
 	readDiscussionExtra,
 } from "@danypops/papyrus";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
@@ -126,17 +127,48 @@ class DiscussionTranscriptViewport {
 			const roundHeader =
 				theme.fg("accent", `[round ${round.roundNumber}] `) + theme.bold(round.actor) + theme.fg("dim", ` · ${round.occurredAt}`);
 			const body = renderMarkdownBody(round.content, width - 2, this.activeTheme).map((line) => ({ text: `  ${line}` }));
+			// Quiz options get lettered (A, B, C, ...) and a distinct "Quiz" label; a plain, non-quiz posed
+			// choice keeps its existing comma-joined "Posed" presentation unchanged (backward compatible).
 			const posed =
 				round.options && round.options.length > 0
 					? [
 							{
-								text: `  ${theme.fg("muted", `Posed (${round.optionsMode === "multi" ? "pick several" : "pick one"}): ${round.options.join(", ")}`)}`,
+								text: `  ${theme.fg(
+									"muted",
+									round.quiz
+										? `Quiz (${round.optionsMode === "multi" ? "pick all that apply" : "pick one"}): ${round.options
+												.map((option, optionIndex) => `${quizOptionLabel(optionIndex)}. ${option}`)
+												.join("  ")}`
+										: `Posed (${round.optionsMode === "multi" ? "pick several" : "pick one"}): ${round.options.join(", ")}`,
+								)}`,
 							},
 						]
 					: [];
 			const picked =
 				round.selected && round.selected.length > 0 ? [{ text: `  ${theme.fg("success", `Selected: ${round.selected.join(", ")}`)}` }] : [];
-			return [{ text: roundHeader }, ...body, ...posed, ...picked, ...(index < this.rounds.length - 1 ? [{ text: "" }] : [])];
+			// The graded verdict -- always includes the explanation, especially when wrong. Only ever
+			// present on the round that actually answered a pending quiz (see domain/discussion.ts).
+			const quizVerdict = round.quizResult
+				? [
+						{
+							text: `  ${theme.fg(
+								round.quizResult.correct ? "success" : "error",
+								round.quizResult.correct
+									? "✅ Correct!"
+									: `❌ Incorrect -- correct answer(s): ${round.quizResult.correctOptions.join(", ")}.`,
+							)}`,
+						},
+						{ text: `  ${theme.fg("muted", round.quizResult.explanation)}` },
+					]
+				: [];
+			return [
+				{ text: roundHeader },
+				...body,
+				...posed,
+				...picked,
+				...quizVerdict,
+				...(index < this.rounds.length - 1 ? [{ text: "" }] : []),
+			];
 		});
 		this.lines = [...header, ...(transcript.length > 0 ? transcript : [{ text: theme.fg("muted", "No rounds recorded.") }])];
 		this.offsetY = Math.min(this.offsetY, Math.max(0, this.lines.length - this.visibleLines));

package/extension/src/tools/renderers/discussion.ts

@@ -1,4 +1,4 @@
-import type { Artifact } from "@danypops/papyrus";
+import { type Artifact, type DiscussionQuizResult, quizOptionLabel } from "@danypops/papyrus";
 import { expandHint } from "@danypops/vehicle-client-pi/expand-hint";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
@@ -7,11 +7,16 @@ import { detailViewTheme, measure, statusColor, statusGlyph } from "../../tool-r
 import { isArtifact, isArtifactArray, type RenderableDiscussionParent } from "./shared.ts";
 
 /** A Discussion round -- discuss.open/reply/show/rounds' own transcript entry. Detected the
- * same name-independent, shape-based way as the others in this directory. */
+ * same name-independent, shape-based way as the others in this directory. quiz/quizResult are
+ * the two quiz-safe fields (see domain/discussion.ts) -- optional, so a plain non-quiz round
+ * renders exactly as before. */
 export interface DiscussionRoundOutput {
 	roundNumber: number;
 	actor: string;
 	content: string;
+	options?: string[];
+	quiz?: boolean;
+	quizResult?: DiscussionQuizResult;
 }
 
 export function isDiscussionRound(value: unknown): value is DiscussionRoundOutput {
@@ -55,10 +60,27 @@ export function isDiscussionListOutput(value: unknown): value is DiscussionListO
 	return isArtifactArray(row.discussions);
 }
 
+/** Appended to a quiz round's own body text -- lettered options when posed, the graded verdict +
+ * explanation (always shown, especially when wrong) once answered. A plain, non-quiz round's
+ * body is untouched (backward compatible). */
+function quizBodySuffix(round: DiscussionRoundOutput): string {
+	const posed =
+		round.quiz && round.options && round.options.length > 0
+			? `\n${round.options.map((option, index) => `${quizOptionLabel(index)}. ${option}`).join("  ")}`
+			: "";
+	const verdict = round.quizResult
+		? `\n${round.quizResult.correct ? "✅ Correct!" : `❌ Incorrect -- correct answer(s): ${round.quizResult.correctOptions.join(", ")}.`} ${round.quizResult.explanation}`
+		: "";
+	return `${posed}${verdict}`;
+}
+
 export function roundsSection(rounds: readonly DiscussionRoundOutput[]): DetailSection {
 	return {
 		heading: `Rounds (${rounds.length}):`,
-		items: rounds.map((round) => ({ byline: `${round.actor} · round ${round.roundNumber}`, body: round.content })),
+		items: rounds.map((round) => ({
+			byline: `${round.actor} · round ${round.roundNumber}`,
+			body: `${round.content}${quizBodySuffix(round)}`,
+		})),
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.55.5",
+  "version": "0.55.7",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "type": "module",
   "keywords": ["pi-package"],
@@ -12,23 +12,23 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "peerDependencies": {
-    "@danypops/vehicle-client-pi": "^0.42.0",
+    "@danypops/vehicle-client-pi": "^0.42.1",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "dependencies": {
-    "@danypops/jittor": "^0.18.1",
-    "@danypops/papyrus": "^0.54.2",
-    "@danypops/vehicle-client": "^0.10.0",
-    "@danypops/vehicle-core": "^0.12.3",
-    "@danypops/vehicle-server": "^0.18.1",
+    "@danypops/jittor": "^0.19.1",
+    "@danypops/papyrus": "^0.59.0",
+    "@danypops/vehicle-client": "^0.10.1",
+    "@danypops/vehicle-core": "^0.17.1",
+    "@danypops/vehicle-server": "^0.24.5",
     "beautiful-mermaid": "1.1.3",
     "malevich-tui-components": "^0.24.0"
   },
   "devDependencies": {
     "@danypops/pi-tui-harness": "^0.0.2",
-    "@danypops/vehicle-client-pi": "^0.42.0",
+    "@danypops/vehicle-client-pi": "^0.42.1",
     "@danypops/vehicle-conformance": "^0.3.0",
     "@earendil-works/pi-coding-agent": "^0.80.10",
     "bun-types": "latest",