@danypops/papyrus 0.36.1 → 0.38.0

package/package.json

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

package/src/artifact-subtree.ts

@@ -0,0 +1,54 @@
+/**
+ * Bulk trash of a `contains` subtree, any artifact kind -- a whole materialized Task run
+ * (root container + steps + nested playbook children) or a Playbook's own nested-playbook
+ * tree can be moved to trash in one call instead of enumerating every id by hand. Mirrors
+ * Tasks.cancelSubtree's traversal shape but performs trash(), not a lifecycle transition,
+ * so it applies to any kind that participates in `contains` (task, playbook), not just Task.
+ */
+import { ARTIFACT_REMOVE_SUBTREE_MAX_NODES } from "./constants.ts";
+import type { ArtifactEventContext } from "./domain/artifact-event.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+import type { ArtifactTrashStore } from "./ports/artifact-trash-store.ts";
+
+export interface RemoveSubtreeResult {
+	removed: string[];
+	/** Already trashed -- a real no-op, not an error, matching trash()/restore()'s own idempotence elsewhere. */
+	skipped: string[];
+}
+
+/**
+ * Trashes `id` and every artifact reachable by following `contains` edges outward from it,
+ * transitively. An already-trashed node is skipped rather than re-trashed (trash() itself is
+ * idempotent, but skipping keeps the result's `removed` list meaningful -- only nodes newly
+ * moved to trash by this call). A node that is the live Task Focus in some scope still throws
+ * (the same guard trash() always enforces for a single artifact) rather than being silently
+ * skipped -- an active Focus is a real conflict to surface, not routine already-done state.
+ */
+export function removeArtifactSubtree(
+	store: ArtifactStore & ArtifactTrashStore,
+	id: string,
+	options: { reason?: string; context?: ArtifactEventContext } = {},
+): RemoveSubtreeResult {
+	if (!store.get(id)) throw new Error(`artifact "${id}" not found`);
+	const visited = new Set<string>();
+	const queue = [id];
+	const removed: string[] = [];
+	const skipped: string[] = [];
+	while (queue.length > 0) {
+		const current = queue.shift()!;
+		if (visited.has(current)) continue;
+		visited.add(current);
+		if (visited.size > ARTIFACT_REMOVE_SUBTREE_MAX_NODES) throw new Error(`remove_subtree exceeds ${ARTIFACT_REMOVE_SUBTREE_MAX_NODES} artifacts`);
+		const childIds = store.relationships({ artifactIds: [current] })
+			.filter((edge) => edge.from === current && edge.relation === "contains")
+			.map((edge) => edge.to);
+		queue.push(...childIds);
+		if (store.trashStatus(current)) {
+			skipped.push(current);
+			continue;
+		}
+		store.trash(current, { reason: options.reason, context: options.context });
+		removed.push(current);
+	}
+	return { removed, skipped };
+}

package/src/cli.ts

@@ -83,6 +83,7 @@ const USAGE = `Usage:
   papyrus artifact query [--kind <kind>] [--status <status>] [--text <query>] [--limit <count>] [--json]
   papyrus artifact show <id> [--depth <n>] [--max-nodes <n>] [--json]
   papyrus artifact remove <id> [--reason <text>] [--json]
+  papyrus artifact remove-subtree <id> [--reason <text>] [--json]
   papyrus artifact restore <id> [--json]
   papyrus artifact trash-status <id> [--json]
   papyrus artifact trash-list [--json]
@@ -169,6 +170,7 @@ const USAGE = `Usage:
   papyrus tasks reject <id> [--session-id <id>] [--json]
   papyrus tasks retry <id> [--session-id <id>] [--json]
   papyrus tasks cancel <id> [--session-id <id>] [--json]
+  papyrus tasks cancel-subtree <id> [--session-id <id>] [--json]
   papyrus tasks depend <id> <prerequisite-id> [--reason <reason>] [--session-id <id>] [--json]
   papyrus tasks undepend <id> <prerequisite-id> [--reason <reason>] [--session-id <id>] [--json]
   papyrus tasks contain <parent-id> <child-id> [--reason <reason>] [--session-id <id>] [--json]
@@ -1022,6 +1024,13 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 			human = `Trashed ${record.artifactId}: eligible for purge at ${record.purgeAfter}`;
 			break;
 		}
