@danypops/papyrus 0.28.3 → 0.29.1

package/extension/src/context-injection-telemetry.ts

@@ -5,6 +5,7 @@ import {
 } from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { ruleInjectionPreview } from "./rules.ts";
+import { playbookInjectionPreview } from "./playbook-bridge.ts";
 
 export interface ContextPayloadSize {
 	characters: number;
@@ -18,6 +19,7 @@ export interface PapyrusContextInjectionObservation {
 	producerId: string;
 	before: ContextPayloadSize;
 	rules: ContextPayloadSize & { count: number };
+	playbooks: ContextPayloadSize & { count: number };
 	tasks: ContextPayloadSize;
 	injected: ContextPayloadSize;
 	after: ContextPayloadSize;
@@ -30,6 +32,7 @@ export interface PapyrusContextInjectionObservation {
 export interface BuildContextInjectionInput {
 	basePrompt: string;
 	rules: Array<Pick<Artifact, "title" | "body" | "extra">>;
+	playbooks: Array<Pick<Artifact, "title" | "extra">>;
 	taskSummary: string | null;
 	observedAt: number;
 	sequence: number;
@@ -46,13 +49,16 @@ function size(value: string): ContextPayloadSize {
 export function buildContextInjection(input: BuildContextInjectionInput): {
 	prompt: string;
 	ruleBlock: string;
+	playbookBlock: string;
 	taskBlock: string;
 	observation: PapyrusContextInjectionObservation;
 } {
 	const ruleContent = input.rules.map(ruleInjectionPreview).join("\n");
 	const ruleBlock = ruleContent ? `\n\n## Active rules (Papyrus)\n\n${ruleContent}\n` : "";
+	const playbookContent = input.playbooks.map(playbookInjectionPreview).join("\n");
+	const playbookBlock = playbookContent ? `\n\n## Available playbooks (Papyrus)\n\n${playbookContent}\n` : "";
 	const taskBlock = input.taskSummary ? `\n\n## Open tasks (Papyrus)\n\n${input.taskSummary}\n` : "";
-	const injected = `${ruleBlock}${taskBlock}`;
+	const injected = `${ruleBlock}${playbookBlock}${taskBlock}`;
 	const prompt = `${input.basePrompt}${injected}`;
 	const fingerprint = createHash("sha256").update(injected).digest("hex");
 	const injectedSize = size(injected);
@@ -60,6 +66,7 @@ export function buildContextInjection(input: BuildContextInjectionInput): {
 	return {
 		prompt,
 		ruleBlock,
+		playbookBlock,
 		taskBlock,
 		observation: {
 			schema: PAPYRUS_CONTEXT_INJECTION_SCHEMA,
@@ -68,6 +75,7 @@ export function buildContextInjection(input: BuildContextInjectionInput): {
 			producerId: input.producerId,
 			before: size(input.basePrompt),
 			rules: { ...size(ruleBlock), count: input.rules.length },
+			playbooks: { ...size(playbookBlock), count: input.playbooks.length },
 			tasks: size(taskBlock),
 			injected: injectedSize,
 			after: afterSize,

package/extension/src/index.ts

@@ -23,7 +23,7 @@ import { formatMetadata } from "./artifact-format.ts";
 import { callService } from "./service-client.ts";
 import { registerDomainTools } from "./domain-tools.ts";
 import { isLiveAskPending } from "./discuss-ask-view.ts";
-import { registerPlaybookBridge } from "./playbook-bridge.ts";
+import { PLAYBOOK_BRIDGE_MAX_PLAYBOOKS, registerPlaybookBridge } from "./playbook-bridge.ts";
 import type { TaskGraph, TaskStatus } from "../../src/task-service.ts";
 import { ActiveTaskContinuation, automaticPauseReason, shouldResumeFocusOnHumanInput, type ActiveTaskMarker } from "./active-task-continuation.ts";
 import { buildTaskWidgetProjection, type TaskWidgetProjection } from "./task-widget.ts";
@@ -626,13 +626,15 @@ export default async function (pi: ExtensionAPI) {
 	pi.on("before_agent_start", async (event, ctx) => {
 		try {
 			const sessionId = ctx.sessionManager.getSessionId();
-			const [rules, summary] = await Promise.all([
+			const [rules, playbooks, summary] = await Promise.all([
 				callService<Record<string, unknown>, Array<Pick<Artifact, "title" | "body" | "extra">>>("rules.injectable", { project_root: ctx.cwd, session_id: sessionId }),
+				callService<Record<string, unknown>, Array<Pick<Artifact, "title" | "extra">>>("playbooks.list", { status: "active", limit: PLAYBOOK_BRIDGE_MAX_PLAYBOOKS }),
 				callService<Record<string, unknown>, string | null>("tasks.context", { project_root: ctx.cwd, session_id: sessionId }),
 			]);
 			const injection = buildContextInjection({
 				basePrompt: event.systemPrompt ?? "",
 				rules,
+				playbooks,
 				taskSummary: summary,
 				observedAt: Date.now(),
 				sequence: ++contextInjectionSequence,

package/extension/src/playbook-bridge.ts

@@ -1,90 +1,91 @@
 /**
- * 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;
+export const PLAYBOOK_BRIDGE_MAX_PLAYBOOKS = 100;
 
 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");
+async function activePlaybooks(): Promise<Artifact[]> {
+	return callService<Record<string, unknown>, Artifact[]>("playbooks.list", { status: "active", limit: PLAYBOOK_BRIDGE_MAX_PLAYBOOKS });
 }
 
-function stringList(value: unknown): string[] {
-	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+/** Exported for direct testing without a real ExtensionAPI. */
+export function playbookCommandName(title: string): string {
+	return `playbook:${slugify(title)}`;
 }
 
-function playbookSkillMarkdown(playbook: Artifact): string {
+/**
+ * One line per active Playbook for context injection -- the passive, every-turn surfacing that
+ * gives the model the same "this exists and might match my task" awareness Pi's own Skill catalog
+ * gives real Skills, without a file-based bridge. See buildContextInjection (rules and open tasks
+ * already work this way).
+ */
+export function playbookInjectionPreview(playbook: Pick<Artifact, "title" | "extra">): 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");
+	return `• ${playbook.title} (when: ${trigger})`;
 }
 
-/** 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.3",
+  "version": "0.29.1",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],