@danypops/pi-papyrus 0.35.1 → 0.36.0

package/README.md

@@ -17,7 +17,7 @@ Agent-facing domain tools own lifecycle invariants and sit above this store API:
 - **`docs`** — create/update/list/show, activate/archive/reopen, and document-safe graph links; Note mutations remain behind the Notes facade
 - **`rules`** — create/update/list/show/preview, enable/disable, and attach governance gates to tasks
 - **`skills`** — create/update/list/show/invoke/run, enable/disable, create compatibility templates, and atomically instantiate parameterized workflow runs
-- **`playbooks`** — a completely different beast from Skills, not a subtype: a trigger and an ordered list of steps an agent reads and follows, never mechanically instantiated and never composed the way Skills call other Skills. create/update/list/show/invoke, enable/disable. A Playbook can declare named arguments (`{name, description?, required?}`, required defaults true); invoking with some unsupplied lists exactly which required ones are still missing and directs the agent to ask via `discuss` with `live:true` rather than guess
+- **`playbooks`** — a completely different beast from Skills at the authoring level (a trigger and an ordered list of steps, written as prose), but `invoke` recycles the same materialization engine workflow Skills use: it compiles the steps and any `contain`/`depend` composition into real Tasks (one per step, plus a container task per playbook in the tree), wires them with `dependsOn` so completing one auto-focuses the next, and focuses the first one. No text dump — one step surfaces at a time, as it becomes the focused task, same as any other Task. `contain`/`uncontain` nest a child Playbook inside a parent (its steps run after the parent's own, as part of it); `depend`/`undepend` chain a prerequisite Playbook before another (it must fully complete first). `preview` renders the whole tree as text with no side effects, for reading before invoking. A Playbook can declare named arguments (`{name, description?, required?}`, required defaults true; referenced in step text as `{{name}}`); invoking with a required one unsupplied creates nothing and reports exactly which are still missing, directing the agent to ask via `discuss` with `live:true` rather than guess
 
 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.
 

package/extension/src/domain-tools.ts

@@ -10,7 +10,7 @@ import {
 	type GateResult,
 	type NoteHistoryPage,
 	type OperationName,
-	type SkillWorkflowRunResult,
+	type WorkflowRunResult,
 	type TaskCompletion,
 	type TaskExecutionPlan,
 	type TaskGraph,
@@ -656,7 +656,7 @@ export function registerPlaybooksTool(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "playbooks",
 		label: "Playbooks",
-		description: "Playbook domain tool -- a completely different beast from the skills tool, not a subtype of it. A Playbook is a trigger and an ordered list of steps an agent reads and follows; it is never mechanically instantiated the way a Skill's artifact-template or workflow blueprint is, and it never composes other Playbooks. ACTIONS: create, list, show, invoke, enable, disable, assign_project, update, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. On create, `arguments` declares named inputs the Playbook needs: [{name, description?, required?}] (required defaults true). On invoke, `arguments` supplies known values as {name: value}; invoke renders which declared REQUIRED arguments are still missing and directs you to ask the human for them via the discuss tool with live:true -- never guess or invent a value for a missing required argument. update changes title/body/labels (at least one required) and is refused for a read-only external projection. remove moves a Playbook to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the playbook's exact title) over `id` -- id is a backend implementation detail, resolved from name automatically.",
+		description: "Playbook domain tool -- a completely different beast from the skills tool at the AUTHORING level (a Playbook is prose: a trigger and an ordered list of steps), but invoke recycles the exact same materialization engine workflow Skills use: it compiles the Playbook's steps and its contains/depends_on composition tree into real Tasks (one per step, plus one container task per playbook in the tree), wires them with dependsOn so completing one auto-focuses the next, and focuses the first one -- no text dump, one step (page) surfaces at a time as it becomes the focused task, exactly like any other Task. contain/uncontain nest a child Playbook inside a parent (its steps run AFTER the parent's own, as part of it); depend/undepend chain a prerequisite Playbook before another (it must fully complete FIRST). Both are bounded; a composition cycle is a hard invoke-time error (real Tasks would otherwise be created in a loop), unlike preview's degrade-to-a-marker. ACTIONS: create, list, show, invoke, preview, enable, disable, assign_project, update, contain, uncontain, depend, undepend, remove, restore. project_root is optional everywhere (omitted = unscoped). On create, `arguments` declares named inputs the Playbook needs: [{name, description?, required?}] (required defaults true) -- referenced in step text as `{{name}}`, substituted at invoke time. On invoke, `arguments` supplies known values as {name: value}; if any declared REQUIRED argument is still missing, invoke creates nothing and returns `missingArguments` -- ask the human for these (discuss tool, live:true) and invoke again, never guess or invent a value. A successful invoke returns `entryTaskId` (now focused) and `created.tasks` -- drive it forward with the tasks tool (start/submit/complete) like any other Task; contains/depends_on wiring auto-focuses each next step on completion. preview renders the whole tree as text with no side effects, for a human who just wants to read it first. update changes title/body/labels (at least one required) and is refused for a read-only external projection. remove moves a Playbook to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the playbook's exact title) over `id`, and `parent_name`/`child_name`/`dependency_name` over `parent_id`/`child_id`/`dependency_id` for contain/uncontain/depend/undepend -- all are backend implementation details, resolved from name automatically.",
 		parameters: Type.Object({
 			action: Type.String(), id: Type.Optional(Type.String()), name: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
 			body: Type.Optional(Type.String()), trigger: Type.Optional(Type.String()), steps: Type.Optional(Type.Array(Type.String())),
@@ -664,6 +664,9 @@ export function registerPlaybooksTool(pi: ExtensionAPI): void {
 			arguments: Type.Optional(Type.Unknown()),
 			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())), status: Type.Optional(Type.String()),
 			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()),
+			parent_id: Type.Optional(Type.String()), parent_name: Type.Optional(Type.String()),
+			child_id: Type.Optional(Type.String()), child_name: Type.Optional(Type.String()),
+			dependency_id: Type.Optional(Type.String()), dependency_name: Type.Optional(Type.String()),
 			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Playbooks", args, theme); },
@@ -672,10 +675,14 @@ export function registerPlaybooksTool(pi: ExtensionAPI): void {
 			try {
 				const params: Record<string, unknown> = { ...rawParams };
 				const action = params.action;
+				const resolutionRequest = { project_root: params.project_root };
 				await resolveNameFields(params, [
-					{ nameKey: "name", idKey: "id", listOperation: "playbooks.list", baseRequest: { project_root: params.project_root } },
+					{ nameKey: "name", idKey: "id", listOperation: "playbooks.list", baseRequest: resolutionRequest },
+					{ nameKey: "parent_name", idKey: "parent_id", listOperation: "playbooks.list", baseRequest: resolutionRequest },
+					{ nameKey: "child_name", idKey: "child_id", listOperation: "playbooks.list", baseRequest: resolutionRequest },
+					{ nameKey: "dependency_name", idKey: "dependency_id", listOperation: "playbooks.list", baseRequest: resolutionRequest },
 				]);
-				if (action === "create" || action === "invoke") normalizeJsonEncodedField(params, "arguments");
+				if (action === "create" || action === "invoke" || action === "preview") normalizeJsonEncodedField(params, "arguments");
 				if (action === "create") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("playbooks.create", params);
 					return text(`Created playbook ${artifactLine(artifact)}`, createArtifactDetails("playbooks.create", artifact));
@@ -684,13 +691,25 @@ export function registerPlaybooksTool(pi: ExtensionAPI): void {
 					const rows = await callService<Record<string, unknown>, Artifact[]>("playbooks.list", params);
 					return text(rows.length ? artifactLines(rows).join("\n") : "No playbooks found.", createArtifactListDetails("playbooks.list", rows));
 				}
+				if (action === "preview") {
+					const rendered = await callService<Record<string, unknown>, string>("playbooks.preview", params);
+					return text(rendered, createPreviewDetails("playbooks.preview", "Playbook preview", rendered));
+				}
 				if (action === "invoke") {
-					const invocation = await callService<Record<string, unknown>, string>("playbooks.invoke", params);
-					return text(invocation, createPreviewDetails("playbooks.invoke", "Playbook invocation", invocation));
+					const invocation = await callService<Record<string, unknown>, { entryTaskId?: string; rootTaskIds?: string[]; created?: { tasks: string[] }; missingArguments?: string[] }>("playbooks.invoke", params);
+					if (invocation.missingArguments) {
+						const message = `Missing required argument(s): ${invocation.missingArguments.join(", ")}. Nothing was created -- ask the human for these (discuss tool, live:true), then invoke again.`;
+						return text(message, createPreviewDetails("playbooks.invoke", "Playbook invocation", message));
+					}
+					const message = `Invoked: ${invocation.created?.tasks.length ?? 0} task(s) created, entry task ${invocation.entryTaskId} now focused. Drive it forward with the tasks tool (start/submit/complete) -- contains/depends_on wiring auto-focuses each next step.`;
+					return text(message, createPreviewDetails("playbooks.invoke", "Playbook invocation", JSON.stringify(invocation, null, 2)));
 				}
 				const trashResult = await handleArtifactRemoveRestore(action, params);
 				if (trashResult) return trashResult;
-				const operations = { show: "playbooks.show", enable: "playbooks.enable", disable: "playbooks.disable", assign_project: "playbooks.assign_project", update: "playbooks.update" } as const;
+				const operations = {
+					show: "playbooks.show", enable: "playbooks.enable", disable: "playbooks.disable", assign_project: "playbooks.assign_project", update: "playbooks.update",
+					contain: "playbooks.contain", uncontain: "playbooks.uncontain", depend: "playbooks.depend", undepend: "playbooks.undepend",
+				} as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown playbooks action: ${action}`);
 				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
@@ -745,7 +764,7 @@ export function registerSkillsTool(pi: ExtensionAPI): void {
 					return text(invocation, createPreviewDetails("skills.invoke", "Skill invocation", invocation));
 				}
 				if (action === "run") {
-					const run = await callService<Record<string, unknown>, SkillWorkflowRunResult>("skills.run", request);
+					const run = await callService<Record<string, unknown>, WorkflowRunResult>("skills.run", request);
 					const runTitleCounts = new Map<string, number>();
 					for (const node of run.execution.nodes) runTitleCounts.set(node.title, (runTitleCounts.get(node.title) ?? 0) + 1);
 					const execution = run.execution.nodes.map((node) => (runTitleCounts.get(node.title) ?? 0) > 1

package/extension/src/index.ts

@@ -25,7 +25,8 @@ import {
 	type TaskStatus,
 } from "@danypops/papyrus";
 import { formatMetadata } from "./artifact-format.ts";
-import { callService } from "./service-client.ts";
+import { callService, subscribeTaskPushChannel } from "./service-client.ts";
+import type { PushChannelClient } from "@danypops/daemon-kit/pi-client";
 import { registerDomainTools, resolveNameFields } from "./domain-tools.ts";
 import { BoundedPoll } from "./bounded-poll.ts";
 import { renderNoteWidgetLines } from "./note-widget.ts";
@@ -109,6 +110,7 @@ export class TaskOverlay {
 	private projectRoot: string | undefined;
 	private sessionId: string | undefined;
 	private readonly poll = new BoundedPoll();
+	private pushChannel: PushChannelClient | undefined;
 
 	setUI(ctx: ExtensionUIContext): void {
 		if (ctx !== this.uiCtx) {
@@ -141,6 +143,19 @@ export class TaskOverlay {
 		} catch {
 			// A rendering bug must not crash the extension host over a best-effort status widget.
 		}
+		this.ensurePushChannel();
+	}
+
+	/**
+	 * Lazily (re)establishes the push subscription -- a no-op once already connected.
+	 * Retried on every poll-driven refresh() call rather than once at startup: the
+	 * daemon may not have been running yet when this session started (subscribeTaskPushChannel
+	 * returns undefined with no token/port on disk), and this piggybacks on the existing
+	 * poll cadence as the natural retry point instead of a second timer.
+	 */
+	private ensurePushChannel(): void {
+		if (this.pushChannel && this.pushChannel.state() !== "closed") return;
+		this.pushChannel = subscribeTaskPushChannel(() => { void this.refresh(); });
 	}
 
 	private render(): void {
@@ -196,6 +211,8 @@ export class TaskOverlay {
 
 	dispose(): void {
 		this.stopPolling();
+		this.pushChannel?.close();
+		this.pushChannel = undefined;
 		this.uiCtx?.setWidget(WIDGET_KEY, undefined);
 		this.registered = false;
 		this.tui = undefined;

package/extension/src/playbook-bridge.ts

@@ -73,9 +73,17 @@ export function registerPlaybookBridge(pi: ExtensionAPI): void {
 							// 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");
+							// invoke materializes real Tasks and focuses the entry one -- it no longer
+							// returns rendered text to drop into the editor (that's playbooks.preview
+							// now). The editor gets a short kickoff prompt instead; the actual step
+							// content surfaces via the normal Task Focus system-prompt pointer.
+							const invocation = await callService<Record<string, unknown>, { entryTaskId?: string; missingArguments?: string[] }>("playbooks.invoke", { id });
+							if (invocation.missingArguments) {
+								ctx.ui.notify(`"${title}" needs: ${invocation.missingArguments.join(", ")}`, "error");
+								return;
+							}
+							ctx.ui.setEditorText(`Run the "${title}" playbook -- work on the currently focused task.`);
+							ctx.ui.notify(`"${title}" invoked: entry task ${invocation.entryTaskId} focused`, "info");
 						} catch (error) {
 							ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
 						}

package/extension/src/playbooks.ts

@@ -26,14 +26,28 @@ export async function playbookArgumentCompletions(argumentPrefix: string): Promi
 	}
 }
 
-/** `/playbook <name>` (no args opens the full browser instead): resolves by exact title, then places its invocation directly in the editor -- one step, not browse-then-select-then-invoke. */
+interface PlaybookInvocationResponse {
+	entryTaskId?: string;
+	missingArguments?: string[];
+}
+
+/** Shared by /playbook <name> and the browser's own "Invoke" action: materializes real Tasks and focuses the entry one, then reports it -- invoke no longer returns rendered text (that's playbooks.preview now). */
+async function invokeAndReport(id: string, label: string, ctx: ExtensionCommandContext): Promise<void> {
+	const invocation = await callService<Record<string, unknown>, PlaybookInvocationResponse>("playbooks.invoke", { id });
+	if (invocation.missingArguments) {
+		ctx.ui.notify(`"${label}" needs: ${invocation.missingArguments.join(", ")}`, "error");
+		return;
+	}
+	ctx.ui.setEditorText(`Run the "${label}" playbook -- work on the currently focused task.`);
+	ctx.ui.notify(`"${label}" invoked: entry task ${invocation.entryTaskId} focused`, "info");
+}
+
+/** `/playbook <name>` (no args opens the full browser instead): resolves by exact title, then invokes it directly -- one step, not browse-then-select-then-invoke. */
 export async function openPlaybookByName(name: string, ctx: ExtensionCommandContext): Promise<void> {
 	if (!name.trim()) { await showPlaybooks(ctx); return; }
 	try {
 		const id = matchArtifactByName(await activePlaybooks(), name);
-		const invocation = await callService<Record<string, unknown>, string>("playbooks.invoke", { id });
-		ctx.ui.setEditorText(invocation);
-		ctx.ui.notify(`"${name.trim()}" invocation placed in the editor`, "info");
+		await invokeAndReport(id, name.trim(), ctx);
 	} catch (error) {
 		ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
 	}
@@ -75,9 +89,7 @@ export async function showPlaybooks(ctx: ExtensionCommandContext): Promise<void>
 				return;
 			}
 			if (choice === "Invoke") {
-				const invocation = await callService<Record<string, unknown>, string>("playbooks.invoke", { id: playbook.id });
-				commandCtx.ui.setEditorText(invocation);
-				commandCtx.ui.notify("Invocation placed in the editor", "info");
+				await invokeAndReport(playbook.id, playbook.title, commandCtx);
 				return;
 			}
 			if (choice === "Link artifact") {

package/extension/src/service-client.ts

@@ -1,5 +1,5 @@
-import { createRetryingClient, type RetryingClient } from "@danypops/daemon-kit/pi-client";
-import { connectPapyrusClient, type OperationName, type PapyrusClient } from "@danypops/papyrus";
+import { connectPushChannel, createRetryingClient, type PushChannelClient, type PushChannelState, type RetryingClient } from "@danypops/daemon-kit/pi-client";
+import { connectPapyrusClient, resolvePushChannelTarget, type OperationName, type PapyrusClient } from "@danypops/papyrus";
 
 type ClientConnector = () => Promise<PapyrusClient>;
 
@@ -26,3 +26,40 @@ export function resetPapyrusClientForTests(): void {
 	connector = () => connectPapyrusClient();
 	client.reset();
 }
+
+let pushChannelTargetResolver: typeof resolvePushChannelTarget = resolvePushChannelTarget;
+
+export function setPushChannelTargetResolverForTests(value: typeof resolvePushChannelTarget): void {
+	pushChannelTargetResolver = value;
+}
+
+export function resetPushChannelTargetResolverForTests(): void {
+	pushChannelTargetResolver = resolvePushChannelTarget;
+}
+
+/**
+ * Subscribes to the daemon's "tasks" push topic so a widget can refresh the moment
+ * a mutation happens, instead of waiting for its next poll tick. Returns undefined
+ * (no-op) rather than throwing when the daemon has never started -- no token/port
+ * on disk yet -- matching how the widget's own fetch-based refresh() already
+ * tolerates "daemon not running" and falls back to its existing poll. A caller
+ * should retry this on a later poll tick once the daemon is confirmed reachable.
+ */
+export function subscribeTaskPushChannel(onMessage: () => void, onStateChange?: (state: PushChannelState) => void): PushChannelClient | undefined {
+	const target = pushChannelTargetResolver();
+	if (!target) return undefined;
+	return connectPushChannel({
+		url: () => {
+			// Re-resolved on every reconnect attempt: the daemon rebinds a new random
+			// port on every restart, exactly the problem connectWithPolicy solves for
+			// one-shot RPC by re-reading the handle file each time.
+			const resolved = pushChannelTargetResolver();
+			if (!resolved) throw new Error("Papyrus daemon is not running");
+			return resolved.url;
+		},
+		token: target.token,
+		topics: ["tasks"],
+		onMessage: (topic) => { if (topic === "tasks") onMessage(); },
+		onStateChange,
+	});
+}

package/extension/src/skills.ts

@@ -1,5 +1,5 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import type { Artifact, SkillWorkflowRunResult, TaskGraph } from "@danypops/papyrus";
+import type { Artifact, WorkflowRunResult, TaskGraph } from "@danypops/papyrus";
 import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
 import { SKILL_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
 import { callService } from "./service-client.ts";
@@ -50,7 +50,7 @@ export function skillInvocationPrompt(skill: Artifact): string {
 	].join("\n");
 }
 
-export function skillRunTaskGraph(run: SkillWorkflowRunResult, taskArtifacts: Artifact[]): TaskGraph {
+export function skillRunTaskGraph(run: WorkflowRunResult, taskArtifacts: Artifact[]): TaskGraph {
 	const executionById = new Map(run.execution.nodes.map((node) => [node.id, node]));
 	return {
 		nodes: taskArtifacts.map((task) => ({
@@ -95,7 +95,7 @@ export async function showSkills(ctx: ExtensionCommandContext): Promise<void> {
 					if (typeof arguments_ !== "object" || arguments_ === null || Array.isArray(arguments_)) {
 						throw new Error("arguments must be a JSON object");
 					}
-					const run = await callService<Record<string, unknown>, SkillWorkflowRunResult>("skills.run", {
+					const run = await callService<Record<string, unknown>, WorkflowRunResult>("skills.run", {
 						id: skill.id,
 						arguments: arguments_ as Record<string, unknown>,
 						project_root: commandCtx.cwd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.35.1",
+  "version": "0.36.0",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "type": "module",
   "keywords": ["pi-package"],
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@danypops/daemon-kit": "^0.10.0",
-    "@danypops/papyrus": "^0.35.1",
+    "@danypops/papyrus": "^0.36.0",
     "beautiful-mermaid": "1.1.3"
   },
   "devDependencies": {