@danypops/papyrus 0.38.2 → 0.38.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.38.2",
+  "version": "0.38.4",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -35,6 +35,7 @@
   "files": ["src", "README.md"],
   "dependencies": {
     "@danypops/vehicle-core": "^0.1.1",
+    "@danypops/vehicle-client": "^0.1.1",
     "@danypops/vehicle-server": "^0.3.2"
   }
 }

package/src/client.ts

@@ -1,5 +1,8 @@
-import { DAEMON_CLIENT_TIMEOUT_MS, DAEMON_PROBE_TIMEOUT_MS } from "./constants.ts";
-import { daemonStateDir, readDaemonHandle } from "./daemon-state.ts";
+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 { OperationName, SchemaState } from "./service.ts";
 
 export type FetchAdapter = (request: Request) => Promise<Response>;
@@ -46,9 +49,7 @@ export class PapyrusClient {
 	}
 }
 
-export async function connectPapyrusClient(dir: string = daemonStateDir()): Promise<PapyrusClient> {
-	const handle = readDaemonHandle(dir);
-	if (!handle) throw new Error("Papyrus daemon is not running; install/start papyrus.service");
+async function probedPapyrusClient(handle: DaemonHandle): Promise<PapyrusClient> {
 	const probe = new PapyrusClient(handle.baseUrl, handle.token, (request) => fetch(request), DAEMON_PROBE_TIMEOUT_MS);
 	try {
 		await probe.health();
@@ -58,6 +59,54 @@ export async function connectPapyrusClient(dir: string = daemonStateDir()): Prom
 	}
 }
 
+/** packages/papyrus/src/cli.ts, resolved relative to this file's own installed location, not require.resolve('@danypops/papyrus') -- this module IS that package, no cross-package lookup needed. */
+function papyrusCliPath(): string {
+	return fileURLToPath(new URL("cli.ts", import.meta.url));
+}
+
+export interface ConnectPapyrusClientOptions {
+	/**
+	 * Environment passed to an auto-spawned daemon child. Defaults to the current
+	 * process.env. Always carries DAEMON_DIR_ENV=dir so the spawned child computes
+	 * the exact same state directory this call itself reads/polls -- without this,
+	 * a caller-supplied `dir` (every real test; production always uses the default
+	 * daemonStateDir(), which the child would derive identically on its own) would
+	 * silently diverge from wherever the child actually starts writing its handle.
+	 */
+	env?: Record<string, string | undefined>;
+}
+
+/**
+ * Transparently starts the daemon first if it is not already running -- matches
+ * every other daemon-backed ecosystem package that opted into auto-start (see
+ * @danypops/vehicle-client's connectWithPolicy doc comment: web-spider opts in,
+ * lector/pi-packed fail closed by design). Papyrus previously failed closed with
+ * "install/start papyrus.service", requiring a human to separately discover and
+ * run `papyrus service install` before the very first tool call could succeed.
+ * A handle file that exists but points at a dead/unreachable daemon is a distinct
+ * 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> {
+	return connectWithPolicy({
+		readHandle: () => readDaemonHandle(dir) ?? null,
+		buildClient: probedPapyrusClient,
+		autoStart: true,
+		spawn: () => {
+			spawnDetachedDaemon({
+				binPath: papyrusCliPath(),
+				args: ["serve"],
+				env: { ...(options.env ?? process.env), [DAEMON_DIR_ENV]: dir },
+				spawn: (command, args, spawnOptions) => {
+					const child = spawnProcess(command, args, spawnOptions);
+					child.unref();
+				},
+			});
+		},
+		fallbackMessage: "Papyrus daemon failed to start automatically; run `papyrus service install` or `papyrus serve` manually.",
+	});
+}
+
 export interface PushChannelTarget {
 	/** ws:// URL for the daemon's push-invalidation channel (see push-channel.ts in vehicle-server). */
 	url: string;

package/src/daemon-state.ts

@@ -12,6 +12,9 @@ import {
 export interface DaemonHandle {
 	baseUrl: string;
 	token: string;
+	host: string;
+	port: number;
+	pid: number;
 }
 
 export function daemonStateDir(
@@ -38,9 +41,9 @@ export function loadOrCreateToken(dir: string): string {
 	return token;
 }
 
-export function writeDaemonPort(dir: string, port: number): void {
+export function writeDaemonPort(dir: string, port: number, pid: number = process.pid): void {
 	mkdirSync(dir, { recursive: true });
-	writeFileSync(join(dir, DAEMON_PORT_FILE), `${port}\n`, { mode: 0o600 });
+	writeFileSync(join(dir, DAEMON_PORT_FILE), `${port}\n${pid}\n`, { mode: 0o600 });
 }
 
 export function clearDaemonPort(dir: string): void {
@@ -50,9 +53,14 @@ export function clearDaemonPort(dir: string): void {
 export function readDaemonHandle(dir: string): DaemonHandle | undefined {
 	try {
 		const token = readFileSync(join(dir, DAEMON_TOKEN_FILE), "utf8").trim();
-		const port = Number(readFileSync(join(dir, DAEMON_PORT_FILE), "utf8").trim());
+		const lines = readFileSync(join(dir, DAEMON_PORT_FILE), "utf8").trim().split("\n");
+		const port = Number(lines[0]);
+		// pid is absent for a handle written before this field existed -- 0 is a safe
+		// "unknown" sentinel (never a real pid), not a crash. Nothing currently reads
+		// pid to make a kill/staleness decision, so a stale 0 is inert, not unsafe.
+		const pid = lines[1] ? Number(lines[1]) : 0;
 		if (!token || !Number.isInteger(port) || port < 1 || port > 65_535) return undefined;
-		return { baseUrl: `http://${DAEMON_HOST}:${port}`, token };
+		return { baseUrl: `http://${DAEMON_HOST}:${port}`, token, host: DAEMON_HOST, port, pid };
 	} catch {
 		return undefined;
 	}

package/src/index.ts

@@ -24,6 +24,7 @@ export type { DiscussionAndRounds } from "./discussion-service.ts";
 export { NOTE_DISPOSITIONS } from "./note-service.ts";
 export type { OperationName, SchemaState } from "./service.ts";
 export type { WorkflowRunResult } from "./workflow-execution.ts";
+export type { PlaybookInvocationResult, PlaybookMissingArguments } from "./playbook-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";