pi-harness-runtime 1.1.411 → 1.1.413

package/harness/notification-settings.ts

@@ -0,0 +1,130 @@
+/**
+ * The persisted notification-channel settings.
+ *
+ * The notification center keeps the runtime state of a channel (in memory and
+ * in its own SQLite table). This file is the durable record of an EXPLICIT
+ * user decision: "LINE is off".
+ *
+ * Two things need that record:
+ *
+ * - The startup summary must show "LINE: disabled" instead of a warning
+ *   after the user turned the channel off. Without a durable record the
+ *   summary cannot tell "disabled on purpose" from "never configured" - and
+ *   it must not guess, because guessing wrong shows a warning for a channel
+ *   the user deliberately turned off.
+ * - The decision must survive a restart, so the setting is written to disk
+ *   when the user changes it.
+ *
+ * Plain JSON is used on purpose: it works in every runtime (Bun has no
+ * usable `node:sqlite`), it is readable by the user, and a broken file can
+ * never stop the harness from starting.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface NotificationChannelSettings {
+	/** `false` = the user turned the channel off. */
+	enabled: boolean;
+}
+
+export interface NotificationSettings {
+	/** The shape of the file. A future change bumps the version. */
+	version: 1;
+	channels: Record<string, NotificationChannelSettings>;
+}
+
+/** The directory that holds the harness runtime state. */
+export function notificationSettingsDir(): string {
+	return join(homedir(), ".pi-harness-runtime");
+}
+
+/** The file that holds the persisted channel decisions. */
+export function notificationSettingsPath(): string {
+	return join(notificationSettingsDir(), "notification-settings.json");
+}
+
+export function defaultNotificationSettings(): NotificationSettings {
+	return { version: 1, channels: {} };
+}
+
+/** A plain object - the only shape the decoder accepts. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Decode one channel entry.
+ *
+ * The file is user-writable, so every value is checked before it is used.
+ * An entry that does not decode is dropped - a broken entry must not take
+ * the whole file (and with it the other channels) down.
+ */
+function decodeChannelSettings(value: unknown): NotificationChannelSettings | null {
+	if (!isRecord(value)) return null;
+	return { enabled: value.enabled !== false };
+}
+
+/**
+ * Read the persisted settings.
+ *
+ * A missing, unreadable or broken file yields the defaults: the settings are
+ * a convenience, never a reason to fail a start.
+ */
+export function loadNotificationSettings(path: string = notificationSettingsPath()): NotificationSettings {
+	try {
+		if (!existsSync(path)) return defaultNotificationSettings();
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!isRecord(parsed)) return defaultNotificationSettings();
+		const channels: Record<string, NotificationChannelSettings> = {};
+		const rawChannels = parsed.channels;
+		if (isRecord(rawChannels)) {
+			for (const [id, value] of Object.entries(rawChannels)) {
+				const decoded = decodeChannelSettings(value);
+				if (decoded) channels[id] = decoded;
+			}
+		}
+		return { version: 1, channels };
+	} catch {
+		return defaultNotificationSettings();
+	}
+}
+
+/** Write the settings. Returns false when the file could not be written. */
+export function saveNotificationSettings(
+	settings: NotificationSettings,
+	path: string = notificationSettingsPath(),
+): boolean {
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Did the user explicitly turn the channel off?
+ *
+ * A channel that was never mentioned has no entry - it is NOT disabled. Only
+ * an explicit decision counts, because "disabled" and "not configured" are
+ * different states with different meanings.
+ */
+export function isChannelDisabled(channel: string, path?: string): boolean {
+	const settings = loadNotificationSettings(path);
+	const entry = settings.channels[channel];
+	return entry ? entry.enabled === false : false;
+}
+
+/**
+ * Record an explicit channel decision.
+ *
+ * Returns false when the decision could not be persisted - the caller then
+ * knows that the decision is lost on the next restart.
+ */
+export function setChannelDisabled(channel: string, disabled: boolean, path?: string): boolean {
+	const settings = loadNotificationSettings(path);
+	settings.channels[channel] = { enabled: !disabled };
+	return saveNotificationSettings(settings, path);
+}

package/harness/skill-remote-source.ts

@@ -0,0 +1,157 @@
+/**
+ * The skill service as a source of server-held skills.
+ *
+ * The service holds the authoritative skill files. It applies the access
+ * rules of the user, so a refusal is an ANSWER of the service and not a
+ * failure of the client - the two need different fixes and must stay
+ * apart.
+ *
+ * The vector store is an index: it says WHICH skill fits a question, but
+ * its payload carries only a truncated body. The service delivers the
+ * complete skill, so a machine without a local copy can still use it.
+ */
+
+import { getSkillFromSaaS, syncSkillsFromSaaS } from "./skill-sync.js";
+import type {
+	RemoteSkill,
+	RemoteSkillSource,
+} from "../packages/skills/dist/remote-source.js";
+
+/** Why a call to the service failed. */
+export type SkillServiceFailure = "denied" | "unavailable";
+
+/** The error a failed call to the service raises. */
+export class SkillServiceError extends Error {
+	/**
+	 * @param message The reason of the failure. Never a credential.
+	 * @param code Whether the service refused the call or could not be
+	 *   reached. The two need different fixes.
+	 */
+	constructor(
+		message: string,
+		readonly code: SkillServiceFailure,
+	) {
+		super(message);
+		this.name = "SkillServiceError";
+	}
+}
+
+/** The parts of the sync result the source needs. */
+interface SyncOutcome {
+	source: "saas" | "cache" | "none";
+	skills?: Array<{
+		id: string;
+		name: string;
+		description: string;
+		version?: string;
+		updatedAt?: string;
+	}>;
+	error?: string;
+	failure?: SkillServiceFailure;
+}
+
+/** The parts of the sync module the source needs. */
+export interface SkillServiceGateway {
+	syncSkillsFromSaaS(options?: {
+		forceRefresh?: boolean;
+	}): Promise<SyncOutcome>;
+	getSkillFromSaaS(identifier: {
+		id?: string;
+		slug?: string;
+	}): Promise<{
+		id: string;
+		name: string;
+		description: string;
+		version?: string;
+		updatedAt?: string;
+		prompt?: string;
+	} | null>;
+}
+
+/**
+ * The service as a source of remote skills.
+ *
+ * The gateway is injected, so the source can be tested without a service
+ * and without a network.
+ */
+export class SkillServiceSource implements RemoteSkillSource {
+	/** @param gateway The sync module. The real one by default. */
+	constructor(
+		private readonly gateway: SkillServiceGateway = {
+			syncSkillsFromSaaS,
+			getSkillFromSaaS,
+		},
+	) {}
+
+	/**
+	 * The skills the service holds.
+	 *
+	 * A service that refuses the call raises a `SkillServiceError` with
+	 * the code "denied" - the caller can tell that apart from a service
+	 * that could not be reached.
+	 */
+	async list(options?: {
+		search?: string;
+		limit?: number;
+	}): Promise<RemoteSkill[]> {
+		const outcome = await this.gateway.syncSkillsFromSaaS();
+
+		if (outcome.source === "none") {
+			throw new SkillServiceError(
+				outcome.error ?? "the skill service could not be reached",
+				outcome.failure ?? "unavailable",
+			);
+		}
+
+		const skills = outcome.skills ?? [];
+		const searched = options?.search
+			? skills.filter((skill) => matches(skill, options.search as string))
+			: skills;
+		const limited = options?.limit ? searched.slice(0, options.limit) : searched;
+
+		return limited.map((skill) => ({
+			id: skill.id,
+			name: skill.name,
+			description: skill.description,
+			version: skill.version,
+			updatedAt: skill.updatedAt,
+		}));
+	}
+
+	/**
+	 * The complete content of one skill.
+	 *
+	 * The service returns the whole skill, so the content is complete -
+	 * unlike the truncated body of a vector store payload.
+	 */
+	async get(id: string): Promise<RemoteSkill | null> {
+		const skill = await this.gateway.getSkillFromSaaS({ id });
+		if (!skill) return null;
+		return {
+			id: skill.id,
+			name: skill.name,
+			description: skill.description,
+			version: skill.version,
+			updatedAt: skill.updatedAt,
+			content: skill.prompt,
+			contentComplete: true,
+		};
+	}
+}
+
+/**
+ * Whether a skill matches a search term.
+ *
+ * The service does the real search; this filter only narrows what the
+ * service already returned.
+ */
+function matches(
+	skill: { name: string; description: string },
+	term: string,
+): boolean {
+	const needle = term.toLowerCase();
+	return (
+		skill.name.toLowerCase().includes(needle) ||
+		skill.description.toLowerCase().includes(needle)
+	);
+}

package/harness/skill-sync.ts

@@ -5,7 +5,7 @@
  * Falls back gracefully if backend is unavailable.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import type {
@@ -13,6 +13,8 @@ import type {
 	GetSkillResult,
 } from "../packages/skill-mcp-client/src/types.js";
 import { SkillAPIError } from "../packages/skill-mcp-client/dist/errors.js";
+import { atomicWriteFileSync } from "../packages/cookie-sanitizer/dist/index.js";
+import { centralWarn } from "../packages/logging/dist/index.js";
 
 type SkillMCPClient = InstanceType<
 	typeof import("../packages/skill-mcp-client/dist/client.js").SkillMCPClient
@@ -52,7 +54,11 @@ async function getClient(): Promise<SkillMCPClient | null> {
 		});
 		return clientInstance;
 	} catch {
-		console.warn("[skill-sync] Failed to import skill-mcp-client");
+		centralWarn(
+			"harness.skill-sync",
+			"service.sync-failed",
+			"the skill client package could not be loaded",
+		);
 		return null;
 	}
 }
