@danypops/papyrus 0.41.0 → 0.42.1

package/src/playbook-execution.ts

@@ -1,18 +1,23 @@
 /**
  * playbook-execution.ts — playbooks.invoke's real implementation: compile the Playbook's
- * composition tree (playbook-definition.ts) into a SkillDefinition, materialize it through
+ * composition tree (playbook-definition.ts) into a BlueprintDefinition, 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 type { BlueprintArgumentValue } from "./domain/blueprint-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";
+import {
+	applyPlaybookExternalLinks,
+	materializeWorkflowDefinition,
+	resolveRefToTaskId,
+	type WorkflowRunHistory,
+} from "./workflow-execution.ts";
 
 export interface InvokePlaybookInput {
 	runId?: string;
@@ -22,7 +27,7 @@ export interface InvokePlaybookInput {
 export interface PlaybookInvocationResult {
 	playbookId: string;
 	runId: string;
-	arguments: Record<string, SkillArgumentValue>;
+	arguments: Record<string, BlueprintArgumentValue>;
 	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). */
@@ -36,24 +41,15 @@ export interface PlaybookMissingArguments {
 	missingArguments: string[];
 }
 
-function missingRequiredInputs(inputs: Record<string, { required?: boolean; default?: SkillArgumentValue }>, provided: Record<string, unknown>): string[] {
+function missingRequiredInputs(
+	inputs: Record<string, { required?: boolean; default?: BlueprintArgumentValue }>,
+	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,
@@ -64,7 +60,9 @@ export function invokePlaybook(
 	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));
+	const atomic = history
+		? history.events.atomic.bind(history.events)
+		: requireAtomicArtifactStore(artifacts).atomic.bind(requireAtomicArtifactStore(artifacts));
 	return atomic(() => {
 		const result = materializeWorkflowDefinition(
 			artifacts,
@@ -75,13 +73,8 @@ export function invokePlaybook(
 			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 });
-		}
+		const refToTaskId = resolveRefToTaskId(artifacts, result.created.tasks, "playbookRun");
+		applyPlaybookExternalLinks(artifacts, compiled.externalLinks, refToTaskId);
 		return {
 			playbookId,
 			runId: result.runId,

package/src/ports/artifact-scope-store.ts

@@ -1,7 +1,7 @@
 import type { TaskScopeSource } from "../domain/task-scope.ts";
 
 /**
- * Project scoping for Docs/Rules/Skills, mirroring TaskScopeStore's shape (task_scopes) but
+ * Project scoping for Docs/Rules/Playbooks, mirroring TaskScopeStore's shape (task_scopes) but
  * kept as its own table/port rather than folding non-Task kinds into Task-named
  * infrastructure. TaskScopeSource ("cwd" | "explicit" | "unscoped") is already kind-agnostic
  * and reused as-is -- no reason to redefine the same three values under a new name.

package/src/ports/note-event-store.ts

@@ -1,10 +1,10 @@
 import {
-	normalizeNoteHistoryQuery,
-	validateNoteEvent,
 	type AppendNoteEvent,
 	type NoteEvent,
 	type NoteHistoryPage,
 	type NoteHistoryQuery,
+	normalizeNoteHistoryQuery,
+	validateNoteEvent,
 } from "../domain/note-event.ts";
 
 export interface NoteEventStore {
@@ -30,8 +30,10 @@ export class InMemoryNoteEventStore implements NoteEventStore {
 	history(noteId: string, query: NoteHistoryQuery = {}): NoteHistoryPage {
 		const { direction, limit, cursor } = normalizeNoteHistoryQuery(query);
 		const ordered = this.events
-			.filter((event) => event.noteId === noteId && (cursor === undefined || (direction === "desc" ? event.id < cursor : event.id > cursor)))
-			.sort((left, right) => direction === "desc" ? right.id - left.id : left.id - right.id);
+			.filter(
+				(event) => event.noteId === noteId && (cursor === undefined || (direction === "desc" ? event.id < cursor : event.id > cursor)),
+			)
+			.sort((left, right) => (direction === "desc" ? right.id - left.id : left.id - right.id));
 		const events = ordered.slice(0, limit);
 		return { events, ...(ordered.length > limit ? { nextCursor: events.at(-1)!.id } : {}) };
 	}

package/src/ports/task-event-store.ts

@@ -1,13 +1,13 @@
 import {
+	type AppendTaskEvent,
 	normalizeTaskEventFeedQuery,
 	normalizeTaskHistoryQuery,
-	validateTaskEvent,
-	type AppendTaskEvent,
 	type TaskEvent,
 	type TaskEventFeedPage,
 	type TaskEventFeedQuery,
 	type TaskHistoryPage,
 	type TaskHistoryQuery,
+	validateTaskEvent,
 } from "../domain/task-event.ts";
 
 export interface TaskEventStore {
@@ -25,8 +25,9 @@ export class InMemoryTaskEventStore implements TaskEventStore {
 	atomic<T>(operation: () => T): T {
 		const length = this.events.length;
 		const nextId = this.nextId;
-		try { return operation(); }
-		catch (error) {
+		try {
+			return operation();
+		} catch (error) {
 			this.events.length = length;
 			this.nextId = nextId;
 			throw error;
@@ -47,8 +48,10 @@ export class InMemoryTaskEventStore implements TaskEventStore {
 	history(taskId: string, query: TaskHistoryQuery = {}): TaskHistoryPage {
 		const { direction, limit, cursor } = normalizeTaskHistoryQuery(query);
 		const ordered = this.events
-			.filter((event) => event.taskId === taskId && (cursor === undefined || (direction === "desc" ? event.id < cursor : event.id > cursor)))
-			.sort((left, right) => direction === "desc" ? right.id - left.id : left.id - right.id);
+			.filter(
+				(event) => event.taskId === taskId && (cursor === undefined || (direction === "desc" ? event.id < cursor : event.id > cursor)),
+			)
+			.sort((left, right) => (direction === "desc" ? right.id - left.id : left.id - right.id));
 		const events = ordered.slice(0, limit);
 		return { events, ...(ordered.length > limit ? { nextCursor: events.at(-1)!.id } : {}) };
 	}

package/src/ports/task-focus-store.ts

@@ -37,7 +37,9 @@ export interface TaskFocusStore {
 export class InMemoryTaskFocusStore implements TaskFocusStore {
 	private readonly state = new Map<string, TaskFocusState>();
 
-	get(scope?: string): TaskFocusState | undefined { return this.state.get(normalizeFocusScope(scope)); }
+	get(scope?: string): TaskFocusState | undefined {
+		return this.state.get(normalizeFocusScope(scope));
+	}
 
 	set(taskId: string, scope?: string): TaskFocusState {
 		const key = normalizeFocusScope(scope);
@@ -51,7 +53,12 @@ export class InMemoryTaskFocusStore implements TaskFocusStore {
 		const key = normalizeFocusScope(scope);
 		const current = this.state.get(key);
 		if (current?.taskId !== taskId) throw new Error(`task "${taskId}" is not focused`);
-		const focus: TaskFocusState = { ...current, status: "paused", updatedAt: new Date().toISOString(), ...(reason ? { pauseReason: reason } : {}) };
+		const focus: TaskFocusState = {
+			...current,
+			status: "paused",
+			updatedAt: new Date().toISOString(),
+			...(reason ? { pauseReason: reason } : {}),
+		};
 		this.state.set(key, focus);
 		return focus;
 	}
@@ -79,7 +86,10 @@ export class InMemoryTaskFocusStore implements TaskFocusStore {
 	reapStale(olderThanIso: string): number {
 		let removed = 0;
 		for (const [key, focus] of this.state) {
-			if (focus.updatedAt < olderThanIso) { this.state.delete(key); removed++; }
+			if (focus.updatedAt < olderThanIso) {
+				this.state.delete(key);
+				removed++;
+			}
 		}
 		return removed;
 	}
@@ -88,7 +98,10 @@ export class InMemoryTaskFocusStore implements TaskFocusStore {
 		let oldestKey: string | undefined;
 		let oldestAt: string | undefined;
 		for (const [key, focus] of this.state) {
-			if (oldestAt === undefined || focus.updatedAt < oldestAt) { oldestKey = key; oldestAt = focus.updatedAt; }
+			if (oldestAt === undefined || focus.updatedAt < oldestAt) {
+				oldestKey = key;
+				oldestAt = focus.updatedAt;
+			}
 		}
 		if (oldestKey !== undefined) this.state.delete(oldestKey);
 	}

package/src/ports/task-lease-store.ts

@@ -1,5 +1,5 @@
 import { TASK_LEASE_DEFAULT_TTL_MS } from "../constants.ts";
-import { isLeaseExpired, validateLeaseNote, validateLeaseOwner, validateLeaseTtlMs, type TaskLease } from "../domain/task-lease.ts";
+import { isLeaseExpired, type TaskLease, validateLeaseNote, validateLeaseOwner, validateLeaseTtlMs } from "../domain/task-lease.ts";
 
 export interface TaskLeaseStore {
 	/**
@@ -51,7 +51,8 @@ export class InMemoryTaskLeaseStore implements TaskLeaseStore {
 		const nowIso = new Date().toISOString();
 		const current = this.leases.get(taskId);
 		if (!current || isLeaseExpired(current, nowIso)) throw new Error(`task "${taskId}" has no live lease to renew`);
-		if (current.owner !== owner || current.token !== token) throw new Error(`lease for task "${taskId}" is held by a different owner/token`);
+		if (current.owner !== owner || current.token !== token)
+			throw new Error(`lease for task "${taskId}" is held by a different owner/token`);
 		const renewed: TaskLease = { ...current, leaseExpiresAt: new Date(Date.now() + ttlMs).toISOString(), heartbeatAt: nowIso };
 		this.leases.set(taskId, renewed);
 		return renewed;
@@ -61,7 +62,8 @@ export class InMemoryTaskLeaseStore implements TaskLeaseStore {
 		const nowIso = new Date().toISOString();
 		const current = this.leases.get(taskId);
 		if (!current || isLeaseExpired(current, nowIso)) return { released: false };
-		if (current.owner !== owner || current.token !== token) throw new Error(`lease for task "${taskId}" is held by a different owner/token`);
+		if (current.owner !== owner || current.token !== token)
+			throw new Error(`lease for task "${taskId}" is held by a different owner/token`);
 		this.leases.delete(taskId);
 		return { released: true };
 	}
@@ -75,7 +77,10 @@ export class InMemoryTaskLeaseStore implements TaskLeaseStore {
 	reapExpired(olderThanIso: string): number {
 		let removed = 0;
 		for (const [taskId, lease] of this.leases) {
-			if (lease.leaseExpiresAt < olderThanIso) { this.leases.delete(taskId); removed++; }
+			if (lease.leaseExpiresAt < olderThanIso) {
+				this.leases.delete(taskId);
+				removed++;
+			}
 		}
 		return removed;
 	}

package/src/ports/task-scope-store.ts

@@ -18,7 +18,9 @@ export class InMemoryTaskScopeStore implements TaskScopeStore {
 		return scope;
 	}
 
-	get(taskId: string): TaskProjectScope | undefined { return this.scopes.get(taskId); }
+	get(taskId: string): TaskProjectScope | undefined {
+		return this.scopes.get(taskId);
+	}
 
 	taskIds(projectRoot: string | undefined, limit: number): string[] {
 		return [...this.scopes.values()]