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

@danypops/papyrus 0.35.3 → 0.36.0

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 (12) hide show

package/package.json +1 -1
package/src/cli.ts +14 -5
package/src/constants.ts +7 -0
package/src/domain/skill-definition.ts +1 -1
package/src/domain-services.ts +16 -12
package/src/index.ts +1 -1
package/src/modules/playbooks.ts +54 -11
package/src/modules/skills.ts +2 -2
package/src/playbook-definition.ts +176 -0
package/src/playbook-execution.ts +95 -0
package/src/service.ts +2 -1
package/src/{skill-execution.ts → workflow-execution.ts} +83 -29

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.35.3",
+  "version": "0.36.0",
   "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

@@ -113,10 +113,10 @@ const USAGE = `Usage:
   papyrus skills assign-project <id> [project-root] [--json]
   papyrus skills update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--json]
   papyrus playbooks create --title <title> [--body <body>] [--trigger <text>] [--steps-json <json>] [--tools-json <json>] [--labels-json <json>] [--extra-json <json>] [--arguments-json <json array>] [--project-root <path>] [--json]
-  papyrus playbooks invoke <id> [--arguments-json <json object>] [--json]
+  papyrus playbooks invoke <id> [--arguments-json <json object>] [--project-root <path>] [--json]  # materializes real tasks (contains/depends_on-wired) and focuses the entry task
+  papyrus playbooks preview <id> [--arguments-json <json object>] [--json]  # renders text only, creates nothing
   papyrus playbooks list [--status <status>] [--text <query>] [--limit <count>] [--project-root <path>] [--json]
   papyrus playbooks show <id> [--json]
-  papyrus playbooks invoke <id> [--json]
   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]
@@ -863,11 +863,20 @@ export async function runPlaybooksCli(args: string[], client: TaskCliClient): Pr
 			human = `${artifactLabel(artifact)}\n\n${artifact.body ?? ""}`;
 			break;
 		}
+		case "preview": {
+			if (!id || second) throw new Error("playbooks preview requires exactly one playbook id");
+			const rendered = await client.call<Record<string, unknown>, string>("playbooks.preview", { id, arguments: playbookArguments });
+			result = rendered;
+			human = rendered;
+			break;
+		}
 		case "invoke": {
 			if (!id || second) throw new Error("playbooks invoke requires exactly one playbook id");
-			const invocation = await client.call<Record<string, unknown>, string>("playbooks.invoke", { id, arguments: playbookArguments });
+			const invocation = await client.call<Record<string, unknown>, { entryTaskId: string; missingArguments?: string[] }>("playbooks.invoke", { id, arguments: playbookArguments, project_root: playbookProjectRoot });
 			result = invocation;
-			human = invocation;
+			human = invocation.missingArguments
+				? `Missing required argument(s): ${invocation.missingArguments.join(", ")}.`
+				: `Invoked: entry task ${invocation.entryTaskId} focused. Drive it forward with \`tasks start/submit/complete\` like any other task.`;
 			break;
 		}
 		case "enable":
@@ -922,7 +931,7 @@ export async function runPlaybooksCli(args: string[], client: TaskCliClient): Pr
 			break;
 		}
 		default:
-			throw new Error("playbooks action must be create, list, show, invoke, enable, disable, assign-project, update, contain, uncontain, depend, or undepend");
+			throw new Error("playbooks action must be create, list, show, invoke, preview, enable, disable, assign-project, update, contain, uncontain, depend, or undepend");
 	}
 	return json ? JSON.stringify(result) : human;
 }

package/src/constants.ts CHANGED Viewed