@@ -73,6 +79,22 @@ interface SkillSyncResult {
 	skillCount: number;
 	source: "saas" | "cache" | "none";
 	error?: string;
+	/**
+	 * The skills the service holds.
+	 *
+	 * The list is carried along with the count, so a caller that needs
+	 * the skills does not have to ask the service a second time.
+	 */
+	skills?: SkillInfo[];
+	/**
+	 * Why the service could not be reached.
+	 *
+	 * "denied" means the service ANSWERED and refused the call - the
+	 * token is missing or the plan does not cover the skill. That is a
+	 * different situation than a service that could not be reached at
+	 * all, and the user needs a different fix for each.
+	 */
+	failure?: "denied" | "unavailable";
 }
 
 /**
@@ -102,22 +124,28 @@ function getCachedSkills(): CacheData | null {
  */
 function saveCache(data: CacheData): void {
 	try {
-		if (!existsSync(CACHE_DIR)) {
-			mkdirSync(CACHE_DIR, { recursive: true });
-		}
-		writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
+		// The write is atomic: a crash in the middle leaves the previous
+		// cache intact instead of a half written file.
+		atomicWriteFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
 	} catch {
-		console.warn("[skill-sync] Failed to save cache");
+		centralWarn(
+			"harness.skill-sync",
+			"service.cache-write-failed",
+			"the skill cache could not be written",
+		);
 	}
 }
 
 /**
  * Fetch and cache skills from SaaS backend
  */
