dsh-agentic-pet 0.4.9 → 0.4.11

package/lib/index.js

@@ -1,12 +1,75 @@
-import { c as globalFilePath, d as readJsonl, f as readPetName, h as writePetName, i as installPetDriver, l as readAffectionRaw, m as writeGlobalJson, n as installPetService, p as writeAffectionRaw, r as petHome, s as eventsFile, u as readGlobalJson } from "./service-BZbhT92u.js";
+import { _ as writePetName, c as parseClock, d as readAffectionRaw, f as readGlobalJson, g as writeGlobalJson, h as writeAffectionRaw, i as voiceBindingSnapshot, l as eventsFile, m as readPetName, o as installPetService, p as readJsonl, s as petHome, t as installPetDriver, u as globalFilePath, v as isPetPreset, y as patchTouchesElectronBinding } from "./driver-BiSFFYXw.js";
 import { createRequire } from "node:module";
 import { execFileSync, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { appendFileSync, existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+const INSTALL_LOCK_MALFORMED_GRACE_MS = 6e4;
+/** True when `pid` names a live process (EPERM means it exists but is not ours). */
+function isProcessAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+/** Parse a lock file; `undefined` means empty/malformed. */
+function parseInstallLock(raw) {
+	try {
+		const value = JSON.parse(raw);
+		return typeof value === "object" && value !== null ? value : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Whether an existing lock may be taken over by a new installer.
+* A dead owner is stale immediately; a live owner keeps its lock until the
+* absolute cap (which also bounds PID-reuse false positives). A malformed
+* record gets a short grace for a concurrent writer, then goes stale.
+*/
+function installLockStale(raw, mtimeMs, now, alive = isProcessAlive) {
+	if (now - mtimeMs > 18e5) return true;
+	const record = raw === void 0 ? void 0 : parseInstallLock(raw);
+	const pid = typeof record?.pid === "number" ? record.pid : void 0;
+	if (pid === void 0) return now - mtimeMs > INSTALL_LOCK_MALFORMED_GRACE_MS;
+	return !alive(pid);
+}
+// lib/types/electron-runtime-status.js
+/**
+* Persisted state of the Electron runtime bootstrap, shared by the installer
+* path (writer) and the settings page (reader). The settings page is the only
+* user-visible surface while the first install downloads ~158 MB, so this
+* file is deliberately plain JSON in the pet home rather than process state.
+* @module dsh-agentic-pet/electron-runtime-status
+*/
+function electronRuntimeStatusPath(home) {
+	return join(home, "whale598", "electron-runtime.json");
+}
+function readElectronRuntimeStatus(home) {
+	try {
+		const parsed = JSON.parse(readFileSync(electronRuntimeStatusPath(home), "utf8"));
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		const status = parsed;
+		return typeof status.state === "string" ? status : void 0;
+	} catch {
+		return;
+	}
+}
+function writeElectronRuntimeStatus(home, status) {
+	try {
+		const path = electronRuntimeStatusPath(home);
+		mkdirSync(dirname(path), { recursive: true });
+		const tmp = `${path}.${String(process.pid)}.tmp`;
+		writeFileSync(tmp, `${JSON.stringify(status)}\n`, "utf8");
+		renameSync(tmp, path);
+	} catch {}
+}
 // lib/types/settings-page.js
 /**
 * The settings page's host half: local HTTP routes backing the desktop
@@ -46,6 +109,15 @@ const DEFAULT_SETTINGS = {
 		},
 		boundSessions: {}
 	},
+	rhythm: { quiet: null },
+	journal: {
+		enabled: true,
+		injectRecent: 3,
+		maxEntryChars: 120,
+		maxFileBytes: 262144,
+		allowUnboundAppend: false
+	},
+	presenceSummary: { enabled: false },
 	tts: { enabled: false },
 	debug: { cdp: false }
 };
@@ -111,6 +183,18 @@ function mergeSettings(current, patch) {
 		...DEFAULT_SETTINGS.innerVoice,
 		...current.innerVoice
 	};
+	const rhythm = {
+		quiet: null,
+		...current.rhythm
+	};
+	const journal = {
+		...DEFAULT_SETTINGS.journal,
+		...current.journal
+	};
+	const presenceSummary = {
+		enabled: false,
+		...current.presenceSummary
+	};
 	const debug = {
 		...DEFAULT_SETTINGS.debug,
 		...current.debug
@@ -173,6 +257,37 @@ function mergeSettings(current, patch) {
 			innerVoice.boundSessions = record;
 		}
 	}
+	const patchRhythm = patch.rhythm;
+	if (typeof patchRhythm === "object" && patchRhythm !== null) {
+		const r = patchRhythm;
+		if (r.quiet === null) rhythm.quiet = null;
+		else if (typeof r.quiet === "object" && r.quiet !== null) {
+			const q = r.quiet;
+			const currentQuiet = current.rhythm?.quiet ?? void 0;
+			rhythm.quiet = {
+				from: typeof q.from === "string" && parseClock(q.from) !== void 0 ? q.from : currentQuiet?.from ?? "01:00",
+				to: typeof q.to === "string" && parseClock(q.to) !== void 0 ? q.to : currentQuiet?.to ?? "09:00",
+				allowTouchReply: typeof q.allowTouchReply === "boolean" ? q.allowTouchReply : currentQuiet?.allowTouchReply ?? true
+			};
+		}
+	}
+	const patchJournal = patch.journal;
+	if (typeof patchJournal === "object" && patchJournal !== null) {
+		const j = patchJournal;
+		if (typeof j.enabled === "boolean") journal.enabled = j.enabled;
+		const inject = clampNumber(j.injectRecent, 1, 20);
+		if (inject !== void 0) journal.injectRecent = inject;
+		const chars = clampNumber(j.maxEntryChars, 40, 1e3);
+		if (chars !== void 0) journal.maxEntryChars = chars;
+		const bytes = clampNumber(j.maxFileBytes, 4096, 4194304);
+		if (bytes !== void 0) journal.maxFileBytes = bytes;
+		if (typeof j.allowUnboundAppend === "boolean") journal.allowUnboundAppend = j.allowUnboundAppend;
+	}
+	const patchPresence = patch.presenceSummary;
+	if (typeof patchPresence === "object" && patchPresence !== null) {
+		const p = patchPresence;
+		if (typeof p.enabled === "boolean") presenceSummary.enabled = p.enabled;
+	}
 	const patchDebug = patch.debug;
 	if (typeof patchDebug === "object" && patchDebug !== null) {
 		const d = patchDebug;
@@ -201,6 +316,9 @@ function mergeSettings(current, patch) {
 		...current,
 		proactivity,
 		innerVoice,
+		rhythm,
+		journal,
+		presenceSummary,
 		tts,
 		debug
 	};
@@ -225,7 +343,7 @@ function openPathInFileManager(path) {
 * @param ctx - plugin context inside the runtime.
 * @param home - the dsh home holding the settings/ledger/manifest files.
 */
-function installSettingsPage(ctx, home, pet) {
+function installSettingsPage(ctx, home, pet, control) {
 	const windowPath = globalFilePath(home, "pet-window.json");
 	/** Summarize EVERY live pet (id, online flag, normalized /status). */
 	const petStatus = async () => {
@@ -238,6 +356,56 @@ function installSettingsPage(ctx, home, pet) {
 	const readSettings = async () => {
 		return mergeSettings(await readGlobalJson(home, "pet-settings.json"), {});
 	};
+	/** Live header first, persisted header second. `checked:false` means the
+	* host exposed neither source — never turn that into a "missing session".
+	* `currentPreset` comes from the preset registry / projection cache, NOT
+	* from the immutable creation-time header field. */
+	const findSessionHeader = async (sessionId) => {
+		const getService = (name) => ctx.get(name);
+		const sessions = getService("sessions");
+		const agentPresets = getService("agentPresets");
+		const live = sessions?.get(sessionId);
+		if (live?.header !== void 0) {
+			let currentPreset;
+			try {
+				const preset = agentPresets?.presetForSession(live);
+				if (typeof preset === "string" && preset !== "") currentPreset = preset;
+			} catch {}
+			return {
+				header: live.header,
+				checked: true,
+				currentPreset
+			};
+		}
+		const persistence = getService("sessionPersistence");
+		if (persistence === void 0) return {
+			header: void 0,
+			checked: sessions !== void 0,
+			currentPreset: void 0
+		};
+		try {
+			const header = (await persistence.list()).find((snapshot) => snapshot.header?.id === sessionId)?.header;
+			let currentPreset;
+			if (header !== void 0) {
+				const cache = getService("sessionProjectionCache");
+				try {
+					const preset = cache?.cachedSnapshot(header)?.values?.agentPreset;
+					if (typeof preset === "string" && preset !== "") currentPreset = preset;
+				} catch {}
+			}
+			return {
+				header,
+				checked: true,
+				currentPreset
+			};
+		} catch {
+			return {
+				header: void 0,
+				checked: false,
+				currentPreset: void 0
+			};
+		}
+	};
 	const routeByPath = /* @__PURE__ */ new Map();
 	const route = (method, path, handler) => {
 		let handlers = routeByPath.get(path);
@@ -269,6 +437,18 @@ function installSettingsPage(ctx, home, pet) {
 		}
 		handlers.set(method, handler);
 	};
+	route("GET", "/api/pet-settings/binding-status", async (_req, res) => {
+		writeJson(res, 200, { status: voiceBindingSnapshot() });
+	});
+	route("POST", "/api/pet-settings/binding-test", async (req, res) => {
+		if (control === void 0) {
+			writeJson(res, 503, { error: "driver control unavailable" });
+			return;
+		}
+		const body = await readJsonBody(req);
+		const petId = typeof body?.petId === "string" && body.petId !== "" ? body.petId : "electron";
+		writeJson(res, 200, await control.testBinding(petId));
+	});
 	route("GET", "/api/pet-settings/read", async (_req, res) => {
 		const [settings, windowPosition, status] = await Promise.all([
 			readSettings(),
@@ -314,6 +494,12 @@ function installSettingsPage(ctx, home, pet) {
 			touchTotals
 		});
 	});
+	route("GET", "/api/pet-settings/electron-runtime", async (_req, res) => {
+		writeJson(res, 200, {
+			ok: true,
+			runtime: readElectronRuntimeStatus(home) ?? null
+		});
+	});
 	route("POST", "/api/pet-settings/update", async (req, res) => {
 		const body = await readJsonBody(req);
 		const patch = body === void 0 ? void 0 : body.patch;
@@ -327,11 +513,29 @@ function installSettingsPage(ctx, home, pet) {
 			delete patch.names;
 		}
 		const next = mergeSettings(await readSettings(), patch);
+		const warnings = [];
+		const patchTouchesBinding = patchTouchesElectronBinding(patch);
+		const bound = next.innerVoice?.boundSessions?.electron;
+		if (typeof bound === "string" && bound !== "") {
+			const found = await findSessionHeader(bound);
+			if (found.checked && found.header === void 0) warnings.push(`会话 ${bound} 不存在`);
+			else {
+				if (found.currentPreset !== void 0 && !isPetPreset(found.currentPreset)) {
+					if (patchTouchesBinding) {
+						writeJson(res, 400, { error: `这个会话的当前模式是「${found.currentPreset}」，没有 pet_say/pet_do。请改用宠物模式（「精简（仅表达）」或「普通（含工作工具）」）的会话，或新建一个宠物模式会话后再绑定。` });
+						return;
+					}
+					warnings.push("当前已保存的绑定会话不是宠物模式；本次保存已生效，但绑定不会有气泡回应。");
+				}
+				if (found.currentPreset === void 0 && found.header !== void 0) warnings.push("无法确认这个会话的当前模式；如果它不是宠物模式，绑定后不会有气泡回应。");
+			}
+		}
 		await writeGlobalJson(home, "pet-settings.json", next);
 		ctx.emit("pet-settings/changed");
 		writeJson(res, 200, {
 			ok: true,
-			settings: next
+			settings: next,
+			warnings
 		});
 	});
 	route("POST", "/api/pet-settings/reset-affection", async (_req, res) => {
@@ -721,7 +925,6 @@ function apply(ctx) {
 			return;
 		}
 	};
-	const INSTALL_LOCK_STALE_MS = 18e5;
 	const installLockPath = (pkgDir) => join(pkgDir, ".dsh-pet-install.lock");
 	const acquireInstallLock = (pkgDir) => {
 		const lock = installLockPath(pkgDir);
@@ -734,63 +937,162 @@ function apply(ctx) {
 		try {
 			write();
 			return true;
+		} catch {}
+		let raw;
+		let mtimeMs = 0;
+		try {
+			raw = readFileSync(lock, "utf8");
+			mtimeMs = statSync(lock).mtimeMs;
 		} catch {
 			try {
-				if (Date.now() - statSync(lock).mtimeMs > INSTALL_LOCK_STALE_MS) {
-					unlinkSync(lock);
-					write();
-					return true;
-				}
-			} catch {}
+				write();
+				return true;
+			} catch {
+				return false;
+			}
+		}
+		const owner = raw === void 0 ? void 0 : parseInstallLock(raw)?.pid;
+		const ownerPid = typeof owner === "number" ? owner : void 0;
+		if (!installLockStale(raw, mtimeMs, Date.now())) {
+			logCarrier(ownerPid === void 0 ? `electron install lock unreadable but fresh; waiting: ${lock}` : `electron install lock held by pid ${String(ownerPid)} (alive); waiting: ${lock}`);
+			return false;
+		}
+		const dead = ownerPid !== void 0 && !isProcessAlive(ownerPid);
+		logCarrier(`electron install lock stale (${ownerPid === void 0 ? "unreadable" : `pid ${String(ownerPid)} ${dead ? "dead" : "expired"}`}); taking over: ${lock}`);
+		try {
+			unlinkSync(lock);
+		} catch {}
+		try {
+			write();
+			return true;
+		} catch {
 			return false;
 		}
 	};
 	const releaseInstallLock = (pkgDir) => {
+		const lock = installLockPath(pkgDir);
+		try {
+			const owner = parseInstallLock(readFileSync(lock, "utf8"))?.pid;
+			if (typeof owner === "number" && owner !== process.pid) return;
+		} catch {}
 		try {
-			unlinkSync(installLockPath(pkgDir));
+			unlinkSync(lock);
 		} catch {}
 	};
+	const NPMMIRROR_ELECTRON = "https://npmmirror.com/mirrors/electron/";
+	const INSTALL_TIMEOUT_MS = 12e5;
+	let activeInstallChild;
+	const writeRuntimeStatus = (status) => {
+		writeElectronRuntimeStatus(petHome(), status);
+	};
 	/**
 	* Install the npm electron binary off the activation path. The package's
-	* lazy installer is a ~250 MB download; running it synchronously (which
+	* lazy installer is a large download; running it synchronously (which
 	* `require('electron')` does) freezes the host, so it runs as a child with
-	* progress in the spawn log and a mirror hint on failure.
+	* progress in the spawn log. The lock is owner-liveness based: a host that
+	* dies mid-download never blocks the next activation.
 	*/
-	const installNpmElectron = async (pkgDir) => {
+	const installNpmElectron = async (pkgDir, attempt) => {
 		const installer = join(pkgDir, "install.js");
 		if (!existsSync(installer)) {
 			logCarrier(`electron binary missing and install.js not found: ${pkgDir}`);
-			return;
+			writeRuntimeStatus({
+				state: "unavailable",
+				updatedAt: Date.now(),
+				error: `install.js not found in ${pkgDir}`
+			});
+			return {
+				kind: "unavailable",
+				error: `install.js not found in ${pkgDir}`
+			};
 		}
 		if (!acquireInstallLock(pkgDir)) {
-			logCarrier(`electron install already in progress (lock present): ${pkgDir}`);
-			return;
+			writeRuntimeStatus({
+				state: "busy",
+				updatedAt: Date.now()
+			});
+			return { kind: "busy" };
 		}
-		logCarrier(`electron binary missing; installing in background: ${pkgDir}`);
+		const explicitMirror = (process.env.ELECTRON_MIRROR ?? process.env.npm_config_electron_mirror ?? "").trim();
+		const mirror = explicitMirror !== "" ? explicitMirror : attempt % 2 === 0 ? NPMMIRROR_ELECTRON : void 0;
+		const source = explicitMirror !== "" ? "explicit" : mirror === void 0 ? "github" : "npmmirror";
+		const startedAt = Date.now();
+		writeRuntimeStatus({
+			state: "downloading",
+			updatedAt: startedAt,
+			startedAt,
+			attempt: attempt + 1,
+			source
+		});
+		logCarrier(`electron binary missing; installing in background (attempt ${String(attempt + 1)}, source=${source}): ${pkgDir}`);
 		return await new Promise((resolveInstall) => {
 			let settled = false;
-			const finish = (value) => {
+			let timeout;
+			const finish = (result) => {
 				if (settled) return;
 				settled = true;
+				if (timeout !== void 0) clearTimeout(timeout);
+				activeInstallChild = void 0;
 				releaseInstallLock(pkgDir);
-				resolveInstall(value);
+				if (result.kind === "installed") writeRuntimeStatus({
+					state: "ready",
+					updatedAt: Date.now(),
+					startedAt,
+					finishedAt: Date.now(),
+					attempt: attempt + 1,
+					source
+				});
+				else if (result.kind === "failed") writeRuntimeStatus({
+					state: "failed",
+					updatedAt: Date.now(),
+					startedAt,
+					attempt: attempt + 1,
+					source,
+					error: result.error
+				});
+				resolveInstall(result);
 			};
 			let stderr = "";
 			let stdout = "";
 			let lastProgress = 0;
-			const child = spawn(process.execPath, [installer], {
-				cwd: pkgDir,
-				env: {
-					...process.env,
-					ELECTRON_RUN_AS_NODE: "1"
-				},
-				stdio: [
-					"ignore",
-					"pipe",
-					"pipe"
-				],
-				windowsHide: true
-			});
+			const env = {
+				...process.env,
+				ELECTRON_RUN_AS_NODE: "1"
+			};
+			if (mirror === void 0) {
+				delete env.ELECTRON_MIRROR;
+				delete env.npm_config_electron_mirror;
+			} else env.ELECTRON_MIRROR = mirror;
+			let child;
+			try {
+				child = spawn(process.execPath, [installer], {
+					cwd: pkgDir,
+					env,
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					],
+					windowsHide: true
+				});
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				logCarrier(`electron install failed to start: ${message}`);
+				finish({
+					kind: "failed",
+					error: message
+				});
+				return;
+			}
+			activeInstallChild = child;
+			timeout = setTimeout(() => {
+				logCarrier(`electron install timed out after ${String(INSTALL_TIMEOUT_MS / 6e4)} min (source=${source}); killing pid=${String(child.pid ?? "unknown")}`);
+				child.kill();
+				finish({
+					kind: "failed",
+					error: `timed out after ${String(INSTALL_TIMEOUT_MS / 6e4)} min`
+				});
+			}, INSTALL_TIMEOUT_MS);
 			child.stdout?.setEncoding("utf8");
 			child.stdout?.on("data", (chunk) => {
 				stdout = `${stdout}${chunk}`.slice(-2e3);
@@ -807,22 +1109,35 @@ function apply(ctx) {
 			});
 			child.on("error", (error) => {
 				logCarrier(`electron install failed to start: ${error.message}`);
-				finish(void 0);
+				finish({
+					kind: "failed",
+					error: error.message
+				});
 			});
 			child.on("exit", (code) => {
 				if (code !== 0) {
-					logCarrier(`electron install failed (exit ${String(code)}): ${stderr.trim() || "no stderr"}. Set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ (or electron_mirror in .npmrc) and restart DSH; or run "node ${installer}" manually.`);
-					finish(void 0);
+					const detail = stderr.trim() || "no stderr";
+					logCarrier(`electron install failed (exit ${String(code)}, source=${source}): ${detail}`);
+					finish({
+						kind: "failed",
+						error: `exit ${String(code)}: ${detail}`
+					});
 					return;
 				}
 				const binary = npmElectronBinary(pkgDir);
 				if (binary === void 0) {
 					logCarrier(`electron install exited 0 but the binary is still missing: ${pkgDir}`);
-					finish(void 0);
+					finish({
+						kind: "failed",
+						error: "binary still missing after a successful install"
+					});
 					return;
 				}
 				logCarrier(`electron installed: ${binary}`);
-				finish(ensureElectronUsable(binary));
+				finish({
+					kind: "installed",
+					binary: ensureElectronUsable(binary)
+				});
 			});
 		});
 	};
@@ -899,20 +1214,86 @@ function apply(ctx) {
 			child.kill();
 		}, "pet-surface: carrier shutdown");
 	};
+	const RETRY_DELAYS_MS = [
+		3e4,
+		6e4,
+		12e4,
+		3e5
+	];
+	let disposed = false;
+	let carrierLaunched = false;
+	let installInFlight = false;
+	let installAttempt = 0;
+	let retryTimer;
+	const launchOnce = (url, carrierDir, binary) => {
+		if (disposed || carrierLaunched) return;
+		carrierLaunched = true;
+		if (retryTimer !== void 0) {
+			clearTimeout(retryTimer);
+			retryTimer = void 0;
+		}
+		launchCarrier(url, carrierDir, binary);
+	};
+	const ensureCarrier = async (url, carrierDir, pkgDir) => {
+		if (disposed || carrierLaunched) return;
+		const resolution = resolveElectron();
+		if (resolution.binary !== void 0) {
+			writeRuntimeStatus({
+				state: "ready",
+				updatedAt: Date.now()
+			});
+			launchOnce(url, carrierDir, resolution.binary);
+			return;
+		}
+		const nextPkgDir = resolution.npmPackageDir ?? pkgDir;
+		if (installInFlight) return;
+		installInFlight = true;
+		const attempt = installAttempt;
+		installAttempt += 1;
+		const result = await installNpmElectron(nextPkgDir, attempt).catch((error) => ({
+			kind: "failed",
+			error: error instanceof Error ? error.message : String(error)
+		}));
+		installInFlight = false;
+		if (disposed || carrierLaunched) return;
+		if (result.kind === "installed") {
+			launchOnce(url, carrierDir, result.binary);
+			return;
+		}
+		if (result.kind === "unavailable") {
+			logCarrier(`electron auto-install unavailable: ${result.error}`);
+			return;
+		}
+		const reason = result.kind === "busy" ? "blocked by another activation" : `failed (${result.error})`;
+		const delay = RETRY_DELAYS_MS[Math.min(installAttempt - 1, RETRY_DELAYS_MS.length - 1)];
+		logCarrier(`electron install ${reason}; retrying in ${String(delay / 1e3)}s`);
+		if (retryTimer !== void 0) clearTimeout(retryTimer);
+		retryTimer = setTimeout(() => {
+			ensureCarrier(url, carrierDir, nextPkgDir);
+		}, delay);
+	};
 	const spawnPetCarrier = (url) => {
 		const carrierDir = resolve(join(dirname(fileURLToPath(import.meta.url)), "..", "carrier"));
 		if (process.env.DSH_PET_NO_SPAWN === "1" || !existsSync(join(carrierDir, "package.json"))) return;
 		const resolution = resolveElectron();
 		if (resolution.binary !== void 0) {
-			launchCarrier(url, carrierDir, resolution.binary);
+			writeRuntimeStatus({
+				state: "ready",
+				updatedAt: Date.now()
+			});
+			launchOnce(url, carrierDir, resolution.binary);
 			return;
 		}
-		if (resolution.npmPackageDir === void 0) return;
-		installNpmElectron(resolution.npmPackageDir).then((binary) => {
-			if (binary !== void 0) launchCarrier(url, carrierDir, binary);
-		}).catch((error) => {
-			logCarrier(`electron install failed: ${error instanceof Error ? error.message : String(error)}`);
-		});
+		if (resolution.npmPackageDir === void 0) {
+			logCarrier("no electron binary and no npm electron package; cannot auto-install");
+			writeRuntimeStatus({
+				state: "unavailable",
+				updatedAt: Date.now(),
+				error: "electron package not installed"
+			});
+			return;
+		}
+		ensureCarrier(url, carrierDir, resolution.npmPackageDir);
 	};
 	const settledReady = () => {
 		const url = authenticatedRoot();
@@ -925,8 +1306,12 @@ function apply(ctx) {
 	else settled.then(settledReady).catch(() => {});
 	const home = petHome();
 	const pet = installPetService(ctx, home);
-	installPetDriver(ctx, home, pet);
-	installSettingsPage(ctx, home, pet);
+	installSettingsPage(ctx, home, pet, installPetDriver(ctx, home, pet));
+	ctx.effect(() => () => {
+		disposed = true;
+		if (retryTimer !== void 0) clearTimeout(retryTimer);
+		activeInstallChild?.kill();
+	}, "pet-surface: electron install cleanup");
 	ctx.effect(() => () => {
 		readFile(petLocatorPath(), "utf8").then((raw) => {
 			if (JSON.parse(raw).pid === process.pid) return unlink(petLocatorPath());

package/lib/tools.js

@@ -1,4 +1,4 @@
-import { a as logStamp, o as registerPetTools, r as petHome, t as createUnregisteredPetHttp } from "./service-BZbhT92u.js";
+import { a as createUnregisteredPetHttp, n as logStamp, r as registerPetTools, s as petHome } from "./driver-BiSFFYXw.js";
 import { appendFile } from "node:fs/promises";
 import { join } from "node:path";
 // lib/types/tools.js

package/lib/types/actions.d.ts

@@ -6,6 +6,17 @@
  * catalog drift between pet implementations must die.
  * @module dsh-agentic-pet/actions
  */
+/** One body-owned catalog entry. `tags` are THIS body's vocabulary — the
+ * driver never defines a cross-body enum. */
+export interface ActionCatalogEntry {
+    readonly id: string;
+    readonly tags: readonly string[];
+    readonly energy?: 'low' | 'mid' | 'high';
+    readonly durationHintMs?: number;
+    readonly textInFrame?: boolean;
+    /** State animation that loops; wait cannot observe a meaningful end. */
+    readonly loop?: boolean;
+}
 /** A pet's advertised capabilities. `contractVersion: null` = a legacy
  * implementation that predates the version field (v1 semantics: seven
  * endpoints, no /world). `actions: null` = the pet publishes no catalog (a
@@ -14,6 +25,10 @@
 export interface PetCapabilities {
     readonly contractVersion: number | null;
     readonly actions: readonly string[] | null;
+    readonly actionCatalog: readonly ActionCatalogEntry[] | null;
+    /** The body's own tag vocabulary, derived from its catalog when omitted. */
+    readonly actionTagVocabulary: readonly string[];
+    readonly tagged: boolean;
 }
 /** Defensive extraction from a raw /capabilities payload: implementations
  * may omit or mistype anything. */
@@ -39,3 +54,18 @@ export declare function resolveActionRequest(requested: string, catalog: readonl
 /** The error-message menu: long catalogs are previewed, with a pointer to
  * pet_state {actions:true} for the full list. */
 export declare function formatAvailableActions(available: readonly string[], cap?: number): string;
+export type TagResolution = {
+    kind: 'ok';
+    action: string;
+    candidates: readonly string[];
+} | {
+    kind: 'unknown';
+    availableTags: readonly string[];
+    availableActions: readonly string[];
+};
+/** Resolve a tag against the CURRENT body's own catalog. Multiple matches are
+ * a random draw (celebrate is never a tag candidate). No cross-body tag
+ * vocabulary is consulted. */
+export declare function resolveTagRequest(tag: string, capabilities: PetCapabilities | null): TagResolution;
+/** Tag menu for errors: an empty vocabulary names the fallback explicitly. */
+export declare function formatAvailableTags(tags: readonly string[], cap?: number): string;