pi-harness-runtime 1.1.411 → 1.1.413

package/harness/skills-startup.ts

@@ -0,0 +1,229 @@
+/**
+ * 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;
+	/**
+	 * The collection of an earlier installation that still holds the skills.
+	 *
+	 * The runtime collection is empty while the legacy one holds the skills
+	 * of the previous version. They are not lost - they live in a
+	 * collection with another name, and one with another vector size.
+	 */
+	legacy?: {
+		/** The name of the collection. */
+		collection: string;
+		/** The number of skill vectors it holds. */
+		count: number;
+		/** The vector size it was created with. */
+		dimensions?: number;
+		/** The embedding model it was created with. */
+		model?: 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.",
+		);
+	}
+	if (stats.legacy) {
+		const legacy = stats.legacy;
+		details.push(
+			`The collection ${legacy.collection} still holds ${legacy.count} skill${legacy.count === 1 ? "" : "s"}` +
+				(legacy.dimensions ? ` with ${legacy.dimensions}-dimensional vectors` : "") +
+				(legacy.model ? ` (${legacy.model})` : "") +
+				" - the runtime embeds with 1536 dimensions, so these skills cannot be found until they are moved.",
+			`Move them into ${stats.collection ?? "pi-harness-skills-openai-v1"} - scripts/sync-to-qdrant.ts writes them there.`,
+		);
+	}
+	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";
+	}
+}

package/harness/startup-report.ts

@@ -13,7 +13,7 @@
 
 import type { KeyFileAuditResult } from "./key-file-audit.ts";
 
