pi-harness-runtime 1.1.410 → 1.1.412

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,
 	};
 }

package/harness/skills-startup.ts

@@ -0,0 +1,202 @@
+/**
+ * The startup line of the skill system.
+ *
+ * The line carries TWO counts: the skills on this machine and the skills in
+ * the vector store. They are different things - a machine without local
+ * skill files can still reach a shared skill - and a single "N discovered"
+ * hides exactly that difference.
+ *
+ * The vector store has states that must not be flattened into "0": no
+ * credentials, an unreachable cluster and an empty collection are three
+ * different situations and need three different actions.
+ */
+
+/** What the vector store is in this run. */
+export type QdrantSkillState =
+	/** No credentials for the vector store on this machine. */
+	| "not-configured"
+	/** The cluster is configured but cannot be reached. */
+	| "unavailable"
+	/** The cluster is reachable but the collection does not exist yet. */
+	| "missing"
+	/** The collection exists but holds no skill. */
+	| "empty"
+	/** The collection holds skills. */
+	| "populated";
+
+/** The state of the skill vector store. */
+export interface QdrantSkillStats {
+	/** What the vector store is in this run. */
+	state: QdrantSkillState;
+	/** The number of skill vectors in the collection. */
+	count: number;
+	/** The collection the numbers belong to. */
+	collection?: string;
+	/** The vector size the collection was created with. */
+	dimensions?: number;
+	/** The distance the collection was created with. */
+	distance?: string;
+	/** Why the collection could not be read. Never a credential. */
+	error?: string;
+	/** The collection does not match the schema of the runtime. */
+	schemaMismatch?: string;
+}
+
+export interface SkillsStartupReport {
+	/** The text of the line. */
+	text: string;
+	/** The status of the line. */
+	status: "wait" | "ok" | "info" | "warn";
+	/** The fix instructions below the line. */
+	details: string[];
+}
+
+/**
+ * The state of the service that holds the server-side skills.
+ *
+ * The vector store is the INDEX. The service holds the authoritative
+ * files, so it is the one that can hand out a complete skill.
+ */
+export interface RemoteSkillStats {
+	/** What the service is in this run. */
+	state:
+		/** No service is configured. */
+		| "not-configured"
+		/** The service refused the call - the token or the plan. */
+		| "denied"
+		/** The service could not be reached. */
+		| "unavailable"
+		/** The service holds no skill for this user. */
+		| "empty"
+		/** The service holds skills. */
+		| "populated";
+	/** The number of skills the service holds. */
+	count: number;
+	/** Why the service could not be reached. Never a credential. */
+	error?: string;
+}
+
+/**
+ * The line before the vector store has answered.
+ *
+ * The count of the local skills is known immediately; the count of the
+ * vector store needs the cluster, so the line waits for it.
+ */
+export function localSkillsReport(localCount: number): SkillsStartupReport {
+	return {
+		text: `Local Skills ${localCount} | Qdrant Skills ...`,
+		status: "wait",
+		details: [],
+	};
+}
+
+/**
+ * The line with the state of the vector store.
+ *
+ * The number is only shown when it is known: a cluster that cannot be
+ * reached has no count, and "0" would be a lie.
+ */
+export function skillsReport(
+	localCount: number,
+	stats: QdrantSkillStats,
+	remote?: RemoteSkillStats,
+): SkillsStartupReport {
+	const details: string[] = [];
+
+	if (stats.schemaMismatch) {
+		details.push(
+			`The vector schema does not match: ${stats.schemaMismatch}.`,
+			"A collection with a different vector size cannot be searched with these vectors, so the vector search finds nothing.",
+			`The runtime uses the collection ${stats.collection ?? "pi-harness-skills-openai-v1"} - move the shared skills into it.`,
+		);
+	}
+	if (stats.state === "unavailable") {
+		details.push(
+			stats.error
+				? `The vector store could not be reached: ${stats.error}`
+				: "The vector store could not be reached.",
+		);
+	}
+	details.push(...remoteDetails(remote));
+
+	return {
+		text: `Local Skills ${localCount} | Qdrant Skills ${describeQdrantState(stats)}`,
+		status: startupStatus(stats, remote),
+		details,
+	};
+}
+
+/**
+ * The lines below the count.
+ *
+ * The service is reported separately from the vector store: it holds the
+ * complete skills, the vector store only the index.
+ */
+function remoteDetails(remote: RemoteSkillStats | undefined): string[] {
+	if (!remote || remote.state === "not-configured") return [];
+
+	if (remote.state === "populated") {
+		return [
+			`The skill service holds ${remote.count} skill${remote.count === 1 ? "" : "s"} - they can be loaded without a local copy.`,
+		];
+	}
+	if (remote.state === "denied") {
+		return [
+			remote.error
+				? `The skill service refused the call: ${remote.error}`
+				: "The skill service refused the call - the token or the plan does not allow it.",
+			"Fix: check SKILLS_SAAS_API_KEY and the plan of the account.",
+		];
+	}
+	if (remote.state === "unavailable") {
+		return [
+			remote.error
+				? `The skill service could not be reached: ${remote.error}`
+				: "The skill service could not be reached.",
+		];
+	}
+	return [];
+}
+
+/**
+ * The status of the line.
+ *
+ * A vector store that is not configured is not a problem - most machines
+ * do not have one - so it is an information. An unreachable cluster and an
+ * incompatible collection are warnings: something is broken there.
+ */
+function startupStatus(
+	stats: QdrantSkillStats,
+	remote?: RemoteSkillStats,
+): "ok" | "info" | "warn" {
+	if (stats.state === "unavailable" || stats.schemaMismatch) return "warn";
+	if (remote && (remote.state === "denied" || remote.state === "unavailable")) {
+		return "warn";
+	}
+	if (stats.state === "not-configured") return "info";
+	return "ok";
+}
+
+/**
+ * The short form of the vector store state.
+ *
+ * "0" means "the remote set is empty" - whether the collection does not
+ * exist yet or holds no skill. The other states say what is wrong.
+ */
+function describeQdrantState(stats: QdrantSkillStats): string {
+	switch (stats.state) {
+		case "not-configured":
+			return "not configured";
+		case "unavailable":
+			return "unavailable";
+		case "missing":
+		case "empty":
+			return "0";
+		case "populated":
+			return String(stats.count);
+		default:
+			// An unknown state is treated like an unreachable cluster: no
+			// count is shown, because a wrong number is worse than none.
+			return "unavailable";
+	}
+}