@oh-my-pi/pi-utils 18.4.10 → 18.4.11

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [18.4.11] - 2026-10-02
+
+### Added
+
+- Added XDG-aware utility paths for skill descriptions and prediction state, with automatic adoption of legacy data when XDG locations are first resolved.
+
+### Fixed
+
+- Fixed machine-global daemon runtime paths so brokers such as text prediction use the shared XDG state location across profiles and custom agent directories.
+
 ## [18.4.10] - 2026-10-02
 
 ### Added

package/dist/types/dirs.d.ts

@@ -277,6 +277,10 @@ export declare function getTinyModelsCacheDir(agentDir?: string): string;
 export declare function getDocumentConversionCacheDir(agentDir?: string): string;
 /** Get the composer speculative cache database (~/.omp/agent/cache/composer.db; XDG default: $XDG_CACHE_HOME/omp/cache/composer.db). */
 export declare function getComposerCacheDbPath(agentDir?: string): string;
+/** Get the skill descriptions database (~/.omp/agent/skill-descriptions.db; XDG default: $XDG_DATA_HOME/omp/skill-descriptions.db). */
+export declare function getSkillDescriptionsDbPath(agentDir?: string): string;
+/** Get the text-predict engine state directory (~/.omp/agent/predict/<method>; XDG default: $XDG_DATA_HOME/omp/predict/<method>). Adopts legacy engine state on first XDG resolution. */
+export declare function getPredictStateDir(agentDir: string | undefined, method: string): string;
 /** Get the sessions directory (~/.omp/agent/sessions). */
 export declare function getSessionsDir(agentDir?: string): string;
 /** Get the content-addressed blob store directory (~/.omp/agent/blobs). */
@@ -314,7 +318,7 @@ export declare function getTinyWorkerRuntimeDir(): string;
 export declare function getDaemonRuntimeRoot(): string;
 /** Get the daemon runtime directory for a project (~/.omp/run/daemons/<hash>; XDG default: $XDG_STATE_HOME/omp/run/daemons/<hash>). */
 export declare function getDaemonRuntimeDir(projectDir: string): string;