-export type StartupStatus = "wait" | "ok" | "warn" | "err";
+export type StartupStatus = "wait" | "ok" | "info" | "warn" | "err";
 
 export interface StartupReport {
 	/** The label of the startup line ("Jev", "Relay", "LINE"). */
@@ -141,12 +141,28 @@ export function relayEndpointReport(options: {
 	};
 }
 
+/**
+ * The two steps that create a usable LINE channel.
+ *
+ * They are shown whenever the credentials are missing: a warning that names
+ * only the key files leaves the user without a way to get the values.
+ */
+export const LINE_SETUP_STEPS: readonly string[] = [
+	"Create a LINE Messaging API channel in LINE Developers Console.",
+	"Issue a Long-term channel access token and get Your user ID from Basic settings.",
+];
+
 /**
  * The LINE line.
  *
- * Returns null when LINE must not be reported at all: a user who never
- * touched LINE must not see a warning on every start. The line appears as
- * soon as one of the LINE client key files exists.
+ * The line is ALWAYS reported: Telegram and LINE are the two notification
+ * channels, and a fresh install must show both of them next to each other -
+ * a user who has never heard of LINE cannot miss the channel they do not
+ * have yet.
+ *
+ * "Disabled" is never inferred from the absence of key files. Only an
+ * explicit opt-out (the user turned the channel off) produces the
+ * informational disabled state.
  *
  * The audit is passed in (and not read here) so that the rule "never report
  * LINE as configured when the audit failed" can be tested.
@@ -154,8 +170,13 @@ export function relayEndpointReport(options: {
 export function lineConfigurationReport(options: {
 	/** The audit result, or null when the audit could not run. */
 	audit: KeyFileAuditResult | null;
-	/** Does a LINE client key file exist (line-access-token.txt / line-user-id.txt)? */
-	clientKeyFilePresent: boolean;
+	/**
+	 * Did the user explicitly turn the LINE channel off?
+	 *
+	 * A missing key file is NOT a disabled channel - it is a channel that was
+	 * never configured.
+	 */
+	disabled?: boolean;
 	/**
 	 * The fix commands for Telegram.
 	 *
@@ -196,8 +217,22 @@ export function lineConfigurationReport(options: {
 	 */
 	channelDiagnostic?: string | null;
 }): StartupReport | null {
-	if (!options.clientKeyFilePresent) return null;
 	const channelState = options.channelState ?? "not-started";
+
+	// An explicit opt-out is an information, not a warning: the user asked
+	// for it and the channel works as told.
+	if (options.disabled) {
+		return {
+			label: "LINE",
+			text: "disabled",
+			status: "info",
+			details: [
+				"The LINE channel is turned off in the notification settings.",
+				"Turn it on again with: /notify-settings line on",
+			],
+		};
+	}
+
 	if (!options.audit) {
 		// The audit failed: LINE must not be reported as configured.
 		const details = options.fixes.length > 0 ? options.fixes : [];
@@ -214,64 +249,71 @@ export function lineConfigurationReport(options: {
 		};
 	}
 	const missing = options.audit.byFeature.get("LINE") ?? [];
-	if (missing.length === 0) {
-		if (channelState === "started") {
-			// The runtime reported the green line itself ("configured and
-			// enabled") - a second LINE line would only overwrite it.
-			return null;
-		}
-		if (channelState === "failed") {
-			// The credentials are there but the channel did not start - the
-			// channel access token is what the startup check validates, so
-			// the user id must not be named as the cause.
-			const details = [
-				...(options.accessTokenFixes && options.accessTokenFixes.length > 0
-					? options.accessTokenFixes
-					: options.fixes),
-			];
-			if (options.channelDiagnostic) {
-				details.push(options.channelDiagnostic);
-			}
-			details.push(
-				"The startup check validates the channel access token - the user id is only the recipient of the messages.",
-			);
-			details.push(
-				"Fix the file, then reload Pi so the channel is checked again.",
-			);
-			return {
-				label: "LINE",
-				text: "configured but the LINE channel did not start",
-				status: "warn",
-				details,
-			};
-		}
-		// The credentials are there but the channel was never started in this
-		// run - say so instead of showing a green line. The cause differs:
-		// without Telegram the channel cannot start at all, with Telegram the
-		// credentials were simply created after the harness was loaded.
-		const cause = options.telegramConfigured
-			? "The LINE channel starts together with the Telegram channel - the key files were created after Pi was loaded."
-			: "The LINE channel starts together with the Telegram channel - it cannot start before Telegram works.";
+	if (missing.length > 0) {
+		// The credentials are missing (no key file at all, or a file the
+		// reader rejects). The warning names the two files AND the two steps
+		// that produce their values - otherwise the user is stuck.
 		return {
 			label: "LINE",
-			// The text names the action - a reload only helps when Telegram
-			// works; otherwise the user has to configure Telegram first.
-			text: options.telegramConfigured
-				? "configured; reload Pi to enable the channel"
-				: "configured; Telegram must be configured first",
+			text: "credentials missing; notifications unavailable",
 			status: "warn",
 			details: [
-				cause,
-				// Without Telegram the user needs the Telegram commands - the
-				// line must not be the only warning without an action.
-				...(options.telegramConfigured ? [] : (options.telegramFixes ?? [])),
+				...LINE_SETUP_STEPS,
+				...options.fixes,
+				"Then reload Pi so the channel is checked again.",
 			],
 		};
 	}
+	if (channelState === "started") {
+		// The runtime reported the green line itself ("configured and
+		// enabled") - a second LINE line would only overwrite it.
+		return null;
+	}
+	if (channelState === "failed") {
+		// The credentials are there but the channel did not start - the
+		// channel access token is what the startup check validates, so
+		// the user id must not be named as the cause.
+		const details = [
+			...(options.accessTokenFixes && options.accessTokenFixes.length > 0
+				? options.accessTokenFixes
+				: options.fixes),
+		];
+		if (options.channelDiagnostic) {
+			details.push(options.channelDiagnostic);
+		}
+		details.push(
+			"The startup check validates the channel access token - the user id is only the recipient of the messages.",
+		);
+		details.push(
+			"Fix the file, then reload Pi so the channel is checked again.",
+		);
+		return {
+			label: "LINE",
+			text: "configured but the LINE channel did not start",
+			status: "warn",
+			details,
+		};
+	}
+	// The credentials are there but the channel was never started in this
+	// run - say so instead of showing a green line. The cause differs:
+	// without Telegram the channel cannot start at all, with Telegram the
+	// credentials were simply created after the harness was loaded.
+	const cause = options.telegramConfigured
+		? "The LINE channel starts together with the Telegram channel - the key files were created after Pi was loaded."
+		: "The LINE channel starts together with the Telegram channel - it cannot start before Telegram works.";
 	return {
 		label: "LINE",
-		text: "not configured",
+		// The text names the action - a reload only helps when Telegram
+		// works; otherwise the user has to configure Telegram first.
+		text: options.telegramConfigured
+			? "configured; reload Pi to enable the channel"
+			: "configured; Telegram must be configured first",
 		status: "warn",
-		details: [...options.fixes, "Configure LINE in ~/.pi-harness-runtime/keys/, then reload Pi."],
+		details: [
+			cause,
+			// Without Telegram the user needs the Telegram commands - the
+			// line must not be the only warning without an action.
+			...(options.telegramConfigured ? [] : (options.telegramFixes ?? [])),
+		],
 	};
 }

package/harness-startup-status.ts

@@ -1,4 +1,4 @@
-export type HarnessStatus = "wait" | "ok" | "warn" | "err";
+export type HarnessStatus = "wait" | "ok" | "info" | "warn" | "err";
 
 export interface HarnessMessage {
 	id: string;
@@ -20,8 +20,37 @@ export class HarnessStartupStatus {
 		else this.messages[existing] = next;
 		this.onChange?.();
 	}
+
+	/**
+	 * Put a message directly after another one.
+	 *
+	 * Two rows that belong together stay together: the notification channels
+	 * (Telegram and LINE) must not be separated by a row that another
+	 * feature added in between. A message that does not exist yet is
+	 * inserted; an existing one is moved.
+	 */
+	updateAfter(
+		anchorLabel: string,
+		label: string,
+		text: string,
+		status: HarnessStatus = "wait",
+		details?: string[],
+	): void {
+		const next = { id: label, label, text, status, details };
+		const existing = this.messages.findIndex((message) => message.id === label);
+		if (existing !== -1) this.messages.splice(existing, 1);
+		const anchor = this.messages.findIndex((message) => message.id === anchorLabel);
+		if (anchor === -1) {
+			// Without the anchor there is nothing to be next to - the row
+			// goes to the end instead of being lost.
+			this.messages.push(next);
+		} else {
+			this.messages.splice(anchor + 1, 0, next);
+		}
+		this.onChange?.();
+	}
 }
 
 export function harnessStatusMarker(status: HarnessStatus): string {
-	return { wait: "[WAIT]", ok: "[OK]", warn: "[WARN]", err: "[ERR]" }[status];
+	return { wait: "[WAIT]", ok: "[OK]", info: "[INFO]", warn: "[WARN]", err: "[ERR]" }[status];
 }