-async function fetchFromSaaS(): Promise<CacheData | null> {
+async function fetchFromSaaS(): Promise<{
+	data: CacheData | null;
+	failure?: "denied" | "unavailable";
+}> {
 	const client = await getClient();
 	if (!client) {
-		return null;
+		return { data: null, failure: "unavailable" };
 	}
 
 	try {
@@ -128,16 +156,26 @@ async function fetchFromSaaS(): Promise<CacheData | null> {
 			version: "1.0.0",
 		};
 		saveCache(cacheData);
-		return cacheData;
+		return { data: cacheData };
 	} catch (error) {
 		if (error instanceof SkillAPIError) {
-			console.warn(
-				`[skill-sync] API error: ${error.message} (code: ${error.code})`,
+			centralWarn(
+				"harness.skill-sync",
+				"service.sync-failed",
+				`the skill service answered with an error (code ${error.code})`,
 			);
+			// The service answered and refused the call.
+			if (error.isAuthError() || error.isTierRestricted()) {
+				return { data: null, failure: "denied" };
+			}
 		} else {
-			console.warn("[skill-sync] Failed to fetch from SaaS");
+			centralWarn(
+				"harness.skill-sync",
+				"service.sync-failed",
+				"the skill service could not be reached",
+			);
 		}
-		return null;
+		return { data: null, failure: "unavailable" };
 	}
 }
 
@@ -162,6 +200,7 @@ export async function syncSkillsFromSaaS(
 			success: true,
 			skillCount: 0,
 			source: "none",
+			skills: [],
 			error: "SKILLS_SAAS_API_KEY not configured",
 		};
 	}
@@ -174,17 +213,19 @@ export async function syncSkillsFromSaaS(
 				success: true,
 				skillCount: cached.skills.length,
 				source: "cache",
+				skills: cached.skills,
 			};
 		}
 	}
 
 	// Fetch from SaaS
-	const data = await fetchFromSaaS();
-	if (data) {
+	const fetched = await fetchFromSaaS();
+	if (fetched.data) {
 		return {
 			success: true,
-			skillCount: data.skills.length,
+			skillCount: fetched.data.skills.length,
 			source: "saas",
+			skills: fetched.data.skills,
 		};
 	}
 
@@ -195,16 +236,23 @@ export async function syncSkillsFromSaaS(
 			success: true,
 			skillCount: staleCache.skills.length,
 			source: "cache",
+			skills: staleCache.skills,
 			error: "Using stale cache (SaaS unavailable)",
+			failure: fetched.failure,
 		};
 	}
 
 	// Everything failed, return empty
 	return {
-		success: true,
+		success: false,
 		skillCount: 0,
 		source: "none",
-		error: "Could not reach Skills SaaS backend",
+		skills: [],
+		error:
+			fetched.failure === "denied"
+				? "The skill service refused the call - the token or the plan does not allow it"
+				: "Could not reach Skills SaaS backend",
+		failure: fetched.failure,
 	};
 }
 
@@ -226,7 +274,11 @@ export async function getSkillFromSaaS(identifier: {
 		return await client.getSkill(identifier);
 	} catch (error) {
 		if (error instanceof SkillAPIError) {
-			console.warn(`[skill-sync] Failed to get skill: ${error.message}`);
+			centralWarn(
+				"harness.skill-sync",
+				"service.skill-fetch-failed",
+				`the skill service could not deliver a skill (code ${error.code})`,
+			);
 		}
 		return null;
 	}
@@ -236,7 +288,7 @@ export async function getSkillFromSaaS(identifier: {
  * Check if skill sync is configured
  */
 export function isSkillSyncConfigured(): boolean {
-	return !!process.env.SKILLS_SAAS_API_KEY;
+	return Boolean(process.env.SKILLS_SAAS_API_KEY);
 }
 
 /**
@@ -250,7 +302,7 @@ export function getSyncStatus(): {
 	const cache = getCachedSkills();
 	return {
 		configured: isSkillSyncConfigured(),
-		cacheValid: !!cache,
+		cacheValid: Boolean(cache),
 		cachedSkills: cache?.skills.length ?? 0,
 	};
 }