@danypops/papyrus 0.19.0 → 0.19.1

package/README.md

@@ -162,6 +162,8 @@ Rounds are a dedicated append-only child table (mirroring Task history's own sha
 
 Blocking is real: `tasks.complete` is refused while any `active` Discussion has a `blocks` edge to that Task. A `deferred` Discussion does not block -- "we will get back to this" is distinct from "resolved."
 
+Run `/discuss` for the interactive panel: browse every Discussion (the real `active`/`deferred`/`settled` state shown per row, not just the shared Doc status glyph), open a scrollable transcript, and reply/defer/resume/settle or block/unblock a task without leaving the TUI. Opening a *new* Discussion is left to the agent (same as Docs/Rules/Skills) -- `/discuss` browses and drives existing ones.
+
 ```bash
 papyrus discuss open --title "Naming" --actor alice --content "Should we rename this?" --blocks-json '["task-id"]' --json
 papyrus discuss reply <discussion-id> --actor bob --content "I think so, here's why..." --json

package/extension/src/artifact-status-presentation.ts

@@ -36,6 +36,19 @@ export const SKILL_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
 	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
 };
 
+/**
+ * Keyed by extra.discussion.state, not the shared Doc status column -- a settled Discussion's
+ * doc.status becomes "archived", but a deferred one stays "active" at the doc level (see
+ * domain/discussion.ts's header comment). Reusing DOC_STATUS_PRESENTATION here would render
+ * "deferred" and "active" Discussions with the identical glyph, silently losing the one piece
+ * of state this feature exists to distinguish.
+ */
+export const DISCUSSION_STATE_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "accent" },
+	deferred: { label: "deferred", glyph: "⏸", color: "warning" },
+	settled: { label: "settled", glyph: "✓", color: "success" },
+};
+
 /** Rule severity gets its own color independent of status -- block is the loudest, info the quietest. */
 export const RULE_SEVERITY_PRESENTATION: Record<string, ThemeColor> = {
 	block: "error",

package/extension/src/discuss.ts

@@ -0,0 +1,96 @@
+/**
+ * discuss.ts — /discuss interactive panel.
+ * Reuses the generic artifact browser (artifact-browser.ts), same as docs.ts/rules.ts/notes.ts:
+ * a Discussion is a `doc` artifact, so the browser's list/filter/refresh/select-action loop
+ * applies unchanged. The one real wrinkle is that Discuss's meaningful lifecycle state
+ * (active/deferred/settled) lives in extra.discussion, not the shared doc status column the
+ * browser colors its row glyph by (see artifact-status-presentation.ts's DISCUSSION_STATE_PRESENTATION
+ * comment) -- so the real state is surfaced in rowMeta text instead, the same way rules.ts
+ * surfaces severity and notes.ts surfaces history count, both also not the row glyph.
+ *
+ * Creating a new Discussion is left to the agent (the discuss tool), matching docs.ts/rules.ts/
+ * skills.ts precedent -- Notes is the one kind with a human-facing creation command (/note),
+ * because Notes exists specifically as a human-authored inbox.
+ */
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import type { DiscussionAndRounds } from "../../src/discussion-service.ts";
+import { showArtifactBrowser } from "./artifact-browser.ts";
+import { DISCUSSION_STATE_PRESENTATION, DOC_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
+import { discussionRoundCountOf, discussionStateOf, showDiscussionDetailView } from "./discussion-detail-view.ts";
+import { callService } from "./service-client.ts";
+
+const SOURCE = "discuss-tui";
+const ACTOR = "human";
+
+export function discussionRowMeta(discussion: Artifact, theme: Theme): string {
+	const state = discussionStateOf(discussion);
+	const presentation = DISCUSSION_STATE_PRESENTATION[state];
+	const stateText = presentation ? theme.fg(presentation.color, `${presentation.glyph} ${presentation.label}`) : theme.fg("muted", "state unknown");
+	const rounds = discussionRoundCountOf(discussion);
+	return `${stateText} · ${rounds} round${rounds === 1 ? "" : "s"}`;
+}
+
+function discussionActions(discussion: Artifact): string[] {
+	const state = discussionStateOf(discussion);
+	if (state === "active") return ["Show transcript", "Reply", "Defer", "Settle", "Block a task", "Unblock a task"];
+	if (state === "deferred") return ["Show transcript", "Resume", "Settle"];
+	return ["Show transcript"]; // settled, or an unrecognized/corrupt state -- read-only either way
+}
+
+export async function showDiscussions(ctx: ExtensionCommandContext): Promise<void> {
+	await showArtifactBrowser(ctx, {
+		kind: "doc",
+		title: "Discussions",
+		listOperation: "discuss.list",
+		statusOrder: ["draft", "active", "archived"],
+		presentation: DOC_STATUS_PRESENTATION,
+		rowMeta: discussionRowMeta,
+		actions: discussionActions,
+		handleAction: async (choice, discussion, commandCtx) => {
+			if (choice === "Show transcript") {
+				const result = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.show", { id: discussion.id });
+				await showDiscussionDetailView(commandCtx, result.discussion, result.rounds);
+				return;
+			}
+			if (choice === "Reply") {
+				const content = await commandCtx.ui.input("Reply:", "");
+				if (!content) return;
+				await callService("discuss.reply", { id: discussion.id, actor: ACTOR, content, source: SOURCE });
+				commandCtx.ui.notify("Round added.", "info");
+				return;
+			}
+			if (choice === "Defer") {
+				const reason = await commandCtx.ui.input("Defer reason (optional):", "");
+				await callService("discuss.defer", { id: discussion.id, ...(reason ? { reason } : {}), actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify("Deferred.", "info");
+				return;
+			}
+			if (choice === "Resume") {
+				await callService("discuss.resume", { id: discussion.id, actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify("Resumed.", "info");
+				return;
+			}
+			if (choice === "Settle") {
+				const settlement = await commandCtx.ui.input("Settlement:", "");
+				if (!settlement) return;
+				await callService("discuss.settle", { id: discussion.id, settlement, actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify("Settled.", "info");
+				return;
+			}
+			if (choice === "Block a task") {
+				const taskId = await commandCtx.ui.input("Task artifact id to block:", "");
+				if (!taskId) return;
+				await callService("discuss.block", { id: discussion.id, task_id: taskId, actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify(`${discussion.id} now blocks ${taskId}`, "info");
+				return;
+			}
+			if (choice === "Unblock a task") {
+				const taskId = await commandCtx.ui.input("Task artifact id to unblock:", "");
+				if (!taskId) return;
+				const result = await callService<Record<string, unknown>, { unblocked: boolean }>("discuss.unblock", { id: discussion.id, task_id: taskId, actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify(result.unblocked ? `${discussion.id} no longer blocks ${taskId}` : "No such blocking relationship.", "info");
+			}
+		},
+	});
+}

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

@@ -0,0 +1,130 @@
+/**
+ * discussion-detail-view.ts — the transcript view for a single Discussion.
+ *
+ * The generic artifact detail view (artifact-detail-view.ts) formats an artifact's own
+ * fields (title, body, extra as JSON, edges); it has no way to show a Discussion's rounds,
+ * since those live in a dedicated child table fetched separately (discuss.show / discuss.rounds),
+ * not in the artifact row itself. Tasks needed the same kind of dedicated view for the same
+ * underlying reason (task-detail-view.ts) -- this mirrors that scrolling-viewport idiom rather
+ * than inventing a new one.
+ */
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import {
+	ARTIFACT_DETAIL_MAX_VISIBLE_LINES,
+	ARTIFACT_DETAIL_MIN_VISIBLE_LINES,
+	ARTIFACT_DETAIL_RESERVED_ROWS,
+} from "../../src/constants.ts";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import { readDiscussionExtra, type DiscussionRound } from "../../src/domain/discussion.ts";
+import { renderMarkdownBody, type ActiveTheme } from "./markdown.ts";
+import { DISCUSSION_STATE_PRESENTATION } from "./artifact-status-presentation.ts";
+
+interface TranscriptLine {
+	text: string;
+}
+
+/** Reads state defensively for display -- a corrupt/foreign extra.discussion shape shows as "unknown" rather than crashing the whole panel over one bad row. */
+export function discussionStateOf(discussion: Artifact): string {
+	try {
+		return readDiscussionExtra(discussion.extra).state;
+	} catch {
+		return "unknown";
+	}
+}
+
+export function discussionRoundCountOf(discussion: Artifact): number {
+	try {
+		return readDiscussionExtra(discussion.extra).roundCount;
+	} catch {
+		return 0;
+	}
+}
+
+class DiscussionTranscriptViewport {
+	private offsetY = 0;
+	private renderedWidth = 0;
+	private lines: TranscriptLine[] = [];
+	private readonly visibleLines: number;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly activeTheme: ActiveTheme,
+		private readonly discussion: Artifact,
+		private readonly rounds: DiscussionRound[],
+		private readonly close: () => void,
+	) {
+		this.visibleLines = Math.max(
+			ARTIFACT_DETAIL_MIN_VISIBLE_LINES,
+			Math.min(ARTIFACT_DETAIL_MAX_VISIBLE_LINES, tui.terminal.rows - ARTIFACT_DETAIL_RESERVED_ROWS),
+		);
+	}
+
+	invalidate(): void { this.renderedWidth = 0; }
+
+	render(width: number): string[] {
+		const contentWidth = Math.max(1, width - 2);
+		this.buildLines(contentWidth);
+		this.offsetY = Math.min(this.offsetY, Math.max(0, this.lines.length - this.visibleLines));
+		const end = Math.min(this.lines.length, this.offsetY + this.visibleLines);
+		const theme = this.activeTheme();
+		const border = theme.fg("borderMuted", "─".repeat(Math.max(1, width)));
+		const footer = [
+			this.lines.length > this.visibleLines ? `↑/↓ scroll · ${this.offsetY + 1}-${end}/${this.lines.length}` : "",
+			"Esc back",
+		].filter(Boolean).join(" · ");
+		return [
+			border,
+			truncateToWidth(theme.fg("accent", theme.bold("Discussion transcript")), width, ""),
+			border,
+			...this.lines.slice(this.offsetY, end).map((line) => truncateToWidth(` ${line.text}`, width, "")),
+			truncateToWidth(theme.fg("dim", footer), width, ""),
+			border,
+		];
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) { this.close(); return; }
+		if (matchesKey(data, "up")) this.offsetY = Math.max(0, this.offsetY - 1);
+		else if (matchesKey(data, "down")) this.offsetY = Math.min(Math.max(0, this.lines.length - this.visibleLines), this.offsetY + 1);
+		else if (matchesKey(data, "pageDown")) this.offsetY = Math.min(Math.max(0, this.lines.length - this.visibleLines), this.offsetY + this.visibleLines);
+		else if (matchesKey(data, "pageUp")) this.offsetY = Math.max(0, this.offsetY - this.visibleLines);
+		else return;
+		this.tui.requestRender();
+	}
+
+	private buildLines(width: number): void {
+		if (this.renderedWidth === width) return;
+		this.renderedWidth = width;
+		const theme = this.activeTheme();
+		const extra = (() => { try { return readDiscussionExtra(this.discussion.extra); } catch { return undefined; } })();
+		const presentation = extra ? DISCUSSION_STATE_PRESENTATION[extra.state] : undefined;
+		const stateLine = presentation
+			? theme.fg(presentation.color, `${presentation.glyph} ${presentation.label}`)
+			: theme.fg("muted", "state unknown");
+		const header: TranscriptLine[] = [
+			{ text: theme.bold(this.discussion.title) },
+			{ text: `${stateLine}${theme.fg("dim", ` · ${this.discussion.id}`)}` },
+			...(extra?.deferredReason ? [{ text: theme.fg("muted", `Deferred: ${extra.deferredReason}`) }] : []),
+			...(extra?.settlement ? [{ text: theme.fg("success", `Settled: ${extra.settlement}`) }] : []),
+			{ text: "" },
+		];
+		const transcript: TranscriptLine[] = this.rounds.flatMap((round, index) => {
+			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}` }));
+			return [{ text: roundHeader }, ...body, ...(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));
+	}
+}
+
+export async function showDiscussionDetailView(ctx: ExtensionCommandContext, discussion: Artifact, rounds: DiscussionRound[]): Promise<void> {
+	if (ctx.mode !== "tui") {
+		const lines = rounds.map((round) => `[round ${round.roundNumber}] ${round.actor}: ${round.content}`);
+		ctx.ui.notify([discussion.title, ...lines].join("\n"), "info");
+		return;
+	}
+	await ctx.ui.custom<void>((tui, theme, _keybindings, done) =>
+		new DiscussionTranscriptViewport(tui, () => ctx.ui.theme ?? theme, discussion, rounds, done));
+}

