@danypops/papyrus 0.28.2 → 0.29.0

package/extension/src/domain-tools.ts

@@ -9,7 +9,7 @@ import type { TaskCompletion, TaskGraph } from "../../src/task-service.ts";
 import type { SkillWorkflowRunResult } from "../../src/skill-execution.ts";
 import type { DiscussionAndRounds } from "../../src/discussion-service.ts";
 import { readDiscussionExtra, type DiscussionRound } from "../../src/domain/discussion.ts";
-import { askQuestion } from "./discuss-ask-view.ts";
+import { askQuestion, type AskDisplayMode } from "./discuss-ask-view.ts";
 import type { OperationName } from "../../src/service.ts";
 import { emitTaskFocusEvent } from "./task-focus-events.ts";
 import { sessionSecretField } from "./session-identity.ts";
@@ -68,7 +68,11 @@ function normalizeDiscussOptions(params: Record<string, unknown>): void {
 	if (anyDescription) params.option_descriptions = descriptions;
 }
 
-async function liveAnswer(ctx: ExtensionContext, discussion: Artifact, latestContent: string | undefined, onUpdate: AgentToolUpdateCallback | undefined, signal: AbortSignal | undefined): Promise<{ content: string; selected?: string[] } | undefined> {
+function parseDisplayMode(value: unknown): AskDisplayMode | undefined {
+	return value === "overlay" || value === "inline" || value === "editor" ? value : undefined;
+}
+
+async function liveAnswer(ctx: ExtensionContext, discussion: Artifact, latestContent: string | undefined, onUpdate: AgentToolUpdateCallback | undefined, signal: AbortSignal | undefined, displayMode: AskDisplayMode | undefined): Promise<{ content: string; selected?: string[] } | undefined> {
 	if (!ctx.hasUI) return undefined;
 	const pending = (() => { try { return readDiscussionExtra(discussion.extra); } catch { return undefined; } })();
 	// The just-recorded round's own content IS the real question -- a generic "Reply to <title>:"
@@ -85,9 +89,10 @@ async function liveAnswer(ctx: ExtensionContext, discussion: Artifact, latestCon
 			allowMultiple: pending.pendingOptionsMode === "multi",
 			onUpdate,
 			signal,
+			displayMode,
 		});
 	}
-	return askQuestion(ctx, { question, subtitle, onUpdate, signal });
+	return askQuestion(ctx, { question, subtitle, onUpdate, signal, displayMode });
 }
 
 /**
@@ -710,7 +715,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 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.",
+		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. display_mode picks how the live picker renders: 'overlay' (default, a floating dialog), 'inline' (renders in the normal transcript flow, no floating), or 'editor' (hosted in place of the input box itself, like a slash-command menu; falls back to 'inline' if unsupported in the current UI mode). 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()),
@@ -733,6 +738,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			options_mode: Type.Optional(Type.String()),
 			selected: Type.Optional(Type.Array(Type.String())),
 			live: Type.Optional(Type.Boolean()),
+			display_mode: Type.Optional(Type.String()),
 		}),
 		// Blocks other tool calls in the same assistant turn until live:true's human answer comes
 		// back, same reasoning as pi-ask-user's own tool: the model must not batch a live ask with
@@ -758,7 +764,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 						? text(`Opened discussion ${artifactLine(result.discussion)}`, createArtifactDetails("discuss.open", result.discussion))
 						: text(`Round ${result.rounds[0]?.roundNumber} added to "${result.discussion.title}"`, createArtifactDetails("discuss.reply", result.discussion));
 					if (params.live !== true) return fallback;
-					const answer = await liveAnswer(ctx, result.discussion, result.rounds[0]?.content, onUpdate, signal);
+					const answer = await liveAnswer(ctx, result.discussion, result.rounds[0]?.content, onUpdate, signal, parseDisplayMode(rawParams.display_mode));
 					if (!answer) return fallback;
 					const answered = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.reply", {
 						id: result.discussion.id, actor: "human", content: answer.content, ...(answer.selected ? { selected: answer.selected } : {}), source: "discuss-live",

package/extension/src/playbook-bridge.ts

@@ -1,90 +1,80 @@
 /**
- * playbook-bridge.ts — materializes active Papyrus Playbooks as real SKILL.md files so they
- * show up in Pi's own native skill catalog and become /skill:name-invocable, through Pi's
- * unmodified, documented resources_discover mechanism (no Pi source touched).
+ * playbook-bridge.ts — materializes active Papyrus Playbooks as their own /playbook:name slash
+ * commands, one per playbook, the same one-entry-per-item autocomplete experience Pi's own
+ * /skill:name gives real skills.
  *
- * Playbooks live in SQLite, not on disk, so they can't satisfy Pi's skill-loading pipeline
- * directly (Skill.filePath is required there). This bridges the gap the other direction:
- * on every resources_discover (session start and /reload), wipe and rebuild a cache directory
- * from the current playbooks.list, so a disabled/removed/renamed Playbook's stale file is never
- * served. Any failure degrades to "no extra skills this cycle" -- a Papyrus daemon hiccup must
- * never break Pi's own resource discovery.
+ * /skill:name itself is a hardcoded core mechanism (Pi's interactive mode builds it directly
+ * from its own skill loader) -- not something an extension can retarget to a different prefix.
+ * pi.registerCommand(name, ...) accepts any string, colons included, so "playbook:<slug>"
+ * registers and invokes as literally /playbook:<slug> -- a real, supported extension API, no
+ * core touched.
+ *
+ * Real limitation: ExtensionAPI has no unregisterCommand. A disabled or renamed playbook's old
+ * /playbook:<slug> command lingers until a full Pi restart -- registerCommand can only add or
+ * overwrite, never remove. Mitigated two ways: registrations refresh on every resources_discover
+ * (session start and /reload), so a renamed playbook's NEW slug appears promptly even though the
+ * old one lingers; and each command's handler re-fetches the live playbook by id at invocation
+ * time rather than baking in stale content, so even a lingering stale name fails cleanly with a
+ * real error instead of running deleted content.
  */
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { callService } from "./service-client.ts";
 
 const PLAYBOOK_BRIDGE_MAX_PLAYBOOKS = 100;