+		case "remove-subtree": {
+			if (!id) throw new Error("artifact remove-subtree requires exactly one artifact id");
+			const outcome = await client.call<Record<string, unknown>, { removed: string[]; skipped: string[] }>("artifact.remove_subtree", { id, reason });
+			result = outcome;
+			human = `Trashed ${outcome.removed.length} artifact(s)${outcome.skipped.length > 0 ? `, skipped ${outcome.skipped.length} already-trashed` : ""}.`;
+			break;
+		}
 		case "restore": {
 			if (!id) throw new Error("artifact restore requires exactly one artifact id");
 			const outcome = await client.call<Record<string, unknown>, { restored: boolean }>("artifact.restore", { id });
@@ -1044,7 +1053,7 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 			break;
 		}
 		default:
-			throw new Error("artifact action must be create, query, show, remove, restore, trash-status, or trash-list");
+			throw new Error("artifact action must be create, query, show, remove, remove-subtree, restore, trash-status, or trash-list");
 	}
 	return json ? JSON.stringify(result) : human;
 }
@@ -1740,6 +1749,13 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 			human = `${action[0]!.toUpperCase()}${action.slice(1)}: ${artifactLabel(artifact)}`;
 			break;
 		}
+		case "cancel-subtree": {
+			if (!id || dependencyId) throw new Error("tasks cancel-subtree requires exactly one task id");
+			const outcome = await client.call<Record<string, unknown>, { canceled: string[]; skipped: string[] }>("tasks.cancel_subtree", { id, actor: "user", source: "cli", ...sessionScope });
+			result = outcome;
+			human = `Canceled ${outcome.canceled.length} task(s)${outcome.skipped.length > 0 ? `, skipped ${outcome.skipped.length} already-terminal` : ""}.`;
+			break;
+		}
 		case "depend": {
 			if (!id || !dependencyId || positional.length !== 3) throw new Error("tasks depend requires a task id and prerequisite id");
 			const artifact = await client.call<Record<string, unknown>, CliArtifact>("tasks.depend", {
@@ -1759,7 +1775,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 			break;
 		}
 		default:
-			throw new Error("tasks action must be create, list, show, active, focused, focus, pause, unpause, clear-focus, update, graph, plan, context, history, scope, assign-project, complete, start, submit, reject, retry, cancel, depend, undepend, contain, uncontain, run-gates, set-checklist, or set-gates");
+			throw new Error("tasks action must be create, list, show, active, focused, focus, pause, unpause, clear-focus, update, graph, plan, context, history, scope, assign-project, complete, start, submit, reject, retry, cancel, cancel-subtree, depend, undepend, contain, uncontain, run-gates, set-checklist, or set-gates");
 	}
 	return json ? JSON.stringify(result) : human;
 }

package/src/constants.ts

@@ -121,6 +121,11 @@ export const PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH = 500;
  */
 export const PLAYBOOK_INVOCATION_MAX_CREATED_TASKS = 200;
 
