@danypops/papyrus 0.28.0 → 0.28.2

package/extension/src/discuss-ask-view.ts

@@ -18,6 +18,7 @@ import {
 	CURSOR_MARKER,
 	decodeKittyPrintable,
 	Editor,
+	type EditorComponent,
 	type EditorTheme,
 	fuzzyFilter,
 	Key,
@@ -51,7 +52,7 @@ function safeMarkdownTheme(): MarkdownTheme | undefined {
 	}
 }
 
-export type AskDisplayMode = "overlay" | "inline";
+export type AskDisplayMode = "overlay" | "inline" | "editor";
 
 export interface AskQuestionParams {
 	question: string;
@@ -1142,7 +1143,7 @@ async function askQuestionUnguarded(ctx: ExtensionContext, params: AskQuestionPa
 	const allowFreeform = params.allowFreeform ?? true;
 	const allowComment = params.allowComment ?? parseBooleanPreference(process.env["PAPYRUS_DISCUSS_ALLOW_COMMENT"]) ?? false;
 	const envMode = process.env["PAPYRUS_DISCUSS_DISPLAY_MODE"]?.trim().toLowerCase();
-	const envDisplayMode: AskDisplayMode | undefined = envMode === "overlay" || envMode === "inline" ? envMode : undefined;
+	const envDisplayMode: AskDisplayMode | undefined = envMode === "overlay" || envMode === "inline" || envMode === "editor" ? envMode : undefined;
 	const displayMode: AskDisplayMode = params.displayMode ?? envDisplayMode ?? "overlay";
 	const normalizedContext = params.context?.trim() || undefined;
 
@@ -1155,6 +1156,63 @@ async function askQuestionUnguarded(ctx: ExtensionContext, params: AskQuestionPa
 	}
 }
 
+/**
+ * Hosts an AskComponent in place of the real input editor (ctx.ui.setEditorComponent), the same
+ * mechanism Pi's own slash-command menu ecosystem uses to render attached to the prompt rather
+ * than as a floating overlay. getText() always returns the human's real in-progress draft,
+ * captured once before swapping in -- setEditorComponent's own swap logic reads getText() off
+ * the OUTGOING editor to carry a draft forward when restoring the previous one afterward; if
+ * this returned anything else, restoring would silently overwrite a real draft with an empty
+ * string. Implements EditorComponent directly rather than extending CustomEditor: CustomEditor's
+ * duck-typed actionHandlers Map would otherwise get every app-level action (model switching,
+ * clear, suspend) copied onto it by Pi's own editor-swap code, none of which this host uses or
+ * forwards -- avoiding the inheritance sidesteps that dead weight entirely.
+ */
+class DiscussEditorHost implements EditorComponent {
+	constructor(
+		private readonly ask: AskComponent,
+		private readonly preservedText: string,
+	) {}
+	getText(): string { return this.preservedText; }
+	setText(_text: string): void {}
+	render(width: number): string[] { return this.ask.render(width); }
+	handleInput(data: string): void { this.ask.handleInput(data); }
+	invalidate(): void { this.ask.invalidate(); }
+}
+
+async function askViaEditorSwap(
+	ctx: ExtensionContext,
+	params: AskQuestionParams,
+	options: AskOption[],
+	allowMultiple: boolean,
+	allowFreeform: boolean,
+	allowComment: boolean,
+	normalizedContext: string | undefined,
+	shortcuts: ResolvedAskShortcuts,
+): Promise<AskResponse | null> {
+	const previousFactory = ctx.ui.getEditorComponent();
+	const preservedText = ctx.ui.getEditorText();
+	// setEditorComponent's factory only receives an EditorTheme (borderColor + selectList) --
+	// nowhere near AskComponent's actual dependency on the full Theme surface (.fg(), .bold(),
+	// etc). ctx.ui.theme is the real, rich Theme; captured here rather than from the factory.
+	const theme = ctx.ui.theme;
+	return new Promise<AskResponse | null>((resolve) => {
+		let settled = false;
+		const finish = (result: AskResponse | null) => {
+			if (settled) return;
+			settled = true;
+			ctx.ui.setEditorComponent(previousFactory);
+			resolve(result);
+		};
+		if (params.signal) params.signal.addEventListener("abort", () => finish(null), { once: true });
+		if (params.timeout && params.timeout > 0) setTimeout(() => finish(null), params.timeout);
+		ctx.ui.setEditorComponent((tui: TUI, _editorTheme: EditorTheme, keybindings: KeybindingsManager) => {
+			const ask = new AskComponent(params.question, normalizedContext, params.subtitle, options, allowMultiple, allowFreeform, allowComment, "inline", tui, theme, keybindings, shortcuts, finish);
+			return new DiscussEditorHost(ask, preservedText);
+		});
+	});
+}
+
 async function askQuestionBlocking(
 	ctx: ExtensionContext,
 	params: AskQuestionParams,
@@ -1173,6 +1231,15 @@ async function askQuestionBlocking(
 		commentToggle: resolveShortcut(undefined, process.env["PAPYRUS_DISCUSS_COMMENT_TOGGLE_KEY"], DEFAULT_COMMENT_TOGGLE_KEY),
 	};
 
+	// "editor" hosts the picker in place of the real input editor (Pi's own slash-command menu's
+	// mechanism) instead of a floating overlay -- degrades to "inline" if setEditorComponent isn't
+	// available in this UI mode (interactive-only, like onTerminalInput below).
+	if (displayMode === "editor" && typeof ctx.ui.setEditorComponent === "function" && typeof ctx.ui.getEditorComponent === "function" && typeof ctx.ui.getEditorText === "function") {
+		const response = await askViaEditorSwap(ctx, params, options, allowMultiple, allowFreeform, allowComment, normalizedContext, shortcuts);
+		return response ? toAskAnswer(response) : undefined;
+	}
+	const effectiveDisplayMode: AskDisplayMode = displayMode === "editor" ? "inline" : displayMode;
+
 	let overlayHandle: OverlayHandle | undefined;
 	let removeOverlayInputListener: (() => void) | undefined;
 	let hasAnnouncedHide = false;
@@ -1181,7 +1248,7 @@ async function askQuestionBlocking(
 		const factory = (tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (result: AskResponse | null) => void) => {
 			if (params.signal) params.signal.addEventListener("abort", () => done(null), { once: true });
 			if (params.timeout && params.timeout > 0) setTimeout(() => done(null), params.timeout);
-			return new AskComponent(params.question, normalizedContext, params.subtitle, options, allowMultiple, allowFreeform, allowComment, displayMode, tui, theme, keybindings, shortcuts, done);
+			return new AskComponent(params.question, normalizedContext, params.subtitle, options, allowMultiple, allowFreeform, allowComment, effectiveDisplayMode, tui, theme, keybindings, shortcuts, done);
 		};
 
 		const overlayToggle = shortcuts.overlayToggle;
@@ -1195,7 +1262,7 @@ async function askQuestionBlocking(
 			});
 		}
 
-		const customResult = await ctx.ui.custom<AskResponse | null>(factory, buildCustomUIOptions(displayMode, (handle) => { overlayHandle = handle; }));
+		const customResult = await ctx.ui.custom<AskResponse | null>(factory, buildCustomUIOptions(effectiveDisplayMode, (handle) => { overlayHandle = handle; }));
 		response = customResult !== undefined ? customResult : await askViaDialogs(ctx.ui, params.question, normalizedContext, options, allowMultiple, allowFreeform, allowComment, params.timeout);
 	} finally {
 		removeOverlayInputListener?.();

package/extension/src/domain-tools.ts

@@ -710,7 +710,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "discuss",
 		label: "Discuss",
-		description: "Native Papyrus deliberation with a real lifecycle -- distinct from a one-shot ask: a Discussion persists, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. ACTIONS: open, reply, defer, resume, settle, block, unblock, show, rounds, list. open starts round 1 and optionally blocks_task_ids immediately. reply is refused once deferred or settled -- resume first. defer is explicitly non-blocking (paused, resumable); settle is terminal and archives the discussion. block/unblock manage the blocking relationship to a task independently of open. A task's completion is refused while any active Discussion blocks it. open/reply can pose a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several); reply answers a currently pending choice via selected, validated against it. Each option is either a bare string (fine for a self-evident choice like yes/no) or {title, description} -- add a description only when there's a genuine tradeoff, risk, or consequence worth conveying (a real pro/con), keep it to one line, and never pad it with something the title already says; skip descriptions entirely when the options don't need them. Pass live:true on open or reply to get the human's answer synchronously in this same call, via an interactive prompt (the pending choice's picker if one was posed, otherwise a freeform question) -- covers a completely open question with no artifact (open with no prior discussion) and a question tied to a specific existing artifact (reply, addressed by name) alike. Only takes effect with an interactive UI available; otherwise degrades silently to the normal async round. PREFER `name` (the discussion's exact title) over `id`, `task_name`/`blocks_task_names` over `task_id`/`blocks_task_ids` -- all are backend implementation details, resolved from name automatically.",
+		description: "Native Papyrus deliberation with a real lifecycle -- distinct from a one-shot ask: a Discussion persists, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. ACTIONS: open, reply, defer, resume, settle, block, unblock, show, rounds, list. open starts round 1 and optionally blocks_task_ids immediately. reply is refused once deferred or settled -- resume first. defer is explicitly non-blocking (paused, resumable); settle is terminal and archives the discussion. block/unblock manage the blocking relationship to a task independently of open. A task's completion is refused while any active Discussion blocks it. open/reply can pose a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several); reply answers a currently pending choice via selected, validated against it. Each option is either a bare string or {title, description}; description is optional for exactly 2 options (a self-evident yes/no) but REQUIRED and non-empty for every option once there are 3 or more -- rejected otherwise. One line: the real pro/con/risk/consequence, never padding that just restates the title. Pass live:true on open or reply to get the human's answer synchronously in this same call, via an interactive prompt (the pending choice's picker if one was posed, otherwise a freeform question) -- covers a completely open question with no artifact (open with no prior discussion) and a question tied to a specific existing artifact (reply, addressed by name) alike. Only takes effect with an interactive UI available; otherwise degrades silently to the normal async round. PREFER `name` (the discussion's exact title) over `id`, `task_name`/`blocks_task_names` over `task_id`/`blocks_task_ids` -- all are backend implementation details, resolved from name automatically.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),

package/package.json

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

package/src/constants.ts

@@ -179,6 +179,8 @@ export const DISCUSSION_OPTION_MAX_LENGTH = 200;
 // description is meant to be a one-line tradeoff/consequence, not a restatement of the whole
 // question. Long enough for a real pro/con, short enough to force conciseness.
 export const DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH = 240;
+// Below this, a binary yes/no choice is often self-evident and a description would just pad it.
+export const DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT = 3;
 /** Bounds for the generic graph projection protocol (external bounded contexts). */
 export const GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH = 500;
 export const GRAPH_PROJECTION_MAX_EDGES_PER_BATCH = 1_000;

package/src/domain/discussion.ts

@@ -21,6 +21,7 @@ import {
 	DISCUSSION_ACTOR_MAX_LENGTH,
 	DISCUSSION_DEFER_REASON_MAX_CHARACTERS,
 	DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH,
+	DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT,
 	DISCUSSION_OPTION_MAX_LENGTH,
 	DISCUSSION_OPTIONS_MAX_COUNT,
 	DISCUSSION_OPTIONS_MIN_COUNT,
@@ -109,7 +110,9 @@ export function validateSettlement(settlement: string): string {
 	return boundedString(settlement, "settlement", DISCUSSION_SETTLEMENT_MAX_CHARACTERS);
 }
 
-/** Validates a freshly-posed choice: 2..DISCUSSION_OPTIONS_MAX_COUNT unique, bounded-length options, a real mode, and -- if given -- one description per option (empty string means "none for this one"). */
+/** Validates a freshly-posed choice: 2..DISCUSSION_OPTIONS_MAX_COUNT unique, bounded-length
+ * options, a real mode, and a non-empty description for every option once
+ * DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT or more are posed. */
 export function validateDiscussionOptions(options: string[], mode: string, optionDescriptions?: string[]): { options: string[]; mode: DiscussionOptionsMode; optionDescriptions?: string[] } {
 	if (!(DISCUSSION_OPTIONS_MODES as readonly string[]).includes(mode)) {
 		throw new Error(`options_mode must be one of ${DISCUSSION_OPTIONS_MODES.join(", ")}`);
@@ -119,6 +122,10 @@ export function validateDiscussionOptions(options: string[], mode: string, optio
 	}
 	for (const option of options) boundedString(option, "option", DISCUSSION_OPTION_MAX_LENGTH);
 	if (new Set(options).size !== options.length) throw new Error("options must not repeat an entry");
+	const descriptionsRequired = options.length >= DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT;
+	if (descriptionsRequired && (optionDescriptions === undefined || optionDescriptions.some((description) => description.trim().length === 0))) {
+		throw new Error(`option_descriptions is required, with a non-empty entry for every option, once ${DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT} or more options are posed`);
+	}
 	if (optionDescriptions !== undefined) {
 		if (optionDescriptions.length !== options.length) throw new Error("option_descriptions must have exactly one entry per option (use an empty string for none)");
 		for (const description of optionDescriptions) {