-/** Root directory containing every machine-global daemon service scope. */
+/** Root directory containing every machine-global daemon service scope (~/.omp/run/daemons/global; XDG default: $XDG_STATE_HOME/omp/run/daemons/global). Shared across profiles. */
 export declare function getGlobalDaemonRuntimeRoot(): string;
 /** Get a profile-independent runtime directory for a machine-global daemon service. */
 export declare function getGlobalDaemonRuntimeDir(service: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.4.10",
+	"version": "18.4.11",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,7 +57,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.4.10"
+		"@oh-my-pi/pi-natives": "18.4.11"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/dirs.ts

@@ -334,6 +334,7 @@ class DirResolver {
 	// With XDG on Linux, they point to $XDG_*_HOME/omp/.
 	readonly #rootDirs: Record<XdgCategory, string>;
 	readonly #agentDirs: Record<XdgCategory, string>;
+	readonly #baseRootDirs: Record<XdgCategory, string>;
 
 	readonly #rootCache = new Map<string, string>();
 	readonly #agentCache = new Map<string, string>();
@@ -362,7 +363,8 @@ class DirResolver {
 		let xdgData: string | undefined;
 		let xdgState: string | undefined;
 		let xdgCache: string | undefined;
-		if ((process.platform === "linux" || process.platform === "darwin") && isDefault) {
+		const xdgPlatform = process.platform === "linux" || process.platform === "darwin";
+		if (xdgPlatform && isDefault) {
 			const resolveIf = (envVar: string) => {
 				const value = process.env[envVar];
 				if (!value) return undefined;
@@ -370,14 +372,10 @@ class DirResolver {
 					const appRoot = path.join(value, APP_NAME);
 					if (profile) {
 						const profilePath = path.join(appRoot, "profiles", profile);
-						if (fs.existsSync(profilePath)) {
-							return profilePath;
-						}
+						if (fs.existsSync(profilePath)) return profilePath;
 						return undefined;
 					}
-					if (fs.existsSync(appRoot)) {
-						return appRoot;
-					}
+					return fs.existsSync(appRoot) ? appRoot : undefined;
 				} catch {}
 				return undefined;
 			};
@@ -386,6 +384,22 @@ class DirResolver {
 			xdgCache = resolveIf("XDG_CACHE_HOME");
 		}
 
+		// XDG choice for machine-global paths (daemon scopes shared by every
+		// process): keyed only on the base app root, independent of both the
+		// profile and any agent-dir override, so every omp process on the machine
+		// agrees on one location. These hold process-scoped runtime state
+		// (sockets, tokens), so there is no migration to protect.
+		const resolveBase = (envVar: string) => {
+			if (!xdgPlatform) return undefined;
+			const value = process.env[envVar];
+			if (!value) return undefined;
+			try {
+				const appRoot = path.join(value, APP_NAME);
+				return fs.existsSync(appRoot) ? appRoot : undefined;
+			} catch {}
+			return undefined;
+		};
+
 		this.#rootDirs = {
 			data: xdgData ?? this.configRoot,
 			state: xdgState ?? this.configRoot,
@@ -397,6 +411,17 @@ class DirResolver {
 			state: xdgState ?? this.agentDir,
 			cache: xdgCache ?? this.agentDir,
 		};
+		const baseRoot = getBaseConfigRoot();
+		this.#baseRootDirs = {
+			data: resolveBase("XDG_DATA_HOME") ?? baseRoot,
+			state: resolveBase("XDG_STATE_HOME") ?? baseRoot,
+			cache: resolveBase("XDG_CACHE_HOME") ?? baseRoot,
+		};
+	}
+
+	/** Profile-independent config-root subdirectory, with optional XDG override. Shared across profiles. */
+	baseRootSubdir(subdir: string, xdg?: XdgCategory): string {
+		return path.join(xdg ? this.#baseRootDirs[xdg] : getBaseConfigRoot(), subdir);
 	}
 
 	/** Config-root subdirectory, with optional XDG override. */
@@ -915,6 +940,17 @@ export function getDocumentConversionCacheDir(agentDir?: string): string {
 export function getComposerCacheDbPath(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, path.join("cache", "composer.db"), "cache");
 }
+/** Get the skill descriptions database (~/.omp/agent/skill-descriptions.db; XDG default: $XDG_DATA_HOME/omp/skill-descriptions.db). */
+export function getSkillDescriptionsDbPath(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "skill-descriptions.db", "data");
+}
+/** Get the text-predict engine state directory (~/.omp/agent/predict/<method>; XDG default: $XDG_DATA_HOME/omp/predict/<method>). Adopts legacy engine state on first XDG resolution. */
+export function getPredictStateDir(agentDir: string | undefined, method: string): string {
+	const subdir = path.join("predict", method);
+	const stateDir = dirs.agentSubdir(agentDir, subdir, "data");
+	adoptLegacyDir(path.join(agentDir ?? dirs.agentDir, subdir), stateDir);
+	return stateDir;
+}
 
 /** Get the sessions directory (~/.omp/agent/sessions). */
 export function getSessionsDir(agentDir?: string): string {
@@ -1000,6 +1036,29 @@ function adoptLegacyFile(legacyPath: string, targetPath: string): void {
 	}
 }
 
+/**
+ * Best-effort one-time copy of a legacy directory to its redirected XDG
+ * location, so learned state survives enabling XDG. The copy is staged next to
+ * the target and renamed into place, so a reader never sees a partial tree and
+ * a concurrent adopter cannot clobber a finished one. The legacy directory is
+ * left in place for older omp versions sharing the profile.
+ */
+function adoptLegacyDir(legacyPath: string, targetPath: string): void {
+	if (targetPath === legacyPath) return;
+	const staging = `${targetPath}.adopt-${process.pid}`;
+	try {
+		if (fs.existsSync(targetPath) || !fs.statSync(legacyPath, { throwIfNoEntry: false })?.isDirectory()) return;
+		fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+		fs.rmSync(staging, { recursive: true, force: true });
+		fs.cpSync(legacyPath, staging, { recursive: true });
+		fs.renameSync(staging, targetPath);
+	} catch {
+		// Opportunistic: a lost race or unwritable XDG dir falls back to fresh
+		// state at the new path — the pre-adoption behavior.
+		fs.rmSync(staging, { recursive: true, force: true });
+	}
+}
+
 /** Get the secret placeholder key path (~/.omp/agent/secret-placeholder.key; XDG default: $XDG_STATE_HOME/omp/secret-placeholder.key). Adopts a legacy key on first XDG resolution. */
 export function getSecretPlaceholderKeyPath(): string {
 	const keyPath = dirs.agentSubdir(undefined, "secret-placeholder.key", "state");
@@ -1023,9 +1082,9 @@ export function getDaemonRuntimeDir(projectDir: string): string {
 	return path.join(getDaemonRuntimeRoot(), key);
 }
 
-/** Root directory containing every machine-global daemon service scope. */
+/** Root directory containing every machine-global daemon service scope (~/.omp/run/daemons/global; XDG default: $XDG_STATE_HOME/omp/run/daemons/global). Shared across profiles. */
 export function getGlobalDaemonRuntimeRoot(): string {
-	return path.join(getBaseConfigRoot(), "run", "daemons", "global");
+	return dirs.baseRootSubdir(path.join("run", "daemons", "global"), "state");
 }
 
 /** Get a profile-independent runtime directory for a machine-global daemon service. */