+/** Tasks.cancelSubtree walks `contains` edges transitively (a whole materialized playbook run can be torn down in one call instead of enumerating every task id by hand) -- bounded the same way PLAYBOOK_INVOCATION_MAX_CREATED_TASKS bounds the forward direction. */
+export const TASK_CANCEL_SUBTREE_MAX_NODES = 500;
+/** artifact.remove_subtree walks `contains` transitively across any artifact kind (a task tree, or a playbook's own nested-playbook children) -- same bound rationale as TASK_CANCEL_SUBTREE_MAX_NODES, kept separate since the two traversals serve different operations. */
+export const ARTIFACT_REMOVE_SUBTREE_MAX_NODES = 500;
+
 /**
  * At the core, a workflow Skill creates Tasks and begins a pipeline -- an Ansible playbook or
  * a Jenkins job, not just a text prompt. A pipeline step can itself trigger another workflow

package/src/modules/tasks.ts

@@ -90,7 +90,7 @@ export const TASKS_OPERATION_NAMES = [
 	"tasks.create", "tasks.update", "tasks.list", "tasks.graph", "tasks.plan", "tasks.show", "tasks.history",
 	"tasks.scope", "tasks.set_scope", "tasks.assign_project", "tasks.active", "tasks.focused", "tasks.focus",
 	"tasks.pause", "tasks.unpause", "tasks.clear_focus", "tasks.start", "tasks.submit", "tasks.complete",
-	"tasks.run_gates", "tasks.set_checklist", "tasks.set_gates", "tasks.context", "tasks.reject", "tasks.retry", "tasks.cancel",
+	"tasks.run_gates", "tasks.set_checklist", "tasks.set_gates", "tasks.context", "tasks.reject", "tasks.retry", "tasks.cancel", "tasks.cancel_subtree",
 	"tasks.depend", "tasks.undepend", "tasks.contain", "tasks.uncontain", "tasks.reap_stale_focus",
 	"tasks.claim", "tasks.heartbeat_lease", "tasks.release_lease", "tasks.lease", "tasks.reap_stale_leases", "tasks.event_feed",
 ] as const;
@@ -169,6 +169,7 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionI
 		define("tasks.reject", (input: OperationInput) => tasks.transition(string(input, "id"), "reject", eventContext(input))),
 		define("tasks.retry", (input: OperationInput) => tasks.transition(string(input, "id"), "retry", eventContext(input))),
 		define("tasks.cancel", (input: OperationInput) => tasks.transition(string(input, "id"), "cancel", eventContext(input))),
+		define("tasks.cancel_subtree", (input: OperationInput) => tasks.cancelSubtree(string(input, "id"), eventContext(input))),
 		define("tasks.depend", (input: OperationInput) => tasks.depend(string(input, "id"), string(input, "dependency_id"), eventContext(input))),
 		define("tasks.undepend", (input: OperationInput) => tasks.undepend(string(input, "id"), string(input, "dependency_id"), eventContext(input))),
 		define("tasks.contain", (input: OperationInput) => tasks.contain(string(input, "parent_id"), string(input, "child_id"), eventContext(input))),

package/src/playbook-definition.ts

@@ -42,10 +42,17 @@ export interface CompiledPlaybook {
 	externalLinks: PlaybookExternalLink[];
 }
 
+/** Trashed but not yet purged: artifacts.get() still returns it (trash is separate, orthogonal metadata -- "still directly showable"), so a stale composition edge left behind by remove/uncontain would otherwise resolve straight through and get compiled in. query() excludes trashed artifacts by default; use that instead of get() for every existence check a compiler makes. */
+function nonTrashedPlaybookIds(artifacts: ArtifactStore, ids: string[]): Set<string> {
+	if (ids.length === 0) return new Set();
+	return new Set(artifacts.query({ ids, kind: "playbook" }).map((artifact) => artifact.id));
+}
+
 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`);
+	if (!nonTrashedPlaybookIds(artifacts, [id]).has(id)) throw new Error(`playbook artifact "${id}" is trashed`);
 	return playbook;
 }
 
@@ -121,12 +128,13 @@ function compileNode(
 	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 composablePlaybookIds = nonTrashedPlaybookIds(artifacts, edges.filter((edge) => edge.from === playbookId).map((edge) => edge.to));
 	const prerequisiteIds = edges.filter((edge) => edge.from === playbookId && edge.relation === "depends_on").map((edge) => edge.to)
-		.filter((id) => artifacts.get(id)?.kind === "playbook");
+		.filter((id) => composablePlaybookIds.has(id));
 	const nestedIds = edges.filter((edge) => edge.from === playbookId && edge.relation === "contains").map((edge) => edge.to)
-		.filter((id) => artifacts.get(id)?.kind === "playbook");
+		.filter((id) => composablePlaybookIds.has(id));
 	for (const edge of edges) {
-		const isComposingFrom = edge.from === playbookId && (edge.relation === "contains" || edge.relation === "depends_on") && artifacts.get(edge.to)?.kind === "playbook";
+		const isComposingFrom = edge.from === playbookId && (edge.relation === "contains" || edge.relation === "depends_on") && composablePlaybookIds.has(edge.to);
 		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 });

package/src/service.ts

@@ -1,6 +1,7 @@
 import { SERVICE_MAX_BODY_BYTES, SQLITE_SCHEMA_VERSION } from "./constants.ts";
 import { VERSION } from "./version.ts";
 import { migrateDb, openDb, schemaVersion } from "./db.ts";
+import { removeArtifactSubtree } from "./artifact-subtree.ts";
 import { SQLiteArtifactStore } from "./adapters/sqlite-artifact-store.ts";
 import { SQLiteGateRunner } from "./adapters/sqlite-gate-runner.ts";
 import { SQLiteArtifactScopeStore } from "./adapters/sqlite-artifact-scope-store.ts";
@@ -57,7 +58,7 @@ import { SQLiteDiscussionRoundStore } from "./adapters/sqlite-discussion-round-s
  */
 const COMPOSITION_ROOT_OPERATION_NAMES = [
 	"system.migrate", "artifact.create", "artifact.query", "artifact.show",
-	"artifact.remove", "artifact.restore", "artifact.trash_status", "artifact.trash_list",
+	"artifact.remove", "artifact.remove_subtree", "artifact.restore", "artifact.trash_status", "artifact.trash_list",
 	"graph.link", "graph.unlink", "graph.tree", "graph.status", "graph.history", "gates.run",
 	"rules.injectable", "skills.instantiate",
 ] as const;
@@ -280,6 +281,7 @@ function handlers(
 			maxNodes: optionalNumber(input, "max_nodes") ?? optionalNumber(input, "maxNodes"),
 		}),
 		"artifact.remove": (input) => artifacts.trash(string(input, "id"), { reason: optionalString(input, "reason"), context: eventContext(input) }),
+		"artifact.remove_subtree": (input) => removeArtifactSubtree(artifacts, string(input, "id"), { reason: optionalString(input, "reason"), context: eventContext(input) }),
 		"artifact.restore": (input) => artifacts.restore(string(input, "id"), eventContext(input)),
 		"artifact.trash_status": (input) => artifacts.trashStatus(string(input, "id")),
 		"artifact.trash_list": () => artifacts.listTrash(),
@@ -359,6 +361,7 @@ function handlers(
 		"tasks.reject": forwardToModule("tasks.reject"),
 		"tasks.retry": forwardToModule("tasks.retry"),
 		"tasks.cancel": forwardToModule("tasks.cancel"),
+		"tasks.cancel_subtree": forwardToModule("tasks.cancel_subtree"),
 		"tasks.depend": forwardToModule("tasks.depend"),
 		"tasks.undepend": forwardToModule("tasks.undepend"),
 		"tasks.contain": forwardToModule("tasks.contain"),

package/src/task-service.ts

@@ -1,5 +1,6 @@
 import {
 	TASK_BODY_MAX_LENGTH,
+	TASK_CANCEL_SUBTREE_MAX_NODES,
 	TASK_EXECUTION_MAX_DEGREE,
 	TASK_EXECUTION_MAX_EDGES,
 	TASK_EXECUTION_MAX_NODES,
@@ -459,6 +460,41 @@ export class Tasks {
 		});
 	}
 
+	/**
+	 * Cancels a task and every task in its containment subtree (`contains` edges, transitively) --
+	 * a whole materialized playbook/skill run can be torn down in one call instead of enumerating
+	 * every task id by hand. A task already in a terminal state (done/canceled) is skipped, not
+	 * treated as an error, matching how a mixed-status subtree is the normal case (some steps
+	 * genuinely finished before the rest needed to be abandoned). Does not follow `depends_on` --
+	 * only containment cascades, a prerequisite is a different unit of work.
+	 */
+	cancelSubtree(id: string, context: TaskEventContext = {}): { canceled: string[]; skipped: string[] } {
+		this.require(id);
+		const visited = new Set<string>();
+		const queue = [id];
+		const canceled: string[] = [];
+		const skipped: string[] = [];
+		while (queue.length > 0) {
+			const current = queue.shift()!;
+			if (visited.has(current)) continue;
+			visited.add(current);
+			if (visited.size > TASK_CANCEL_SUBTREE_MAX_NODES) throw new Error(`cancelSubtree exceeds ${TASK_CANCEL_SUBTREE_MAX_NODES} tasks`);
+			const task = this.artifacts.get(current);
+			if (!task || task.kind !== "task") continue;
+			const childIds = this.artifacts.relationships({ artifactIds: [current] })
+				.filter((edge) => edge.from === current && edge.relation === "contains")
+				.map((edge) => edge.to);
+			queue.push(...childIds);
+			if (task.status === "done" || task.status === "canceled") {
+				skipped.push(current);
+				continue;
+			}
+			this.transition(current, "cancel", context);
+			canceled.push(current);
+		}
+		return { canceled, skipped };
+	}
+
 	complete(id: string, context: TaskEventContext = {}, options: TaskCompletionOptions = {}): TaskCompletion {
 		const task = this.requireReview(id);
 		this.requireNotBlocked(task);