@@ -113,6 +113,13 @@ 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;
+/**
+ * playbooks.invoke materializes a real Task per step (plus one container Task per playbook
+ * node in the contains/depends_on composition tree) instead of rendering text -- this bounds
+ * the total number of Tasks one invoke call can create, the same blast-radius concern
+ * SKILL_MAX_BLUEPRINTS already covers for workflow Skills.
+ */
+export const PLAYBOOK_INVOCATION_MAX_CREATED_TASKS = 200;
 /**
  * At the core, a workflow Skill creates Tasks and begins a pipeline -- an Ansible playbook or

package/src/domain/skill-definition.ts CHANGED Viewed

@@ -49,7 +49,7 @@ export interface SkillTaskBlueprint {
 /**
  * A pipeline step that nests another workflow Skill's run inside this one -- the Jenkins
  * "trigger downstream job and wait" / Ansible "include_tasks" primitive. `skillId` is late-
- * bound: existence and workflow-subtype are checked at execution time (skill-execution.ts),
+ * bound: existence and workflow-subtype are checked at execution time (workflow-execution.ts),
  * not here, since this validator has no store access. `dependsOn`/`parent` place this step in
  * the SAME dependency graph as ordinary task blueprints -- a task can depend on a skill-call
  * ref (meaning: depend on every task the nested run creates), and a skill-call's own `parent`

package/src/domain-services.ts CHANGED Viewed

@@ -524,18 +524,22 @@ 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. 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.
+ * Playbooks: a trigger and an ordered list of steps -- authored as prose, a completely
+ * different beast from Skills at that level. But playbooks.invoke (playbook-execution.ts)
+ * recycles the exact same materialization engine workflow Skills use: it compiles a Playbook
+ * into a SkillDefinition and mechanically instantiates real Tasks from it, same as a Skill's
+ * own artifact-template/workflow blueprint. `playbookInvocation` below is the OTHER, older
+ * path -- rendered text with no side effects, now exposed as the `preview` action for a human
+ * who wants to just read a playbook before invoking it, not the primary way of running one.
+ * Like Tasks, a Playbook can be nested or chained with another Playbook: `contains`/`part_of`
+ * (containPlaybook/uncontainPlaybook) nests a sub-playbook inside a parent -- both preview and
+ * invoke run the nested one's own steps as part of the parent, invoke as real dependsOn-chained
+ * Tasks, preview as embedded text. `depends_on` (dependPlaybook/undependPlaybook) chains one
+ * playbook before another -- the prerequisite's steps run first, either as real Tasks the
+ * dependent's first step depends_on (invoke) or as embedded text rendered first (preview).
+ * Composition is bounded in both paths; preview degrades a cycle to a text marker at render
+ * time, while invoke's compiler (playbook-definition.ts) treats a cycle as a hard error --
+ * real Tasks would otherwise be created in an infinite loop, unlike text rendering.
  */
 export interface PlaybookArgument {
 	name: string;

package/src/index.ts CHANGED Viewed

@@ -23,7 +23,7 @@ export { connectPapyrusClient, resolvePushChannelTarget, type PapyrusClient, typ
 export type { DiscussionAndRounds } from "./discussion-service.ts";
 export { NOTE_DISPOSITIONS } from "./note-service.ts";
 export type { OperationName, SchemaState } from "./service.ts";
-export type { SkillWorkflowRunResult } from "./skill-execution.ts";
+export type { WorkflowRunResult } from "./workflow-execution.ts";
 export { projectArtifactRelationships } from "./artifact-relationship-view.ts";
 export { taskContext } from "./task-context.ts";
 export { projectTaskExecution, type TaskExecutionPlan, type TaskExecutionState } from "./task-execution.ts";

package/src/modules/playbooks.ts CHANGED Viewed

@@ -1,15 +1,34 @@
 /**
  * modules/playbooks.ts — Playbooks as a Papyrus-native registered module.
  *
- * A Playbook (trigger + ordered steps an agent reads and follows) is a completely different
- * beast from a Skill (a mechanically instantiated artifact-template or workflow blueprint) --
- * its own kind, not a subtype squeezed into "skill". See domain-services.ts's Playbook section
- * for the full rationale.
+ * A Playbook (trigger + ordered steps, contains/depends_on composition, predefined
+ * rules/docs) is a completely different beast from a Skill (a mechanically instantiated
+ * artifact-template or workflow blueprint) at the AUTHORING level -- but playbooks.invoke
+ * recycles the exact same materialization engine workflow Skills use (playbook-execution.ts
+ * compiles a Playbook's composition tree into a SkillDefinition, then hands off to
+ * workflow-execution.ts's shared core). See domain-services.ts's Playbook section and
+ * playbook-definition.ts for the full rationale.
  */
-import { assignPlaybookProject, containPlaybook, createPlaybook, dependPlaybook, listPlaybooks, playbookInvocation, showPlaybook, transitionPlaybook, uncontainPlaybook, undependPlaybook, 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";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import { invokePlaybook } from "../playbook-execution.ts";
+import type { Tasks } from "../task-service.ts";
 const MODULE_ID = "playbooks";
@@ -41,6 +60,11 @@ const eventContext = (input: OperationInput) => ({
 	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
 });
+const eventContextFor = (input: OperationInput, source: string) => {
+	const context = eventContext(input);
+	return { ...context, source: context.source ?? source };
+};
 const artifactFilter = (input: OperationInput) => ({
 	status: optionalString(input, "status"),
 	text: optionalString(input, "text"),
@@ -50,28 +74,47 @@ 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.create", "playbooks.list", "playbooks.show", "playbooks.invoke", "playbooks.preview", "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[] {
+export interface PlaybooksModuleDeps {
+	artifacts: ArtifactStore;
+	events: TaskEventStore;
+	scopes: TaskScopeStore;
+	/** Docs/Rules/Skills/Playbooks project scoping (distinct from `scopes`, which is Task-run project scoping for playbooks.invoke's materialized tasks). */
+	artifactScopes: ArtifactScopeStore;
+	/** Used for exactly one thing: focusing the entry task after a successful invoke -- the one safety-checked Tasks operation this module needs, not bulk graph construction (that goes straight through artifacts/events/scopes in playbook-execution.ts, mirroring workflow-execution.ts). */
+	tasks: Tasks;
+}
+export function playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks }: PlaybooksModuleDeps): OperationDefinition[] {
 	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
 		name, moduleId: MODULE_ID, execute,
 	});
 	return [
-		define("playbooks.create", (input: OperationInput) => createPlaybook(artifacts, scopes, {
+		define("playbooks.create", (input: OperationInput) => createPlaybook(artifacts, artifactScopes, {
 			title: string(input, "title"), body: optionalString(input, "body"), trigger: optionalString(input, "trigger"),
 			steps: input["steps"] as string[] | undefined, tools: input["tools"] as string[] | undefined,
 			arguments: input["arguments"],
 			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
 			projectRoot: optionalString(input, "project_root"),
 		}, eventContext(input))),
-		define("playbooks.list", (input: OperationInput) => listPlaybooks(artifacts, scopes, artifactFilter(input))),
+		define("playbooks.list", (input: OperationInput) => listPlaybooks(artifacts, artifactScopes, artifactFilter(input))),
 		define("playbooks.show", (input: OperationInput) => showPlaybook(artifacts, string(input, "id"))),
-		define("playbooks.invoke", (input: OperationInput) => playbookInvocation(artifacts, string(input, "id"), input["arguments"] as Record<string, string> | undefined)),
+		define("playbooks.preview", (input: OperationInput) => playbookInvocation(artifacts, string(input, "id"), input["arguments"] as Record<string, string> | undefined)),
+		define("playbooks.invoke", (input: OperationInput) => {
+			const result = invokePlaybook(artifacts, string(input, "id"), {
+				runId: optionalString(input, "run_id") ?? optionalString(input, "runId"),
+				arguments: input["arguments"] as Record<string, unknown> | undefined,
+			}, { events, scopes, projectRoot: optionalString(input, "project_root"), context: eventContextFor(input, "playbook-run") });
+			if ("missingArguments" in result) return result;
+			tasks.focus(result.entryTaskId, eventContextFor(input, "playbook-run"));
+			return result;
+		}),
 		define("playbooks.enable", (input: OperationInput) => transitionPlaybook(artifacts, string(input, "id"), "enable", eventContext(input))),
 		define("playbooks.disable", (input: OperationInput) => transitionPlaybook(artifacts, string(input, "id"), "disable", eventContext(input))),
-		define("playbooks.assign_project", (input: OperationInput) => assignPlaybookProject(artifacts, scopes, string(input, "id"), optionalString(input, "project_root"))),
+		define("playbooks.assign_project", (input: OperationInput) => assignPlaybookProject(artifacts, artifactScopes, string(input, "id"), optionalString(input, "project_root"))),
 		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))),

package/src/modules/skills.ts CHANGED Viewed

@@ -12,7 +12,7 @@
  * skills.run depends on the Task-domain ports (TaskEventStore, TaskScopeStore) as
  * constructor parameters. These are shared port contracts every module may depend on,
  * the same way every module already depends on ArtifactStore — not "another module's
- * infrastructure" in the sense of a concrete class. skill-execution.ts already has this
+ * infrastructure" in the sense of a concrete class. workflow-execution.ts already has this
  * port dependency pre-existing; untangling it is a separate, larger concern than this
  * extraction.
  */
@@ -23,7 +23,7 @@ import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
 import type { TaskEventStore } from "../ports/task-event-store.ts";
 import type { TaskScopeStore } from "../ports/task-scope-store.ts";
-import { instantiateSkillWorkflow } from "../skill-execution.ts";
+import { instantiateSkillWorkflow } from "../workflow-execution.ts";
 const MODULE_ID = "skills";

package/src/playbook-definition.ts ADDED Viewed

@@ -0,0 +1,176 @@
+/**
+ * playbook-definition.ts — compiles a Playbook's own steps/trigger/tools/arguments, plus its
+ * `contains` (nested) and `depends_on` (prerequisite) composition tree, into an in-memory
+ * SkillDefinition. This is the "recycle Papyrus Skills -> Playbooks" half of the redesign:
+ * rather than a second graph-materialization engine, a Playbook becomes prose that compiles
+ * down to the exact blueprint shape workflow Skills already use, then hands off to
+ * workflow-execution.ts's shared materializeWorkflowDefinition for the actual Task creation.
+ *
+ * One task blueprint per playbook-node root (a container, never itself gated) plus one per
+ * step (chained by sequential dependsOn); `contains`-linked playbooks nest their own root
+ * under the parent root and continue the parent's own step chain ("run as part of this one",
+ * after the parent's own steps); `depends_on`-linked playbooks compile as independent
+ * subtrees whose tails gate this node's first step ("complete this FIRST"). No SkillCallBlueprint
+ * indirection is used -- everything is inlined into one flat definition, since a Playbook's
+ * composition tree is fully known and owned at compile time, unlike a workflow Skill's nested
+ * pipeline step (which references another SKILL by id, resolved and executed independently).
+ */
+import {
+	PLAYBOOK_INVOCATION_MAX_CALL_DEPTH,
+	PLAYBOOK_INVOCATION_MAX_CREATED_TASKS,
+	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
+} from "./constants.ts";
+import type { Artifact } from "./domain/artifact.ts";
+import type { SkillDefinition, SkillInputDefinition, SkillTaskBlueprint } from "./domain/skill-definition.ts";
+import { validateSkillDefinition } from "./domain/skill-definition.ts";
+import type { PlaybookArgument } from "./domain-services.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+/** A non-composing edge touching a playbook node, to be mirrored onto that node's generated root task once real task ids exist -- e.g. a Rule `gates` this playbook, or this playbook `references`/`documents` a Doc. Direction is preserved exactly: `from`/`to` name whichever side is NOT the playbook, and `ownerIsFrom` says which side the playbook (now the generated root task) occupies. */
+export interface PlaybookExternalLink {
+	rootRef: string;
+	relation: string;
+	otherArtifactId: string;
+	/** true: playbook (root task) is the edge's `from`; false: playbook (root task) is the edge's `to`. */
+	ownerIsFrom: boolean;
+}
+export interface CompiledPlaybook {
+	definition: SkillDefinition;
+	/** The very first real leaf task in the whole tree's reading order -- what a caller should focus once materialized. */
+	entryRef: string;
+	externalLinks: PlaybookExternalLink[];
+}
+function requirePlaybook(artifacts: ArtifactStore, id: string): Artifact {
+	const playbook = artifacts.get(id);
+	if (!playbook) throw new Error(`playbook artifact "${id}" not found`);
+	if (playbook.kind !== "playbook") throw new Error(`artifact "${id}" is not a playbook`);
+	return playbook;
+}
+function stepsOf(playbook: Artifact): string[] {
+	return Array.isArray(playbook.extra["steps"]) ? playbook.extra["steps"].filter((step): step is string => typeof step === "string") : [];
+}
+function toolsOf(playbook: Artifact): string[] {
+	return Array.isArray(playbook.extra["tools"]) ? playbook.extra["tools"].filter((tool): tool is string => typeof tool === "string") : [];
+}
+function argumentsOf(playbook: Artifact): PlaybookArgument[] {
+	return Array.isArray(playbook.extra["arguments"]) ? (playbook.extra["arguments"] as PlaybookArgument[]) : [];
+}
+/** The generated container task's own body -- purpose and context only. Steps are separate child tasks, so they are not re-listed here (that was the old text-dump shape). */
+function rootTaskBody(playbook: Artifact): string {
+	const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
+	const tools = toolsOf(playbook);
+	return [
+		`Playbook "${playbook.title}".`,
+		`Trigger: ${trigger}`,
+		...(playbook.body ? [`Context: ${playbook.body}`] : []),
+		...(tools.length > 0 ? [`Tools: ${tools.join(", ")}`] : []),
+		"This task contains its steps as child tasks -- work through them in order as each becomes focused.",
+	].join("\n");
+}
+function stepTitle(step: string): string {
+	const firstLine = step.split("\n")[0]!.trim();
+	return firstLine.length > 120 ? `${firstLine.slice(0, 117)}...` : firstLine;
+}
+interface CompileContext {
+	tasks: SkillTaskBlueprint[];
+	inputs: Record<string, SkillInputDefinition>;
+	externalLinks: PlaybookExternalLink[];
+	refCounter: { n: number };
+}
+interface CompileNodeResult {
+	rootRef: string;
+	/** First real leaf in this subtree's own reading order -- rootRef itself when the node has neither steps nor nested children. */
+	headRef: string;
+	/** Last real leaf in this subtree's own reading order -- what an enclosing "nested-after" continuation or successor prerequisite gate should depend on. */
+	tailRef: string;
+}
+function mergeArgument(inputs: Record<string, SkillInputDefinition>, argument: PlaybookArgument): void {
+	const existing = inputs[argument.name];
+	inputs[argument.name] = { type: "string", required: (existing?.required ?? false) || argument.required };
+}
+function compileNode(
+	artifacts: ArtifactStore,
+	playbookId: string,
+	ctx: CompileContext,
+	ancestorIds: ReadonlySet<string>,
+	depth: number,
+	parentRef: string | undefined,
+	incomingPrecedingRefs: string[],
+): CompileNodeResult {
+	if (ancestorIds.has(playbookId)) throw new Error(`playbook composition cycle includes "${playbookId}"`);
+	if (depth > PLAYBOOK_INVOCATION_MAX_CALL_DEPTH) throw new Error(`playbook composition exceeds ${PLAYBOOK_INVOCATION_MAX_CALL_DEPTH} levels`);
+	const nextAncestors = new Set([...ancestorIds, playbookId]);
+	const playbook = requirePlaybook(artifacts, playbookId);
+	for (const argument of argumentsOf(playbook)) mergeArgument(ctx.inputs, argument);
+	const rootRef = `pb${ctx.refCounter.n++}`;
+	const rootBlueprint: SkillTaskBlueprint = { ref: rootRef, title: playbook.title, body: rootTaskBody(playbook), ...(parentRef ? { parent: parentRef } : {}) };
+	ctx.tasks.push(rootBlueprint);
+	if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS) throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
+	const edges = artifacts.relationships({ artifactIds: [playbookId] }).slice(0, PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS);
+	const prerequisiteIds = edges.filter((edge) => edge.from === playbookId && edge.relation === "depends_on").map((edge) => edge.to)
+		.filter((id) => artifacts.get(id)?.kind === "playbook");
+	const nestedIds = edges.filter((edge) => edge.from === playbookId && edge.relation === "contains").map((edge) => edge.to)
+		.filter((id) => artifacts.get(id)?.kind === "playbook");
+	for (const edge of edges) {
+		const isComposingFrom = edge.from === playbookId && (edge.relation === "contains" || edge.relation === "depends_on") && artifacts.get(edge.to)?.kind === "playbook";
+		if (isComposingFrom) continue;
+		if (edge.from === playbookId) ctx.externalLinks.push({ rootRef, relation: edge.relation, otherArtifactId: edge.to, ownerIsFrom: true });
+		else if (edge.to === playbookId) ctx.externalLinks.push({ rootRef, relation: edge.relation, otherArtifactId: edge.from, ownerIsFrom: false });
+	}
+	const prerequisiteTailRefs: string[] = [];
+	let headRef: string | undefined;
+	for (const prerequisiteId of prerequisiteIds) {
+		const result = compileNode(artifacts, prerequisiteId, ctx, nextAncestors, depth + 1, undefined, []);
+		prerequisiteTailRefs.push(result.tailRef);
+		if (headRef === undefined) headRef = result.headRef;
+	}
+	let cursorPrecedingRefs = [...incomingPrecedingRefs, ...prerequisiteTailRefs];
+	let tailRef = rootRef;
+	for (const [index, step] of stepsOf(playbook).entries()) {
+		const stepRef = `${rootRef}-s${index}`;
+		ctx.tasks.push({ ref: stepRef, title: stepTitle(step), body: step, parent: rootRef, dependsOn: cursorPrecedingRefs });
+		if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS) throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
+		if (headRef === undefined) headRef = stepRef;
+		cursorPrecedingRefs = [stepRef];
+		tailRef = stepRef;
+	}
+	for (const nestedId of nestedIds) {
+		const result = compileNode(artifacts, nestedId, ctx, nextAncestors, depth + 1, rootRef, cursorPrecedingRefs);
+		if (headRef === undefined) headRef = result.headRef;
+		cursorPrecedingRefs = [result.tailRef];
+		tailRef = result.tailRef;
+	}
+	if (tailRef === rootRef && cursorPrecedingRefs.length > 0) rootBlueprint.dependsOn = cursorPrecedingRefs;
+	return { rootRef, headRef: headRef ?? rootRef, tailRef };
+}
+/** Pure and read-only: creates no artifacts. Cycle/depth-bounded exactly like playbookInvocation's own traversal, but a composition cycle here is a hard error (real Tasks would be created, unlike a text render degrading to a marker). */
+export function compilePlaybookDefinition(artifacts: ArtifactStore, playbookId: string): CompiledPlaybook {
+	const ctx: CompileContext = { tasks: [], inputs: {}, externalLinks: [], refCounter: { n: 0 } };
+	const { headRef } = compileNode(artifacts, playbookId, ctx, new Set(), 0, undefined, []);
+	const definition = validateSkillDefinition({
+		version: 1,
+		inputs: ctx.inputs,
+		blueprints: { docs: [], rules: [], tasks: ctx.tasks, skills: [] },
+		links: [],
+	});
+	return { definition, entryRef: headRef, externalLinks: ctx.externalLinks };
+}

package/src/playbook-execution.ts ADDED Viewed

@@ -0,0 +1,95 @@
+/**
+ * playbook-execution.ts — playbooks.invoke's real implementation: compile the Playbook's
+ * composition tree (playbook-definition.ts) into a SkillDefinition, materialize it through
+ * workflow-execution.ts's shared engine, mirror any pre-existing Rule/Doc links onto the
+ * generated root task, and report which task to focus. No text is rendered here -- every
+ * step is its own Task, and only the currently-focused one is ever surfaced to an agent
+ * (via the existing Task Focus system-prompt pointer), which is what actually avoids the
+ * old text-dump problem: one page at a time, not the whole book at once.
+ */
+import type { SkillArgumentValue } from "./domain/skill-definition.ts";
+import { compilePlaybookDefinition } from "./playbook-definition.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+import { requireAtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
+import { materializeWorkflowDefinition, type WorkflowRunHistory } from "./workflow-execution.ts";
+import type { TaskExecutionPlan } from "./task-execution.ts";
+export interface InvokePlaybookInput {
+	runId?: string;
+	arguments?: Record<string, unknown>;
+}
+export interface PlaybookInvocationResult {
+	playbookId: string;
+	runId: string;
+	arguments: Record<string, SkillArgumentValue>;
+	created: { docs: string[]; rules: string[]; tasks: string[] };
+	rootTaskIds: string[];
+	/** The one task to focus -- the first real leaf in the whole composition tree's reading order (deepest prerequisite's own first step, or this playbook's own first step, or its first nested child's, or the container task itself when there is nothing else). */
+	entryTaskId: string;
+	execution: TaskExecutionPlan;
+}
+export interface PlaybookMissingArguments {
+	playbookId: string;
+	/** Nothing was created: ask the human for these (discuss tool, live:true) before invoking again with them supplied. */
+	missingArguments: string[];
+}
+function missingRequiredInputs(inputs: Record<string, { required?: boolean; default?: SkillArgumentValue }>, provided: Record<string, unknown>): string[] {
+	return Object.entries(inputs)
+		.filter(([name, input]) => input.required && provided[name] === undefined && input.default === undefined)
+		.map(([name]) => name);
+}
+/** Reads each newly-created task's own playbookRun.ref tag back off the store -- avoids threading an extra ref-to-id map out of materializeWorkflowDefinition's existing, already-stable return shape. */
+function resolveRefToTaskId(artifacts: ArtifactStore, taskIds: string[]): Map<string, string> {
+	const map = new Map<string, string>();
+	for (const taskId of taskIds) {
+		const lineage = artifacts.get(taskId)?.extra["playbookRun"];
+		if (typeof lineage !== "object" || lineage === null || Array.isArray(lineage)) continue;
+		const ref = (lineage as Record<string, unknown>)["ref"];
+		if (typeof ref === "string") map.set(ref, taskId);
+	}
+	return map;
+}
+export function invokePlaybook(
+	artifacts: ArtifactStore,
+	playbookId: string,
+	input: InvokePlaybookInput,
+	history?: WorkflowRunHistory,
+): PlaybookInvocationResult | PlaybookMissingArguments {
+	const compiled = compilePlaybookDefinition(artifacts, playbookId);
+	const missingArguments = missingRequiredInputs(compiled.definition.inputs, input.arguments ?? {});
+	if (missingArguments.length > 0) return { playbookId, missingArguments };
+	const atomic = history ? history.events.atomic.bind(history.events) : requireAtomicArtifactStore(artifacts).atomic.bind(requireAtomicArtifactStore(artifacts));
+	return atomic(() => {
+		const result = materializeWorkflowDefinition(
+			artifacts,
+			{ ownerId: playbookId, extraKey: "playbookRun", labelPrefix: "playbook-run" },
+			compiled.definition,
+			{ runId: input.runId, arguments: input.arguments, focusRef: compiled.entryRef },
+			history,
+			new Set(),
+			0,
+		);
+		const refToTaskId = resolveRefToTaskId(artifacts, result.created.tasks);
+		for (const link of compiled.externalLinks) {
+			const taskId = refToTaskId.get(link.rootRef);
+			if (!taskId) continue; // defensive -- every rootRef this compiler emits is always materialized
+			if (link.ownerIsFrom) artifacts.link({ from: taskId, relation: link.relation, to: link.otherArtifactId });
+			else artifacts.link({ from: link.otherArtifactId, relation: link.relation, to: taskId });
+		}
+		return {
+			playbookId,
+			runId: result.runId,
+			arguments: result.arguments,
+			created: { docs: result.created.docs, rules: result.created.rules, tasks: result.created.tasks },
+			rootTaskIds: result.rootTaskIds,
+			entryTaskId: result.entryTaskId!,
+			execution: result.execution,
+		};
+	});
+}

package/src/service.ts CHANGED Viewed

@@ -409,6 +409,7 @@ function handlers(
 		"playbooks.list": forwardToModule("playbooks.list"),
 		"playbooks.show": forwardToModule("playbooks.show"),
 		"playbooks.invoke": forwardToModule("playbooks.invoke"),
+		"playbooks.preview": forwardToModule("playbooks.preview"),
 		"playbooks.enable": forwardToModule("playbooks.enable"),
 		"playbooks.disable": forwardToModule("playbooks.disable"),
 		"playbooks.assign_project": forwardToModule("playbooks.assign_project"),
@@ -480,7 +481,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority));
 	moduleRegistry.registerAll(rulesOperations(artifacts, artifactScopes));
 	moduleRegistry.registerAll(skillsOperations({ artifacts, events, scopes, artifactScopes, authority }));
-	moduleRegistry.registerAll(playbooksOperations(artifacts, artifactScopes));
+	moduleRegistry.registerAll(playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks }));
 	moduleRegistry.registerAll(graphProjectionOperations(artifacts, projections, authority));
 	const registry = handlers(artifacts, gates, tasks, notes, events, scopes, () => migrateDb(db), moduleRegistry, authority);
 	const state = (): SchemaState => {

package/src/{skill-execution.ts → workflow-execution.ts} RENAMED Viewed

@@ -26,9 +26,25 @@ const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 export interface InstantiateSkillWorkflowInput {
 	runId?: string;
 	arguments?: Record<string, unknown>;
+	/** When set, names one blueprint task ref whose resolved real task id is returned as `entryTaskId` -- e.g. the first-in-reading-order step of a compiled Playbook, so the caller can focus it without recomputing the ref-to-id mapping externally. */
+	focusRef?: string;
 }
-export interface SkillWorkflowRunResult {
+/**
+ * Identifies who owns a materialized run for tagging purposes: which artifact gets the
+ * `triggers` edges to its root tasks, which extra-bag key records run lineage on each created
+ * artifact, and which label prefix scopes them. Defaults used by instantiateSkillWorkflow
+ * (ownerId: the skill's own id, extraKey: "skillRun", labelPrefix: "skill-run") are unchanged
+ * from before this was made pluggable -- a Playbook-compiled run supplies its own (playbook id,
+ * "playbookRun", "playbook-run") instead, the only thing that actually differs between the two.
+ */
+export interface WorkflowLineage {
+	ownerId: string;
+	extraKey: string;
+	labelPrefix: string;
+}
+export interface WorkflowRunResult {
 	skillId: string;
 	runId: string;
 	arguments: Record<string, SkillArgumentValue>;
@@ -41,6 +57,8 @@ export interface SkillWorkflowRunResult {
 	};
 	/** Real starting points: for a nested skill-call root step, that nested run's own root tasks (recursively), not just "all its tasks". */
 	rootTaskIds: string[];
+	/** Resolved from input.focusRef when supplied -- the one real task id a caller (e.g. Playbook invocation) should focus, undefined when focusRef was not requested or names an unknown ref. */
+	entryTaskId?: string;
 	/** Scoped to this definition's own directly-created tasks only -- nested runs' tasks are real, graph-linked, and visible via /tasks graph, but not folded into this projection. */
 	execution: TaskExecutionPlan;
 }
@@ -98,15 +116,15 @@ function renderDefinition(definition: SkillDefinition, arguments_: Record<string
 	return validateSkillDefinition(rendered);
 }
-function withRunLabel(labels: string[] | undefined, runId: string): string[] {
-	return [...new Set([...(labels ?? []), `skill-run:${runId}`])];
+function withRunLabel(labels: string[] | undefined, labelPrefix: string, runId: string): string[] {
+	return [...new Set([...(labels ?? []), `${labelPrefix}:${runId}`])];
 }
-function executionGraph(tasks: Artifact[], definition: SkillDefinition, ids: Map<string, string>): TaskGraph {
+function executionGraph(tasks: Artifact[], definition: SkillDefinition, ids: Map<string, string>, extraKey: string): TaskGraph {
 	const byRef = new Map(definition.blueprints.tasks.map((task) => [task.ref, task]));
 	const nodes: TaskNode[] = tasks.map((task) => {
-		const ref = task.extra["skillRun"] && typeof task.extra["skillRun"] === "object"
-			? (task.extra["skillRun"] as Record<string, unknown>)["ref"] as string
+		const ref = task.extra[extraKey] && typeof task.extra[extraKey] === "object"
+			? (task.extra[extraKey] as Record<string, unknown>)["ref"] as string
 			: "";
 		const blueprint = byRef.get(ref)!;
 		return {
@@ -120,7 +138,8 @@ function executionGraph(tasks: Artifact[], definition: SkillDefinition, ids: Map
 	return { nodes, rootIds: nodes.filter((node) => node.parentIds.length === 0).map((node) => node.task.id) };
 }
-type SkillWorkflowHistory = { events: TaskEventStore; scopes: TaskScopeStore; projectRoot: string; context?: TaskEventContext };
+/** projectRoot is optional -- skills.run always supplies one (workflow Skill runs are always project-scoped today), while a Playbook invocation may legitimately be ad hoc/cross-project (e.g. a lab-deploy playbook not tied to any one repo), landing its tasks in the same "unscoped" bucket Tasks.create already supports for a caller that omits projectRoot entirely. */
+export type WorkflowRunHistory = { events: TaskEventStore; scopes: TaskScopeStore; projectRoot?: string; context?: TaskEventContext };
 /**
  * Public entry point: wraps one complete pipeline run (including every nested sub-pipeline
@@ -133,8 +152,8 @@ export function instantiateSkillWorkflow(
 	artifacts: ArtifactStore,
 	skillId: string,
 	input: InstantiateSkillWorkflowInput = {},
-	history?: SkillWorkflowHistory,
-): SkillWorkflowRunResult {
+	history?: WorkflowRunHistory,
+): WorkflowRunResult {
 	const run = () => runWorkflowSteps(artifacts, skillId, input, history, new Set(), 0);
 	if (history) return history.events.atomic(run);
 	return requireAtomicArtifactStore(artifacts).atomic(run);
@@ -154,19 +173,53 @@ function runWorkflowSteps(
 	artifacts: ArtifactStore,
 	skillId: string,
 	input: InstantiateSkillWorkflowInput,
-	history: SkillWorkflowHistory | undefined,
+	history: WorkflowRunHistory | undefined,
 	ancestorSkillIds: ReadonlySet<string>,
 	depth: number,
-): SkillWorkflowRunResult {
+): WorkflowRunResult {
 	if (ancestorSkillIds.has(skillId)) throw new Error(`skill workflow nesting cycle includes "${skillId}"`);
 	if (depth > SKILL_WORKFLOW_MAX_NESTING_DEPTH) throw new Error(`skill workflow nesting exceeds ${SKILL_WORKFLOW_MAX_NESTING_DEPTH} levels`);
 	const nextAncestors = new Set([...ancestorSkillIds, skillId]);
 	const { definition } = requireWorkflowSkill(artifacts, skillId);
-	const projectRoot = history ? normalizeProjectRoot(history.projectRoot) : undefined;
+	return materializeWorkflowDefinition(
+		artifacts,
+		{ ownerId: skillId, extraKey: "skillRun", labelPrefix: "skill-run" },
+		definition,
+		input,
+		history,
+		nextAncestors,
+		depth,
+	);
+}
+/**
+ * The definition-materialization core, shared by workflow Skills (instantiateSkillWorkflow,
+ * via runWorkflowSteps above) and Playbook invocation (playbook-execution.ts): given an
+ * ALREADY-RESOLVED SkillDefinition -- fetched from a persisted Skill artifact for the Skill
+ * path, compiled in-memory from a Playbook's steps/trigger/arguments and its contains/
+ * depends_on composition tree for the Playbook path -- creates every blueprint artifact,
+ * wires dependsOn/parent/links, recurses into nested skill-call pipeline steps (a no-op for a
+ * Playbook-compiled definition, which never populates blueprints.skills), and tags every
+ * created artifact and the run's containing labels via `lineage` rather than a hardcoded
+ * "skillRun"/"skill-run" shape -- the only thing that differs between the two callers.
+ * `ancestorSkillIds`/`depth` are the same cycle/nesting-depth tracking runWorkflowSteps already
+ * enforced before this was extracted; a Playbook caller with no nested skill-calls to recurse
+ * into passes an empty set and depth 0 and never revisits this function itself.
+ */
+export function materializeWorkflowDefinition(
+	artifacts: ArtifactStore,
+	lineage: WorkflowLineage,
+	definition: SkillDefinition,
+	input: InstantiateSkillWorkflowInput,
+	history: WorkflowRunHistory | undefined,
+	ancestorSkillIds: ReadonlySet<string>,
+	depth: number,
+): WorkflowRunResult {
+	const { ownerId, extraKey, labelPrefix } = lineage;
+	const projectRoot = history?.projectRoot !== undefined ? normalizeProjectRoot(history.projectRoot) : undefined;
 	const arguments_ = resolveSkillArguments(definition, input.arguments);
 	const rendered = renderDefinition(definition, arguments_);
-	const runId = normalizeRunId(skillId, input.runId);
+	const runId = normalizeRunId(ownerId, input.runId);
 	const refs = [
 		...rendered.blueprints.docs.map(({ ref }) => ref),
 		...rendered.blueprints.rules.map(({ ref }) => ref),
@@ -194,22 +247,22 @@ function runWorkflowSteps(
 		title: blueprint.title,
 		body: blueprint.body,
 		subtype: blueprint.subtype,
-		labels: withRunLabel(blueprint.labels, runId),
-		extra: { ...(blueprint.extra ?? {}), skillRun: { id: runId, skillId, ref: blueprint.ref } },
+		labels: withRunLabel(blueprint.labels, labelPrefix, runId),
+		extra: { ...(blueprint.extra ?? {}), [extraKey]: { id: runId, ownerId, ref: blueprint.ref } },
 	}));
 	const rules = rendered.blueprints.rules.map((blueprint) => artifacts.create({
 		id: ids.get(blueprint.ref),
 		kind: "rule",
 		title: blueprint.title,
 		body: blueprint.body,
-		labels: withRunLabel(blueprint.labels, runId),
+		labels: withRunLabel(blueprint.labels, labelPrefix, runId),
 		extra: {
 			...(blueprint.extra ?? {}),
 			...(blueprint.condition ? { condition: blueprint.condition } : {}),
 			...(blueprint.action ? { action: blueprint.action } : {}),
 			...(blueprint.severity ? { severity: blueprint.severity } : {}),
-			skillRun: { id: runId, skillId, ref: blueprint.ref },
-			scope: { type: "skill-run", runId, taskIds },
+			[extraKey]: { id: runId, ownerId, ref: blueprint.ref },
+			scope: { type: labelPrefix, runId, taskIds },
 		},
 	}));
 	const tasks = rendered.blueprints.tasks.map((blueprint) => {
@@ -218,16 +271,16 @@ function runWorkflowSteps(
 			kind: "task",
 			title: blueprint.title,
 			body: blueprint.body,
-			labels: withRunLabel(blueprint.labels, runId),
-			extra: { ...(blueprint.extra ?? {}), skillRun: { id: runId, skillId, ref: blueprint.ref } },
+			labels: withRunLabel(blueprint.labels, labelPrefix, runId),
+			extra: { ...(blueprint.extra ?? {}), [extraKey]: { id: runId, ownerId, ref: blueprint.ref } },
 		});
 		if (history) {
-			history.scopes.assign(task.id, projectRoot, "cwd");
+			history.scopes.assign(task.id, projectRoot, projectRoot ? "cwd" : "unscoped");
 			history.events.append({
 				taskId: task.id,
 				type: "created",
 				actor: history.context?.actor ?? "system",
-				source: history.context?.source ?? "skill-run",
+				source: history.context?.source ?? labelPrefix,
 				toStatus: task.status as TaskStatus,
 				...(history.context?.sessionId === undefined ? {} : { sessionId: history.context.sessionId }),
 				...(history.context?.reason === undefined ? {} : { reason: history.context.reason }),
@@ -240,7 +293,7 @@ function runWorkflowSteps(
 	// nested run actually produced. stepTaskIds/stepRootTaskIds map EVERY step ref (task or
 	// skill-call) to the task id(s) it resolves to, so dependsOn/parent wiring below treats
 	// both kinds of step uniformly.
-	const nestedRuns: SkillWorkflowRunResult[] = [];
+	const nestedRuns: WorkflowRunResult[] = [];
 	const stepTaskIds = new Map<string, string[]>(tasks.map((task, index) => [rendered.blueprints.tasks[index]!.ref, [task.id]]));
 	const stepRootTaskIds = new Map<string, string[]>(
 		tasks.map((task, index) => [rendered.blueprints.tasks[index]!.ref, (rendered.blueprints.tasks[index]!.dependsOn?.length ?? 0) === 0 ? [task.id] : []]),
@@ -251,7 +304,7 @@ function runWorkflowSteps(
 			call.skillId,
 			{ runId: `${runId}-${call.ref}`, arguments: call.arguments },
 			history,
-			nextAncestors,
+			ancestorSkillIds,
 			depth + 1,
 		);
 		nestedRuns.push(nested);
@@ -298,14 +351,14 @@ function runWorkflowSteps(
 			.flatMap((call) => stepRootTaskIds.get(call.ref) ?? []),
 	];
 	for (const task of rendered.blueprints.tasks) {
-		if ((task.dependsOn?.length ?? 0) === 0) artifacts.link({ from: skillId, relation: "triggers", to: ids.get(task.ref)! });
+		if ((task.dependsOn?.length ?? 0) === 0) artifacts.link({ from: ownerId, relation: "triggers", to: ids.get(task.ref)! });
 	}
 	for (const call of rendered.blueprints.skills as SkillCallBlueprint[]) {
-		if ((call.dependsOn?.length ?? 0) === 0) artifacts.link({ from: skillId, relation: "triggers", to: call.skillId });
+		if ((call.dependsOn?.length ?? 0) === 0) artifacts.link({ from: ownerId, relation: "triggers", to: call.skillId });
 	}
 	return {
-		skillId,
+		skillId: ownerId,
 		runId,
 		arguments: arguments_,
 		created: {
@@ -315,6 +368,7 @@ function runWorkflowSteps(
 			skillRuns: [...nestedRuns.map((run) => run.runId), ...nestedRuns.flatMap((run) => run.created.skillRuns)],
 		},
 		rootTaskIds,
-		execution: projectTaskExecution(executionGraph(tasks, rendered, ids)),
+		...(input.focusRef !== undefined && ids.has(input.focusRef) ? { entryTaskId: ids.get(input.focusRef)! } : {}),
+		execution: projectTaskExecution(executionGraph(tasks, rendered, ids, extraKey)),
 	};
 }