npm - @danypops/papyrus - Versions diffs - 0.35.2 → 0.35.3 - Mend

@danypops/papyrus 0.35.2 → 0.35.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/package.json CHANGED Viewed

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

package/src/cli.ts CHANGED Viewed

@@ -120,6 +120,10 @@ const USAGE = `Usage:
   papyrus playbooks enable|disable <id> [--json]
   papyrus playbooks assign-project <id> [project-root] [--json]
   papyrus playbooks update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--json]
+  papyrus playbooks contain <parent-id> <child-id> [--json]
+  papyrus playbooks uncontain <parent-id> <child-id> [--json]
+  papyrus playbooks depend <id> <dependency-id> [--json]
+  papyrus playbooks undepend <id> <dependency-id> [--json]
   papyrus notes capture <request> [--title <title>] [--json]
   papyrus notes list [--status <draft|active|archived>] [--text <query>] [--limit <count>] [--json]
   papyrus notes show <id> [--json]
@@ -889,8 +893,36 @@ export async function runPlaybooksCli(args: string[], client: TaskCliClient): Pr
 			human = `${artifactLabel(artifact)}`;
 			break;
 		}
+		case "contain": {
+			if (!id || !second || positional.length !== 3) throw new Error("playbooks contain requires a parent id and child id");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.contain", { parent_id: id, child_id: second });
+			result = artifact;
+			human = `Nested: ${second} → ${artifactLabel(artifact)}`;
+			break;
+		}
+		case "uncontain": {
+			if (!id || !second || positional.length !== 3) throw new Error("playbooks uncontain requires a parent id and child id");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.uncontain", { parent_id: id, child_id: second });
+			result = artifact;
+			human = `Removed ${second} from ${artifactLabel(artifact)}`;
+			break;
+		}
+		case "depend": {
+			if (!id || !second || positional.length !== 3) throw new Error("playbooks depend requires a playbook id and prerequisite id");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.depend", { id, dependency_id: second });
+			result = artifact;
+			human = `Dependency added: ${artifactLabel(artifact)} waits for ${second}`;
+			break;
+		}
+		case "undepend": {
+			if (!id || !second || positional.length !== 3) throw new Error("playbooks undepend requires a playbook id and prerequisite id");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.undepend", { id, dependency_id: second });
+			result = artifact;
+			human = `Dependency removed: ${artifactLabel(artifact)} no longer waits for ${second}`;
+			break;
+		}
 		default:
-			throw new Error("playbooks action must be create, list, show, invoke, enable, disable, assign-project, or update");
+			throw new Error("playbooks action must be create, list, show, invoke, enable, disable, assign-project, update, contain, uncontain, depend, or undepend");
 	}
 	return json ? JSON.stringify(result) : human;
 }

package/src/constants.ts CHANGED Viewed

@@ -108,6 +108,8 @@ export const SKILL_MAX_RENDERED_BYTES = 1_048_576;
 export const SKILL_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
 export const SKILL_INVOCATION_MAX_CALL_DEPTH = 4;
 export const PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
+/** Mirrors SKILL_INVOCATION_MAX_CALL_DEPTH: a playbook-calls-playbook edge chain is bounded the same way a skill-calls-skill chain is. */
+export const PLAYBOOK_INVOCATION_MAX_CALL_DEPTH = 4;
 export const PLAYBOOK_ARGUMENT_MAX_COUNT = 20;
 export const PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH = 64;
 export const PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH = 500;

package/src/domain-services.ts CHANGED Viewed

@@ -7,6 +7,7 @@ import {
 	PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH,
 	PLAYBOOK_ARGUMENT_MAX_COUNT,
 	PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH,
+	PLAYBOOK_INVOCATION_MAX_CALL_DEPTH,
 	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
 	RULE_TEXT_HARD_LIMIT_CHARACTERS,
 	SKILL_INVOCATION_MAX_CALL_DEPTH,
@@ -526,7 +527,15 @@ export function transitionSkill(artifacts: ArtifactStore, id: string, action: Sk
  * Playbooks: a trigger and an ordered list of steps an agent reads and follows -- a completely
  * different beast from Skills, not a subtype of one. A Skill (artifact-template or workflow) is
  * mechanically instantiated into other artifacts; a Playbook is never instantiated, it's read
- * and followed, and it never composes other Playbooks the way a Skill can call another Skill.
+ * and followed. Like Tasks, a Playbook can be nested or chained with another Playbook:
+ * `contains`/`part_of` (containPlaybook/uncontainPlaybook) nests a sub-playbook inside a parent
+ * -- invoking the parent recursively embeds the nested one's own steps, run as part of it.
+ * `depends_on` (dependPlaybook/undependPlaybook) chains one playbook before another -- invoking
+ * the dependent recursively renders the prerequisite's steps FIRST, to be completed before the
+ * dependent's own. Both are bounded and cycle-safe: a composition cycle degrades to a marker at
+ * render time (playbookInvocation) rather than being rejected at link time -- unlike Tasks' own
+ * depends_on, which does reject a real dependency cycle up front because Task dependencies gate
+ * actual lifecycle execution, not just text rendering.
  */
 export interface PlaybookArgument {
 	name: string;
@@ -629,15 +638,44 @@ export function transitionPlaybook(artifacts: ArtifactStore, id: string, action:
 	return artifacts.setStatus(id, target, context)!;
 }
-/**
- * Renders trigger/steps/tools/arguments into readable guidance, plus any real linked artifacts.
- * No nested playbook-calls-playbook composition -- a Playbook is a flat procedure, not a
- * composable bundle. `provided` is the caller's already-known argument values (e.g. from the
- * conversation so far); any declared *required* argument missing from it is called out
- * explicitly, directing the agent to discuss (live:true) rather than guess or silently proceed.
- */
-export function playbookInvocation(artifacts: ArtifactStore, id: string, provided: Record<string, string> = {}): string {
-	const playbook = requireKind(artifacts, id, "playbook");
+/** Idempotent (INSERT OR IGNORE at the storage layer): containing an already-nested child is a no-op, not an error. Both contains/part_of edges are written atomically -- matches tasks.contain's own shape. */
+export function containPlaybook(artifacts: ArtifactStore, parentId: string, childId: string, context?: ArtifactEventContext): Artifact {
+	requireLocallyOwnedContent(requireKind(artifacts, parentId, "playbook"));
+	requireLocallyOwnedContent(requireKind(artifacts, childId, "playbook"));
+	if (parentId === childId) throw new Error(`playbook "${parentId}" cannot contain itself`);
+	artifacts.link({ from: parentId, relation: "contains", to: childId }, context);
+	artifacts.link({ from: childId, relation: "part_of", to: parentId }, context);
+	return showPlaybook(artifacts, parentId);
+}
+/** Idempotent: uncontaining an already-absent nesting is a no-op. Both contains/part_of edges are removed atomically. */
+export function uncontainPlaybook(artifacts: ArtifactStore, parentId: string, childId: string, context?: ArtifactEventContext): Artifact {
+	requireLocallyOwnedContent(requireKind(artifacts, parentId, "playbook"));
+	requireLocallyOwnedContent(requireKind(artifacts, childId, "playbook"));
+	artifacts.unlink({ from: parentId, relation: "contains", to: childId }, context);
+	artifacts.unlink({ from: childId, relation: "part_of", to: parentId }, context);
+	return showPlaybook(artifacts, parentId);
+}
+/** Idempotent: depending on an already-declared prerequisite is a no-op, not an error. Unlike tasks.depend, this never rejects a cycle at write time -- playbookInvocation degrades a composition cycle to a marker at render time instead, the same posture already established for Skill-calls-Skill and Playbook-calls-Playbook via `contains`. */
+export function dependPlaybook(artifacts: ArtifactStore, id: string, dependencyId: string, context?: ArtifactEventContext): Artifact {
+	requireLocallyOwnedContent(requireKind(artifacts, id, "playbook"));
+	requireLocallyOwnedContent(requireKind(artifacts, dependencyId, "playbook"));
+	if (id === dependencyId) throw new Error(`playbook "${id}" cannot depend on itself`);
+	artifacts.link({ from: id, relation: "depends_on", to: dependencyId }, context);
+	return showPlaybook(artifacts, id);
+}
+/** Idempotent: undepending an already-absent prerequisite is a no-op. */
+export function undependPlaybook(artifacts: ArtifactStore, id: string, dependencyId: string, context?: ArtifactEventContext): Artifact {
+	requireLocallyOwnedContent(requireKind(artifacts, id, "playbook"));
+	requireLocallyOwnedContent(requireKind(artifacts, dependencyId, "playbook"));
+	artifacts.unlink({ from: id, relation: "depends_on", to: dependencyId }, context);
+	return showPlaybook(artifacts, id);
+}
+/** Renders trigger/body/arguments/steps/tools into readable guidance -- the flat, non-recursive part of a Playbook's own invocation, shared by the top-level render and by a nested composed call. */
+function playbookInvocationBody(playbook: Artifact, provided: Record<string, string>): string {
 	const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
 	const steps = Array.isArray(playbook.extra["steps"]) ? playbook.extra["steps"].filter((step): step is string => typeof step === "string") : [];
 	const tools = Array.isArray(playbook.extra["tools"]) ? playbook.extra["tools"].filter((tool): tool is string => typeof tool === "string") : [];
@@ -649,7 +687,7 @@ export function playbookInvocation(artifacts: ArtifactStore, id: string, provide
 		return `- ${argument.name} (${qualifier}${argument.description ? `: ${argument.description}` : ""}) -- not yet provided`;
 	});
 	const missingRequired = declaredArguments.filter((argument) => argument.required && provided[argument.name] === undefined);
-	const sections = [[
+	return [
 		`Apply Papyrus playbook "${playbook.title}".`,
 		`Trigger: ${trigger}`,
 		...(playbook.body ? [`Context: ${playbook.body}`] : []),
@@ -659,11 +697,56 @@ export function playbookInvocation(artifacts: ArtifactStore, id: string, provide
 			: []),
 		...(steps.length ? ["Steps:", ...steps.map((step, index) => `${index + 1}. ${step}`)] : []),
 		...(tools.length ? [`Tools: ${tools.join(", ")}`] : []),
-	].join("\n")];
+	].join("\n");
+}
+/**
+ * Renders trigger/steps/tools/arguments into readable guidance, plus any real linked artifacts.
+ * Two relations compose recursively, each with distinct wording matching Tasks' own semantics:
+ * `contains` nests a child playbook -- its full steps render AFTER this playbook's own, as
+ * "run as part of this one". `depends_on` chains a prerequisite -- its full steps render BEFORE
+ * this playbook's own, as "complete this first". Every other relation (references, relates_to,
+ * etc.) still gets the flat one-line "Linked context" pointer, unchanged. Bounded and
+ * cycle-safe -- a composition cycle degrades to a marker instead of infinite-looping, matching
+ * skillInvocation's own cycle-safety discipline.
+ * `provided` is the caller's already-known argument values (e.g. from the conversation so far);
+ * any declared *required* argument missing from it is called out explicitly, directing the agent
+ * to discuss (live:true) rather than guess or silently proceed. `visited` and `depth` are
+ * recursion-internal; callers should not pass them.
+ */
+export function playbookInvocation(artifacts: ArtifactStore, id: string, provided: Record<string, string> = {}, visited: Set<string> = new Set(), depth = 0): string {
+	const playbook = requireKind(artifacts, id, "playbook");
+	visited.add(id);
 	const edges = artifacts.relationships({ artifactIds: [id] }).filter((edge) => edge.from === id).slice(0, PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS);
-	const linkedLines = edges
-		.map((edge) => { const target = artifacts.get(edge.to); return target ? `- ${edge.relation} ${target.kind} "${target.title}"` : undefined; })
-		.filter((line): line is string => line !== undefined);
-	if (linkedLines.length > 0) sections.push(["Linked context (query Papyrus for full detail before proceeding):", ...linkedLines].join("\n"));
+	const linkedArtifactLines: string[] = [];
+	const nestedSections: string[] = []; // contains -- rendered after this playbook's own body
+	const prerequisiteSections: string[] = []; // depends_on -- rendered before this playbook's own body
+	for (const edge of edges) {
+		const target = artifacts.get(edge.to);
+		if (!target) continue; // dangling edge -- defensive, should not happen
+		const isComposing = target.kind === "playbook" && (edge.relation === "contains" || edge.relation === "depends_on");
+		if (!isComposing) {
+			linkedArtifactLines.push(`- ${edge.relation} ${target.kind} "${target.title}"`);
+			continue;
+		}
+		const bucket = edge.relation === "contains" ? nestedSections : prerequisiteSections;
+		const role = edge.relation === "contains" ? "nested" : "prerequisite";
+		if (visited.has(target.id)) {
+			bucket.push(`Also linked via ${edge.relation} to ${role} playbook "${target.title}" -- already invoked above in this chain, not repeated.`);
+		} else if (depth + 1 > PLAYBOOK_INVOCATION_MAX_CALL_DEPTH) {
+			bucket.push(`Also linked via ${edge.relation} to ${role} playbook "${target.title}" -- call depth limit reached, invoke it separately.`);
+		} else {
+			const nested = playbookInvocation(artifacts, target.id, provided, visited, depth + 1);
+			bucket.push(edge.relation === "contains"
+				? `Nested playbook (contains) "${target.title}" -- run as part of this one:\n${nested}`
+				: `Prerequisite playbook (depends_on) "${target.title}" -- complete this FIRST, before the steps below:\n${nested}`);
+		}
+	}
+	const sections = [...prerequisiteSections, playbookInvocationBody(playbook, provided), ...nestedSections];
+	if (linkedArtifactLines.length > 0) {
+		sections.push(["Linked context (query Papyrus for full detail before proceeding):", ...linkedArtifactLines].join("\n"));
+	}
 	return sections.join("\n\n");
 }

package/src/modules/playbooks.ts CHANGED Viewed

@@ -6,7 +6,7 @@
  * its own kind, not a subtype squeezed into "skill". See domain-services.ts's Playbook section
  * for the full rationale.
  */
-import { assignPlaybookProject, createPlaybook, listPlaybooks, playbookInvocation, showPlaybook, transitionPlaybook, updatePlaybook } from "../domain-services.ts";
+import { assignPlaybookProject, containPlaybook, createPlaybook, dependPlaybook, listPlaybooks, playbookInvocation, showPlaybook, transitionPlaybook, uncontainPlaybook, undependPlaybook, updatePlaybook } from "../domain-services.ts";
 import type { OperationDefinition } from "../module-registry.ts";
 import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
@@ -51,6 +51,7 @@ const artifactFilter = (input: OperationInput) => ({
 /** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. */
 export const PLAYBOOKS_OPERATION_NAMES = [
 	"playbooks.create", "playbooks.list", "playbooks.show", "playbooks.invoke", "playbooks.enable", "playbooks.disable", "playbooks.assign_project", "playbooks.update",
+	"playbooks.contain", "playbooks.uncontain", "playbooks.depend", "playbooks.undepend",
 ] as const;
 export function playbooksOperations(artifacts: ArtifactStore, scopes: ArtifactScopeStore): OperationDefinition[] {
@@ -74,5 +75,9 @@ export function playbooksOperations(artifacts: ArtifactStore, scopes: ArtifactSc
 		define("playbooks.update", (input: OperationInput) => updatePlaybook(artifacts, string(input, "id"), {
 			title: optionalString(input, "title"), body: optionalString(input, "body"), labels: input["labels"] as string[] | undefined,
 		}, eventContext(input))),
+		define("playbooks.contain", (input: OperationInput) => containPlaybook(artifacts, string(input, "parent_id"), string(input, "child_id"), eventContext(input))),
+		define("playbooks.uncontain", (input: OperationInput) => uncontainPlaybook(artifacts, string(input, "parent_id"), string(input, "child_id"), eventContext(input))),
+		define("playbooks.depend", (input: OperationInput) => dependPlaybook(artifacts, string(input, "id"), string(input, "dependency_id"), eventContext(input))),
+		define("playbooks.undepend", (input: OperationInput) => undependPlaybook(artifacts, string(input, "id"), string(input, "dependency_id"), eventContext(input))),
 	];
 }

package/src/service.ts CHANGED Viewed

@@ -413,6 +413,10 @@ function handlers(
 		"playbooks.disable": forwardToModule("playbooks.disable"),
 		"playbooks.assign_project": forwardToModule("playbooks.assign_project"),
 		"playbooks.update": forwardToModule("playbooks.update"),
+		"playbooks.contain": forwardToModule("playbooks.contain"),
+		"playbooks.uncontain": forwardToModule("playbooks.uncontain"),
+		"playbooks.depend": forwardToModule("playbooks.depend"),
+		"playbooks.undepend": forwardToModule("playbooks.undepend"),
 		"skills.instantiate": (input) => {
 			const templateId = string(input, "template_id");
 			const template = artifacts.get(templateId);