package/extension/src/index.ts

@@ -416,12 +416,13 @@ export default async function (pi: ExtensionAPI) {
 	// ── Interactive artifact browsers ──────────────────────────────────
 
 	// Lazy imports keep TUI components out of non-interactive startup paths.
-	const [tasksModule, docsModule, notesModule, rulesModule, skillsModule] = await Promise.all([
+	const [tasksModule, docsModule, notesModule, rulesModule, skillsModule, discussModule] = await Promise.all([
 		import("./tasks.ts"),
 		import("./docs.ts"),
 		import("./notes.ts"),
 		import("./rules.ts"),
 		import("./skills.ts"),
+		import("./discuss.ts"),
 	]);
 	let overlay: TaskOverlay | undefined;
 
@@ -454,6 +455,10 @@ export default async function (pi: ExtensionAPI) {
 		description: "Browse and invoke Papyrus skills and templates (interactive)",
 		handler: async (_args, ctx) => { await skillsModule.showSkills(ctx); },
 	});
+	pi.registerCommand("discuss", {
+		description: "Browse Papyrus Discussions and reply, defer, resume, settle, or block/unblock a task (interactive)",
+		handler: async (_args, ctx) => { await discussModule.showDiscussions(ctx); },
+	});
 	pi.registerCommand("context", {
 		description: "Structured, per-segment breakdown of the context window: real usage against the model's window, drilling into Papyrus Rules and the Pi-native skill catalog",
 		handler: async (_args, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/discussion-service.ts

@@ -3,7 +3,7 @@
  * append-only rounds (via DiscussionRoundStore). See domain/discussion.ts for the full
  * design rationale.
  */
-import { DISCUSSION_MAX_ROUNDS } from "./constants.ts";
+import { DISCUSSION_LIST_DEFAULT_LIMIT, DISCUSSION_LIST_MAX_LIMIT, DISCUSSION_MAX_ROUNDS } from "./constants.ts";
 import {
 	DISCUSSION_SUBTYPE,
 	isDiscussionArtifact,
@@ -29,7 +29,6 @@ export interface OpenDiscussionInput {
 	body?: string;
 	labels?: string[];
 	blocksTaskIds?: string[];
-	projectRoot?: string;
 }
 
 export interface DiscussionAndRounds {
@@ -150,7 +149,11 @@ export class Discussions {
 	}
 
 	list(filter: { state?: string; limit?: number } = {}): Artifact[] {
-		const rows = this.artifacts.query({ kind: "doc", subtype: DISCUSSION_SUBTYPE, limit: filter.limit });
+		// DISCUSSION_LIST_MAX_LIMIT/DEFAULT_LIMIT exist specifically so an unqualified discuss.list
+		// (limit omitted) can never fall through to queryArtifacts' own unbounded default -- the same
+		// class of gap notes.ts's noteListInput comment documents fixing for Notes.
+		const limit = Math.min(DISCUSSION_LIST_MAX_LIMIT, Math.max(1, Math.floor(filter.limit ?? DISCUSSION_LIST_DEFAULT_LIMIT)));
+		const rows = this.artifacts.query({ kind: "doc", subtype: DISCUSSION_SUBTYPE, limit });
 		if (!filter.state) return rows;
 		return rows.filter((row) => {
 			try { return this.extra(row).state === filter.state; } catch { return false; }