@danypops/papyrus 0.41.0 → 0.42.1

package/src/client.ts

@@ -2,7 +2,7 @@ import { spawn as spawnProcess } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { connectWithPolicy, spawnDetachedDaemon } from "@danypops/vehicle-client/daemon-client";
 import { DAEMON_CLIENT_TIMEOUT_MS, DAEMON_DIR_ENV, DAEMON_PROBE_TIMEOUT_MS } from "./constants.ts";
-import { daemonStateDir, readDaemonHandle, type DaemonHandle } from "./daemon-state.ts";
+import { type DaemonHandle, daemonStateDir, readDaemonHandle } from "./daemon-state.ts";
 import type { OperationName, SchemaState } from "./service.ts";
 
 export type FetchAdapter = (request: Request) => Promise<Response>;
@@ -26,7 +26,7 @@ export class PapyrusClient {
 			signal: init.signal ?? AbortSignal.timeout(this.timeoutMs),
 		});
 		const response = await this.fetchAdapter(request);
-		const body = await response.json() as { error?: string } & T;
+		const body = (await response.json()) as { error?: string } & T;
 		if (!response.ok) throw new Error(body.error ?? `Papyrus daemon HTTP ${response.status}`);
 		return body;
 	}
@@ -87,7 +87,10 @@ export interface ConnectPapyrusClientOptions {
  * failure (stale, not "never started") and is NOT auto-recovered here -- it still
  * throws its own actionable "restart manually" error, unchanged from before.
  */
-export async function connectPapyrusClient(dir: string = daemonStateDir(), options: ConnectPapyrusClientOptions = {}): Promise<PapyrusClient> {
+export async function connectPapyrusClient(
+	dir: string = daemonStateDir(),
+	options: ConnectPapyrusClientOptions = {},
+): Promise<PapyrusClient> {
 	return connectWithPolicy({
 		readHandle: () => readDaemonHandle(dir) ?? null,
 		buildClient: probedPapyrusClient,

package/src/constants.ts

@@ -7,7 +7,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 21;
+export const SQLITE_SCHEMA_VERSION = 23;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -97,22 +97,22 @@ export const SKILL_MAX_LINKS = 500;
 export const SKILL_MAX_RENDERED_BYTES = 1_048_576;
 
 /**
- * Skills are special: invoking one queries Papyrus for whatever it's actually graph-linked
- * to (existing Tasks/Rules/Docs via ordinary edges, not just its own static body/extra
- * fields), and a Skill can link to and invoke other Skills. Both traversals are bounded and
- * cycle-safe -- a skill-calls-skill edge cycle must not infinite-loop invocation, matching
- * the same cycle-safety discipline established by task dependency graphs and the
+ * Invoking a Playbook queries Papyrus for whatever it's actually graph-linked to (existing
+ * Tasks/Rules/Docs via ordinary edges, not just its own static body/extra fields), and a
+ * Playbook can link to and invoke other Playbooks. Both traversals are bounded and
+ * cycle-safe -- a playbook-calls-playbook edge cycle must not infinite-loop invocation,
+ * matching the same cycle-safety discipline established by task dependency graphs and the
  * (since-removed; see Doc "ConversationJournal design record") ConversationJournal domain's
  * own reply chains.
  */
-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;
+/** A Playbook argument's enum/default validation reuses SKILL_MAX_ENUM_VALUES directly (same value shape, no reason for a second bound). */
+/** One playbook's own steps array, before composition with any contained/depended-on playbook -- mirrors SKILL_MAX_BLUEPRINTS' role for a workflow Skill's flat blueprint list. */
+export const PLAYBOOK_MAX_STEPS = 100;
 /**
  * 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
@@ -289,57 +289,24 @@ export const TASK_RECONCILIATION_INSTRUCTION = [
 
 /** $XDG_DATA_HOME/papyrus/papyrus.db */
 export function dbPath(): string {
-	const xdg = process.env["XDG_DATA_HOME"] || `${process.env["HOME"]}/.local/share`;
+	const xdg = process.env.XDG_DATA_HOME || `${process.env.HOME}/.local/share`;
 	return `${xdg}/papyrus/papyrus.db`;
 }
 
-/**
- * Four purpose-built kinds — the enforced vocabulary.
- *
- * doc   = Knowledge — descriptive ("here is what the architecture looks like")
- * task  = Work — prescriptive action items with gates and checklists
- * rule  = Governance — context injection ("when doing X, follow Y").
- *         Maps to AGENTS.md semantics: active rules with inject:true are
- *         appended to the system prompt on before_agent_start.
- * skill = Parameterized workflow bundle — validated inputs render connected Task, Rule, and Doc collections.
- */
-export const SEED_KINDS = [
-	{ name: "doc", description: "Knowledge — descriptive reference (specs, decisions, research, designs)" },
-	{ name: "task", description: "Work — action items with gates, checklists, and dependencies" },
-	{ name: "rule", description: "Governance — context injection (when doing X, follow Y). Maps to AGENTS.md" },
-	{ name: "skill", description: "Parameterized workflow bundle — inputs and templates load deterministic tasks plus contextual rules and docs" },
-] as const;
-
-export const SEED_STATUSES = [
-	{ name: "draft", kind: "doc" },
-	{ name: "active", kind: "doc" },
-	{ name: "archived", kind: "doc" },
-	{ name: "todo", kind: "task" },
-	{ name: "in-progress", kind: "task" },
-	{ name: "review", kind: "task" },
-	{ name: "rejected", kind: "task" },
-	{ name: "done", kind: "task" },
-	{ name: "canceled", kind: "task" },
-	{ name: "active", kind: "rule" },
-	{ name: "deprecated", kind: "rule" },
-	{ name: "active", kind: "skill" },
-	{ name: "deprecated", kind: "skill" },
-] as const;
-
 /**
  * The initial status a newly created artifact of a kind gets when no caller-supplied
  * status is given. This must be an explicit, named mapping — never derived from row order
- * in the `statuses` table (SEED_STATUSES' listed order, or a migration's insertion order,
- * is not a semantic guarantee; a migrated database can freely have a different physical
- * row order for the same logical status set). Deriving "the default" from "whichever row
- * happens to be first by rowid" was the root cause of a real production defect where
- * migrated databases created new Tasks as done instead of todo.
+ * in the `statuses` table (a migration's insertion order is not a semantic guarantee; a
+ * migrated database can freely have a different physical row order for the same logical
+ * status set). Deriving "the default" from "whichever row happens to be first by rowid"
+ * was the root cause of a real production defect where migrated databases created new
+ * Tasks as done instead of todo.
  */
 export const DEFAULT_STATUS_BY_KIND: Readonly<Record<string, string>> = {
 	doc: "draft",
 	task: "todo",
 	rule: "active",
-	skill: "active",
+	playbook: "active",
 };
 
 /**
@@ -347,17 +314,28 @@ export const DEFAULT_STATUS_BY_KIND: Readonly<Record<string, string>> = {
  *
  * references:  source material (doc→doc, doc→task, doc→rule)
  * implements:  this work satisfies that (task→doc, task→rule)
- * follows:     this work obeys that (task→rule, task→skill)
- * depends_on:  DAG ordering (task→task)
- * documents:   describes (doc→task, doc→rule, doc→skill)
+ * follows:     this work obeys that (task→rule, task→playbook)
+ * depends_on:  DAG ordering (task→task, playbook→playbook)
+ * documents:   describes (doc→task, doc→rule, doc→playbook)
  * blocks:      blocking relationship (task→task)
  * supersedes:  replaces (doc→doc, rule→rule)
  * relates_to:  catch-all (any→any)
  * gates:       this rule gates that task (rule→task)
- * triggers:    this skill applies to that work (skill→task)
+ * triggers:    this playbook run applies to that work (playbook→task)
  */
 export const SEED_RELATIONS = [
-	"references", "implements", "follows", "depends_on",
-	"documents", "blocks", "supersedes", "relates_to",
-	"gates", "triggers", "contains", "part_of", "reply_to", "discusses",
+	"references",
+	"implements",
+	"follows",
+	"depends_on",
+	"documents",
+	"blocks",
+	"supersedes",
+	"relates_to",
+	"gates",
+	"triggers",
+	"contains",
+	"part_of",
+	"reply_to",
+	"discusses",
 ] as const;

package/src/daemon-state.ts

@@ -2,12 +2,7 @@ import { randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import {
-	DAEMON_DIR_ENV,
-	DAEMON_HOST,
-	DAEMON_PORT_FILE,
-	DAEMON_TOKEN_FILE,
-} from "./constants.ts";
+import { DAEMON_DIR_ENV, DAEMON_HOST, DAEMON_PORT_FILE, DAEMON_TOKEN_FILE } from "./constants.ts";
 
 export interface DaemonHandle {
 	baseUrl: string;
@@ -17,13 +12,10 @@ export interface DaemonHandle {
 	pid: number;
 }
 
-export function daemonStateDir(
-	env: Record<string, string | undefined> = process.env,
-	home: string = homedir(),
-): string {
+export function daemonStateDir(env: Record<string, string | undefined> = process.env, home: string = homedir()): string {
 	if (env[DAEMON_DIR_ENV]) return env[DAEMON_DIR_ENV];
-	if (env["XDG_RUNTIME_DIR"]) return join(env["XDG_RUNTIME_DIR"], "papyrus");
-	if (env["XDG_STATE_HOME"]) return join(env["XDG_STATE_HOME"], "papyrus");
+	if (env.XDG_RUNTIME_DIR) return join(env.XDG_RUNTIME_DIR, "papyrus");
+	if (env.XDG_STATE_HOME) return join(env.XDG_STATE_HOME, "papyrus");
 	return join(home, ".local", "state", "papyrus");
 }
 

package/src/daemon.ts

@@ -1,8 +1,8 @@
 import { PushChannel } from "@danypops/vehicle-server/push-channel";
-import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, WAL_CHECKPOINT_INTERVAL_MS, dbPath } from "./constants.ts";
+import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, dbPath, WAL_CHECKPOINT_INTERVAL_MS } from "./constants.ts";
 import { clearDaemonPort, daemonStateDir, loadOrCreateToken, writeDaemonPort } from "./daemon-state.ts";
+import { logEvent, vehicleLogger } from "./log.ts";
 import { createApp, createPapyrusService } from "./service.ts";
-import { logEvent } from "./log.ts";
 
 /**
  * Operations that never change what a Task-graph reader (the pi-papyrus widget's
@@ -13,8 +13,16 @@ import { logEvent } from "./log.ts";
  * silently-uncovered new mutation.
  */
 const TASK_READ_ONLY_OPERATIONS = new Set([
-	"tasks.active", "tasks.context", "tasks.event_feed", "tasks.focused",
-	"tasks.graph", "tasks.history", "tasks.list", "tasks.plan", "tasks.scope", "tasks.show",
+	"tasks.active",
+	"tasks.context",
+	"tasks.event_feed",
+	"tasks.focused",
+	"tasks.graph",
+	"tasks.history",
+	"tasks.list",
+	"tasks.plan",
+	"tasks.scope",
+	"tasks.show",
 ]);
 
 /** Start the supervised, long-running Papyrus service. */
@@ -31,6 +39,7 @@ export function serveMain(): void {
 				pushChannel.publish("tasks", { operation });
 			}
 		},
+		logger: vehicleLogger(),
 	});
 	const server = Bun.serve({
 		hostname: DAEMON_HOST,
@@ -49,10 +58,18 @@ export function serveMain(): void {
 	}
 	writeDaemonPort(stateDir, server.port);
 	const checkpointTimer = setInterval(() => {
-		try { service.checkpoint(); } catch (error) { logEvent("error", "checkpoint_failed", { message: error instanceof Error ? error.message : String(error) }); }
+		try {
+			service.checkpoint();
+		} catch (error) {
+			logEvent("error", "checkpoint_failed", { message: error instanceof Error ? error.message : String(error) });
+		}
 	}, WAL_CHECKPOINT_INTERVAL_MS);
 	const optimizeTimer = setInterval(() => {
-		try { service.optimize(); } catch (error) { logEvent("error", "optimize_failed", { message: error instanceof Error ? error.message : String(error) }); }
+		try {
+			service.optimize();
+		} catch (error) {
+			logEvent("error", "optimize_failed", { message: error instanceof Error ? error.message : String(error) });
+		}
 	}, DB_OPTIMIZE_INTERVAL_MS);
 	// Daily cadence (reusing DB_OPTIMIZE_INTERVAL_MS) is plenty against a 30-day staleness
 	// threshold (TASK_FOCUS_STALE_AFTER_MS) -- see clean-up-stale-per-session-task-focus-rows-
@@ -61,7 +78,9 @@ export function serveMain(): void {
 		try {
 			const removed = service.reapStaleFocus();
 			if (removed > 0) logEvent("info", "stale_focus_reaped", { removed });
-		} catch (error) { logEvent("error", "reap_stale_focus_failed", { message: error instanceof Error ? error.message : String(error) }); }
+		} catch (error) {
+			logEvent("error", "reap_stale_focus_failed", { message: error instanceof Error ? error.message : String(error) });
+		}
 	}, DB_OPTIMIZE_INTERVAL_MS);
 	// Same daily cadence: ARTIFACT_TRASH_RETENTION_MS is 30 days, so a daily sweep finds newly
 	// due artifacts promptly without needing its own tighter interval -- see domain/artifact-trash.ts.
@@ -69,7 +88,9 @@ export function serveMain(): void {
 		try {
 			const purged = service.purgeDueTrash();
 			if (purged > 0) logEvent("info", "artifact_trash_purged", { purged });
-		} catch (error) { logEvent("error", "purge_trash_failed", { message: error instanceof Error ? error.message : String(error) }); }
+		} catch (error) {
+			logEvent("error", "purge_trash_failed", { message: error instanceof Error ? error.message : String(error) });
+		}
 	}, DB_OPTIMIZE_INTERVAL_MS);
 	let stopping = false;
 	const shutdown = () => {
@@ -83,7 +104,8 @@ export function serveMain(): void {
 		service.close();
 		// .finally() re-throws rather than handling a rejection -- catching it first turns a bare
 		// unhandled-rejection warning into a real, queryable shutdown-failure log line.
-		void server.stop(true)
+		void server
+			.stop(true)
 			.catch((error) => logEvent("error", "server_stop_failed", { message: error instanceof Error ? error.message : String(error) }))
 			.finally(() => process.exit(0));
 	};