-const PLAYBOOK_BRIDGE_DESCRIPTION_MAX_CHARACTERS = 1000;
 
 function slugify(title: string): string {
 	const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
 	return slug.length > 0 ? slug : "playbook";
 }
 
-function playbookCacheDir(): string {
-	const base = process.env["XDG_CACHE_HOME"] ?? join(homedir(), ".cache");
-	return join(base, "papyrus", "playbooks");
-}
-
-function stringList(value: unknown): string[] {
-	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+async function activePlaybooks(): Promise<Artifact[]> {
+	return callService<Record<string, unknown>, Artifact[]>("playbooks.list", { status: "active", limit: PLAYBOOK_BRIDGE_MAX_PLAYBOOKS });
 }
 
-function playbookSkillMarkdown(playbook: Artifact): string {
-	const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
-	const steps = stringList(playbook.extra["steps"]);
-	const tools = stringList(playbook.extra["tools"]);
-	const description = trigger.replace(/\n/g, " ").slice(0, PLAYBOOK_BRIDGE_DESCRIPTION_MAX_CHARACTERS);
-	return [
-		"---",
-		`name: ${slugify(playbook.title)}`,
-		`description: ${description}`,
-		"---",
-		"",
-		`# ${playbook.title}`,
-		"",
-		`Materialized from a live Papyrus playbook; edits here are lost on the next refresh. Edit the playbook itself instead (the playbooks tool, action=update), then /reload.`,
-		"",
-		`Trigger: ${trigger}`,
-		"",
-		...(playbook.body ? [`Context: ${playbook.body}`, ""] : []),
-		...(steps.length > 0 ? ["## Steps", "", ...steps.map((step, index) => `${index + 1}. ${step}`), ""] : []),
-		...(tools.length > 0 ? [`Tools: ${tools.join(", ")}`, ""] : []),
-	].join("\n");
+/** Exported for direct testing without a real ExtensionAPI. */
+export function playbookCommandName(title: string): string {
+	return `playbook:${slugify(title)}`;
 }
 
-/** Exported for direct testing without a real ExtensionAPI. */
-export async function materializePlaybookSkillPaths(): Promise<string[]> {
-	const dir = playbookCacheDir();
-	if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
-	const playbooks = await callService<Record<string, unknown>, Artifact[]>("playbooks.list", { status: "active", limit: PLAYBOOK_BRIDGE_MAX_PLAYBOOKS });
-	if (playbooks.length === 0) return [];
-	mkdirSync(dir, { recursive: true });
-	const usedSlugs = new Set<string>();
-	const paths: string[] = [];
-	for (const playbook of playbooks) {
-		let slug = slugify(playbook.title);
-		if (usedSlugs.has(slug)) slug = `${slug}-${playbook.id.slice(0, 8)}`; // a real title collision, not the common case
-		usedSlugs.add(slug);
-		const skillDir = join(dir, slug);
-		mkdirSync(skillDir, { recursive: true });
-		const filePath = join(skillDir, "SKILL.md");
-		writeFileSync(filePath, playbookSkillMarkdown(playbook), "utf8");
-		paths.push(filePath);
-	}
-	return paths;
+/** Exported for direct testing without a real ExtensionAPI: what would be registered right now. */
+export async function planPlaybookCommandRegistrations(): Promise<Array<{ name: string; id: string; title: string; trigger: string }>> {
+	const playbooks = await activePlaybooks();
+	const usedNames = new Set<string>();
+	return playbooks.map((playbook) => {
+		let name = playbookCommandName(playbook.title);
+		if (usedNames.has(name)) name = `${name}-${playbook.id.slice(0, 8)}`; // a real title collision, not the common case
+		usedNames.add(name);
+		const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
+		return { name, id: playbook.id, title: playbook.title, trigger };
+	});
 }
 
 export function registerPlaybookBridge(pi: ExtensionAPI): void {
-	pi.on("resources_discover", async () => {
+	const refresh = async () => {
 		try {
-			return { skillPaths: await materializePlaybookSkillPaths() };
+			const registrations = await planPlaybookCommandRegistrations();
+			for (const { name, id, title, trigger } of registrations) {
+				pi.registerCommand(name, {
+					description: trigger,
+					handler: async (_args, ctx) => {
+						try {
+							// Re-fetched live, not captured at registration time: a lingering stale
+							// command (renamed or disabled since, since registerCommand can't be
+							// unregistered) must fail cleanly, never run deleted/stale content.
+							const invocation = await callService<Record<string, unknown>, string>("playbooks.invoke", { id });
+							ctx.ui.setEditorText(invocation);
+							ctx.ui.notify(`"${title}" invocation placed in the editor`, "info");
+						} catch (error) {
+							ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+						}
+					},
+				});
+			}
 		} catch {
-			return {};
+			// A Papyrus daemon hiccup must never break Pi's own resource discovery -- degrades to
+			// "no new/updated playbook commands this cycle", not a broken session start.
 		}
-	});
+	};
+	pi.on("resources_discover", async () => { await refresh(); return {}; });
 }

package/package.json

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