@danypops/pi-papyrus 0.35.1 → 0.35.2

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, not a subtype: a trigger and an ordered list of steps an agent reads and follows, never mechanically instantiated. Like Tasks, a Playbook can be nested or chained with another Playbook: `contain`/`uncontain` nest a child Playbook inside a parent (its steps run as part of the parent); `depend`/`undepend` chain a prerequisite Playbook before another (its steps run first). Both compose recursively when invoked, bounded and cycle-safe. create/update/list/show/invoke, enable/disable, contain/uncontain, depend/undepend. 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
 
 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

@@ -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, 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. Like Tasks, a Playbook can be nested or chained with another Playbook: contain/uncontain nest a child Playbook inside a parent (invoking the parent recursively runs the child's steps as part of it); depend/undepend chain a prerequisite Playbook before another (invoking the dependent recursively runs the prerequisite's steps first). Both are bounded and cycle-safe -- a composition cycle degrades to a marker instead of infinite-looping, rather than being rejected up front the way a real Task dependency cycle is. ACTIONS: create, list, show, invoke, enable, disable, assign_project, update, contain, uncontain, depend, undepend, 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`, 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,8 +675,12 @@ 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") {
@@ -690,7 +697,10 @@ export function registerPlaybooksTool(pi: ExtensionAPI): void {
 				}
 				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);

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.35.1",
+  "version": "0.35.2",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "type": "module",
   "keywords": ["pi-package"],