@narumitw/pi-analytics 0.45.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# 📈 pi-analytics — Local Analytics for Pi
+
+[![npm](https://img.shields.io/npm/v/@narumitw/pi-analytics)](https://www.npmjs.com/package/@narumitw/pi-analytics) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+> [!WARNING]
+> This extension is experimental. Its metrics, storage format, and dashboard may change between releases.
+
+`@narumitw/pi-analytics` is a local-first [Pi coding agent](https://pi.dev) extension that counts model calls, skill activations, tool activity, and observed provider errors without storing conversation or tool content.
+
+## ✨ Features
+
+- Starts collecting settled Pi response cycles after installation with no configuration.
+- Breaks skill activations down by explicit user invocation, model loading, provider, and model.
+- Counts tool calls, failures, average duration, and model attribution.
+- Reports logical LLM calls per response with average, median, P95, maximum, and distribution buckets.
+- Separates HTTP 429/5xx responses, conservative connection-error categories, recovered errors, and terminal provider failures.
+- Offers Today, rolling 7-day, rolling 30-day, and all-time views through one `/analytics` TUI/RPC dashboard.
+- Stores only content-free metadata in one private local Turso Database.
+- Uses forward-only, checksummed, transactional schema migrations and fails closed on unknown newer schemas.
+- Never starts a server, contacts Turso Cloud, or sends analytics anywhere.
+
+## 📦 Install
+
+Install persistently:
+
+```bash
+pi install npm:@narumitw/pi-analytics
+```
+
+Try the published package without installing:
+
+```bash
+pi -e npm:@narumitw/pi-analytics
+```
+
+Try a local checkout from the repository root:
+
+```bash
+pi -e ./experimental/pi-analytics
+```
+
+### Supported platforms
+
+The embedded `@tursodatabase/database` dependency currently publishes native binaries for:
+
+- Linux x64 and arm64 with glibc;
+- macOS arm64; and
+- Windows x64.
+
+On another platform, Pi still loads the extension and `/analytics` remains available, but collection is disabled and the dashboard explains the supported platform boundary. The database engine is pre-1.0. Analytics are treated as non-critical derived metadata. If the history itself matters, stop every Pi process using the extension and back up both `pi-analytics.db` and `pi-analytics.db-wal`; copying only the main file is not a complete backup.
+
+## 🚀 Quick start
+
+Complete at least one Pi response, then run:
+
+```text
+/analytics
+```
+
+The default overview covers the last seven rolling days:
+
+```text
+Analytics · Last 7 days
+
+Response cycles                    83
+LLM calls                         192
+Calls per response        2.31 · P95 6
+Tool calls                        414
+Tool errors                         7
+Skill activations                  31
+Provider errors                     4
+Recovered errors                    3
+```
+
+Use the menu to change the time range or browse Skills, Tools, Provider reliability, Response cycles, and Data & privacy. Only fully settled cycles are included; active work is omitted until Pi settles.
+
+## 📐 Metric definitions
+
+### Response cycles and LLM calls
+
+A **response cycle** starts when Pi begins agent work and ends at `agent_settled`. Automatic retries, overflow-compaction recovery, tool follow-ups, and queued continuations before settlement stay in that cycle.
+
+An **LLM call** is one logical provider generation. A provider may make several HTTP attempts inside it, so `429 → 429 → 200` is one LLM call, three observed HTTP responses, two provider errors, and a recovered generation.
+
+### Skills
+
+An activation is **User initiated** when an observed interactive or RPC `/skill:<name>` input is associated with an active or subsequently started response cycle. This includes skill commands queued while Pi is streaming. It is **Model initiated** when the built-in `read` tool successfully loads the exact canonical `SKILL.md` path Pi discovered. A skill is counted at most once per response cycle, and explicit user use takes precedence.
+
+Pi does not expose a first-class skill-invocation event or a post-chain acceptance event for input observers. Non-standard loading such as `bash` plus `cat SKILL.md`, unsuccessful reads, and provider behavior invisible to Pi are not counted; an explicit skill input intercepted later by another extension while a response is active may still be observed.
+
+### Tools
+
+A tool call starts at Pi's `tool_execution_start` event and finishes at `tool_execution_end`. The extension stores the tool name, model attribution, timing, completion state, and final error flag. It cannot reliably distinguish another extension blocking a call from every other tool error, so the MVP reports both as errors rather than claiming a separate blocked count.
+
+### Provider reliability
+
+Pi exposes HTTP responses and final assistant failures, not every provider-SDK transport retry. The dashboard therefore labels these values as **observed provider errors**. It reports:
+
+- HTTP 429 and 5xx counts;
+- DNS, timeout, connection-refused, connection-reset, TLS, other-network, and other-provider categories;
+- recovered errors; and
+- terminal failures.
+
+Error messages are classified in memory and discarded. Raw error text is never stored.
+
+## 💬 Command
+
+```text
+/analytics
+```
+
+The command accepts no arguments. TUI mode uses the full dashboard; RPC mode adapts the same standard screens to dialogs. Print and JSON modes reject the interactive command observably instead of writing ad hoc protocol output.
+
+The root menu contains seven actions:
+
+```text
+Change time range
+Skills
+Tools
+Provider reliability
+Response cycles
+Data & privacy
+Close
+```
+
+Skills and Tools are searchable browse views with details and model breakdowns. Escape goes Back from nested screens and closes the root. Ctrl+C closes the menu. Cancelling data deletion has no side effects.
+
+## 🔐 Local data and privacy
+
+The database is stored at:
+
+```text
+<pi-agent-directory>/pi-analytics.db
+```
+
+On Unix, the extension pre-creates and restricts the database and WAL files to mode `0600`, repairs their permissions after migration, and refuses linked database files.
+
+Stored fields are limited to:
+
+- timestamps and durations;
+- provider/model IDs and thinking level;
+- tool and skill names;
+- user/model skill source;
+- counts, outcomes, and completion states;
+- HTTP status codes; and
+- classified provider-error categories.
+
+The extension does **not** store:
+
+- prompts, responses, or thinking content;
+- tool arguments or results;
+- raw error messages or HTTP headers;
+- cwd, project names, file paths, session names, or Pi session IDs; or
+- credentials.
+
+It imports only the local embedded database package. It does not install `@tursodatabase/sync`, request Turso credentials, contact Turso Cloud, or perform any other remote telemetry.
+
+Choose **Data & privacy → Clear analytics data…** to transactionally remove all currently committed response, model, skill, tool, and reliability observations. Migration history remains so the valid schema can continue to be used. Another running Pi process may commit a newly settled response after the clear operation.
+
+## 🧱 Database migrations and recovery
+
+Schema migrations are numbered, immutable, contiguous, and checksummed. Pending migrations recheck and apply inside an exclusive transaction with bounded conflict retry, so two Pi processes cannot publish half of a migration. Runtime schema changes follow additive-first compatibility: add nullable columns or tables before considering any later contraction.
+
+The extension never downgrades, repairs, deletes, or recreates a database automatically. If a migration fails, an applied checksum differs, or the database was created by a newer extension version, collection fails closed and existing bytes remain in place. Update the extension or restore a user-managed backup before retrying.
+
+Settled response publication is one atomic transaction. A failed write leaves prior data valid and is retained for bounded retry while that Pi session remains open. Graceful shutdown drains pending writes and closes the session-owned connection.
+
+## 🚧 MVP limitations
+
+- There are no retention settings; records remain until explicitly cleared.
+- Prometheus, JSON/CSV export, Turso Cloud sync, browser dashboards, token/cost reporting, and project attribution are not included.
+- Statistics cover only events visible through Pi's public extension API.
+- Clearing rows is logical deletion, not a secure-erasure guarantee for underlying storage media.
+
+## 🗂️ Package layout
+
+```text
+experimental/pi-analytics/
+├── src/
+│   ├── index.ts              # Thin Pi entrypoint
+│   ├── analytics.ts          # Pi lifecycle, command, and session ownership
+│   ├── collector.ts          # Content-free response-cycle state machine
+│   ├── errors.ts             # Conservative error classification
+│   ├── skills.ts             # Explicit and model skill detection
+│   ├── menu.ts               # TUI/RPC analytics dashboard
+│   ├── types.ts              # Observation records
+│   └── storage/
+│       ├── database.ts       # Dynamic driver startup and private file lifecycle
+│       ├── migrations.ts     # Transactional checksummed schema history
+│       ├── queries.ts        # Indexed aggregate projections
+│       └── store.ts          # Atomic writes, retries, queries, and clear
+├── test/
+├── README.md
+├── LICENSE
+├── package.json
+└── tsconfig.json
+```
+
+## 🔎 Keywords
+
+Pi extension, Pi coding agent, local analytics, agent skills, tool usage, model calls, provider reliability, Turso Database, SQLite-compatible metrics.
+
+## 📄 License
+
+MIT. See [`LICENSE`](./LICENSE).

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@narumitw/pi-analytics",
+	"version": "0.45.0",
+	"description": "Local-first usage analytics for Pi models, skills, tools, and reliability.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"analytics",
+		"metrics",
+		"turso"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check --vcs-use-ignore-file=false src test package.json tsconfig.json README.md && npm run typecheck",
+		"format": "biome check --write --vcs-use-ignore-file=false src test package.json tsconfig.json README.md",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@narumitw/pi-tui-kit": "^0.45.0",
+		"@tursodatabase/database": "^0.7.2"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.6",
+		"@earendil-works/pi-coding-agent": "0.83.0",
+		"@types/node": "26.1.2",
+		"typescript": "7.0.2"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/narumiruna/pi-extensions",
+		"directory": "experimental/pi-analytics"
+	}
+}

package/src/analytics.ts

@@ -0,0 +1,406 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import {
+	type ExtensionAPI,
+	type ExtensionContext,
+	getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+import { ResponseCollector } from "./collector.js";
+import { type AnalyticsMenuDataSource, showAnalyticsMenu } from "./menu.js";
+import { SkillTracker } from "./skills.js";
+import { AnalyticsDatabaseOpenError, openAnalyticsDatabase } from "./storage/database.js";
+import {
+	ChecksumMismatchError,
+	MigrationFailedError,
+	NewerSchemaError,
+} from "./storage/migrations.js";
+import type { AnalyticsSnapshot, TimeRange } from "./storage/queries.js";
+import { AnalyticsStore } from "./storage/store.js";
+import type { ModelIdentity, SettledRun, TriggerSource } from "./types.js";
+
+const EXPERIMENTAL_WARNING = "pi-analytics is experimental; its metrics and dashboard may change.";
+
+export interface AnalyticsStorePort {
+	readonly path: string;
+	recordRun(run: SettledRun): Promise<void>;
+	getSnapshot(range: TimeRange): Promise<AnalyticsSnapshot>;
+	clearAll(): Promise<number>;
+	close(): Promise<void>;
+}
+
+interface AnalyticsDependencies {
+	openStore(path: string): Promise<AnalyticsStorePort>;
+	getAgentDir(): string;
+	now(): number;
+	createId(): string;
+	platform(): string;
+}
+
+export function createAnalyticsExtension(
+	dependencies: Partial<AnalyticsDependencies> = {},
+): (pi: ExtensionAPI) => void {
+	const deps: AnalyticsDependencies = {
+		openStore:
+			dependencies.openStore ??
+			(async (databasePath) =>
+				new AnalyticsStore(await openAnalyticsDatabase({ path: databasePath }))),
+		getAgentDir: dependencies.getAgentDir ?? getAgentDir,
+		now: dependencies.now ?? Date.now,
+		createId: dependencies.createId ?? randomUUID,
+		platform: dependencies.platform ?? runtimePlatform,
+	};
+
+	return function analyticsExtension(pi: ExtensionAPI): void {
+		let sessionGeneration = 0;
+		let sessionController = new AbortController();
+		let collector = new ResponseCollector();
+		let skillTracker: SkillTracker | undefined;
+		let store: AnalyticsStorePort | undefined;
+		let storageFailure: string | undefined;
+		let startupTask: Promise<void> | undefined;
+		let writeFailureActive = false;
+		let pendingTriggerSource: TriggerSource = "unknown";
+		let pendingAttemptWithoutRun = false;
+
+		pi.registerCommand("analytics", {
+			description: "Open local Pi usage analytics",
+			handler: async (args, ctx) => {
+				if (args.trim()) {
+					if (!ctx.hasUI || (ctx.mode !== "tui" && ctx.mode !== "rpc")) {
+						throw new Error("/analytics does not accept arguments.");
+					}
+					ctx.ui.notify("/analytics does not accept arguments.", "warning");
+					return;
+				}
+				if (!ctx.hasUI || (ctx.mode !== "tui" && ctx.mode !== "rpc")) {
+					throw new Error("/analytics requires Pi TUI or RPC mode.");
+				}
+				const generation = sessionGeneration;
+				const owner = sessionController;
+				const source = menuSource(generation, owner.signal);
+				await showAnalyticsMenu(ctx, source, {
+					signal: owner.signal,
+					isCurrent: () => generation === sessionGeneration && !owner.signal.aborted,
+				});
+			},
+		});
+
+		pi.on("session_start", async (_event, ctx) => {
+			const generation = ++sessionGeneration;
+			if (ctx.hasUI) ctx.ui.notify(EXPERIMENTAL_WARNING, "warning");
+			sessionController.abort(new DOMException("Analytics session replaced", "AbortError"));
+			sessionController = new AbortController();
+			collector = new ResponseCollector();
+			skillTracker = new SkillTracker(ctx.cwd);
+			store = undefined;
+			storageFailure = undefined;
+			writeFailureActive = false;
+			pendingTriggerSource = "unknown";
+			pendingAttemptWithoutRun = false;
+			const databasePath = path.join(deps.getAgentDir(), "pi-analytics.db");
+			const task = (async () => {
+				try {
+					const opened = await deps.openStore(databasePath);
+					if (generation !== sessionGeneration) {
+						await opened.close();
+						return;
+					}
+					store = opened;
+				} catch (error) {
+					if (generation !== sessionGeneration) return;
+					storageFailure = storageFailureMessage(error, deps.platform());
+					safeNotify(ctx, storageFailure, "warning");
+				}
+			})();
+			startupTask = task;
+			await task;
+			if (startupTask === task) startupTask = undefined;
+		});
+
+		pi.on("input", (event, ctx) => {
+			const now = deps.now();
+			const tracker = skillTracker;
+			tracker?.observeInput(event.text, event.source, now);
+			if (event.source !== "extension") pendingTriggerSource = event.source;
+			if (!tracker || !collector.hasActiveRun()) return;
+			const explicit = tracker.consumeExplicitSkill();
+			if (!explicit || !tracker.hasAvailableSkill(explicit.name)) return;
+			collector.activateSkill({
+				name: explicit.name,
+				initiatedBy: "user",
+				now: explicit.observedAtMs,
+				model: modelIdentity(ctx, pi),
+			});
+		});
+
+		pi.on("before_agent_start", async (event, ctx) => {
+			const generation = sessionGeneration;
+			const tracker = skillTracker;
+			if (!tracker) return;
+			const skills = availableSkills(pi, event.systemPromptOptions.skills ?? []);
+			await tracker.setAvailableSkills(skills);
+			if (generation !== sessionGeneration || tracker !== skillTracker) return;
+			const explicit = tracker.consumeExplicitSkill();
+			const interrupted = collector.begin({
+				id: deps.createId(),
+				now: deps.now(),
+				triggerSource: explicit?.source ?? pendingTriggerSource,
+				model: modelIdentity(ctx, pi),
+			});
+			pendingTriggerSource = "unknown";
+			if (interrupted) await persistRun(interrupted, ctx, generation);
+			if (explicit && skills.some(({ name }) => name === explicit.name)) {
+				collector.activateSkill({
+					name: explicit.name,
+					initiatedBy: "user",
+					now: explicit.observedAtMs,
+					model: modelIdentity(ctx, pi),
+				});
+			}
+		});
+
+		pi.on("agent_start", () => {
+			if (collector.hasActiveRun()) collector.beginAttempt();
+			else pendingAttemptWithoutRun = true;
+		});
+
+		pi.on("turn_start", (_event, ctx) => {
+			ensureRun(ctx, "extension");
+		});
+
+		pi.on("before_provider_request", (_event, ctx) => {
+			ensureRun(ctx, "extension");
+			collector.beginGeneration({
+				id: deps.createId(),
+				now: deps.now(),
+				model: modelIdentity(ctx, pi),
+			});
+		});
+
+		pi.on("after_provider_response", (event) => {
+			collector.recordProviderResponse({ status: event.status, now: deps.now() });
+		});
+
+		pi.on("message_end", (event) => {
+			if (event.message.role !== "assistant") return;
+			collector.finishGeneration({
+				now: deps.now(),
+				stopReason: event.message.stopReason,
+				errorMessage: event.message.errorMessage,
+			});
+		});
+
+		pi.on("tool_execution_start", (event, ctx) => {
+			ensureRun(ctx, "extension");
+			collector.beginTool({
+				id: event.toolCallId,
+				name: event.toolName,
+				now: deps.now(),
+				model: modelIdentity(ctx, pi),
+			});
+		});
+
+		pi.on("tool_result", async (event, ctx) => {
+			if (event.toolName === "read" && !isBuiltinReadTool(pi)) return;
+			const generation = sessionGeneration;
+			const tracker = skillTracker;
+			if (!tracker) return;
+			const name = await tracker.matchSuccessfulRead({
+				toolName: event.toolName,
+				input: event.input,
+				isError: event.isError,
+			});
+			if (!name || generation !== sessionGeneration || tracker !== skillTracker) return;
+			collector.activateSkill({
+				name,
+				initiatedBy: "model",
+				now: deps.now(),
+				model: modelIdentity(ctx, pi),
+			});
+		});
+
+		pi.on("tool_execution_end", (event) => {
+			collector.finishTool({ id: event.toolCallId, now: deps.now(), isError: event.isError });
+		});
+
+		pi.on("agent_settled", async (_event, ctx) => {
+			const generation = sessionGeneration;
+			const run = collector.settle(deps.now());
+			pendingAttemptWithoutRun = false;
+			pendingTriggerSource = "unknown";
+			skillTracker?.clearPending();
+			if (run) await persistRun(run, ctx, generation);
+		});
+
+		pi.on("session_shutdown", async (_event, ctx) => {
+			const activeStore = store;
+			const activeStartup = startupTask;
+			++sessionGeneration;
+			sessionController.abort(new DOMException("Analytics session shut down", "AbortError"));
+			skillTracker?.clearPending();
+			skillTracker = undefined;
+			store = undefined;
+			const run = collector.interrupt(deps.now());
+			if (run && activeStore) {
+				await activeStore.recordRun(run).catch(() => {
+					safeNotify(ctx, "Analytics could not save the interrupted response cycle.", "warning");
+				});
+			}
+			await activeStartup?.catch(() => undefined);
+			await activeStore?.close().catch(() => {
+				safeNotify(
+					ctx,
+					"Analytics storage shutdown was incomplete; some pending metrics may not have been saved.",
+					"warning",
+				);
+			});
+		});
+
+		function ensureRun(ctx: ExtensionContext, triggerSource: TriggerSource): void {
+			if (collector.hasActiveRun()) return;
+			collector.begin({
+				id: deps.createId(),
+				now: deps.now(),
+				triggerSource,
+				model: modelIdentity(ctx, pi),
+			});
+			if (pendingAttemptWithoutRun) {
+				pendingAttemptWithoutRun = false;
+				collector.beginAttempt();
+			}
+		}
+
+		async function persistRun(
+			run: SettledRun,
+			ctx: ExtensionContext,
+			generation: number,
+		): Promise<void> {
+			const activeStore = store;
+			if (!activeStore) return;
+			try {
+				await activeStore.recordRun(run);
+				if (generation !== sessionGeneration || activeStore !== store) return;
+				if (writeFailureActive) {
+					writeFailureActive = false;
+					safeNotify(ctx, "Local analytics storage recovered.", "info");
+				}
+			} catch {
+				if (generation !== sessionGeneration || activeStore !== store || writeFailureActive) return;
+				writeFailureActive = true;
+				safeNotify(
+					ctx,
+					"Analytics could not save a response cycle; it will retry while this Pi session remains open.",
+					"warning",
+				);
+			}
+		}
+
+		function menuSource(generation: number, signal: AbortSignal): AnalyticsMenuDataSource {
+			return {
+				path: store?.path ?? path.join(deps.getAgentDir(), "pi-analytics.db"),
+				async load(range) {
+					assertCurrent(generation, signal);
+					const activeStore = store;
+					if (!activeStore) {
+						return {
+							kind: "unavailable",
+							message: storageFailure ?? unavailableMessage(deps.platform()),
+						};
+					}
+					const snapshot = await activeStore.getSnapshot(range);
+					assertCurrent(generation, signal);
+					return { kind: "ready", snapshot };
+				},
+				async clearAll() {
+					assertCurrent(generation, signal);
+					const activeStore = store;
+					if (!activeStore) return 0;
+					const count = await activeStore.clearAll();
+					assertCurrent(generation, signal);
+					return count;
+				},
+			};
+		}
+
+		function assertCurrent(generation: number, signal: AbortSignal): void {
+			if (generation !== sessionGeneration || signal.aborted) {
+				throw new DOMException("Analytics interaction replaced", "AbortError");
+			}
+		}
+	};
+}
+
+function modelIdentity(ctx: ExtensionContext, pi: ExtensionAPI): ModelIdentity | undefined {
+	if (!ctx.model) return undefined;
+	return {
+		provider: ctx.model.provider,
+		model: ctx.model.id,
+		thinkingLevel: pi.getThinkingLevel(),
+	};
+}
+
+export function isBuiltinReadTool(pi: ExtensionAPI): boolean {
+	const read = pi.getAllTools().find(({ name }) => name === "read");
+	return read?.sourceInfo.source === "builtin";
+}
+
+function availableSkills(
+	pi: ExtensionAPI,
+	systemSkills: ReadonlyArray<{ name: string; filePath: string }>,
+): Array<{ name: string; filePath: string }> {
+	const result = [...systemSkills];
+	const seen = new Set(result.map(({ name }) => name));
+	const getCommands = (pi as ExtensionAPI & { getCommands?: ExtensionAPI["getCommands"] })
+		.getCommands;
+	for (const command of typeof getCommands === "function" ? getCommands.call(pi) : []) {
+		if (command.source !== "skill" || seen.has(command.name.replace(/^skill:/u, ""))) continue;
+		const name = command.name.replace(/^skill:/u, "");
+		seen.add(name);
+		result.push({ name, filePath: command.sourceInfo.path });
+	}
+	return result;
+}
+
+function runtimePlatform(): string {
+	if (process.platform !== "linux") return `${process.platform}-${process.arch}`;
+	const report = process.report?.getReport() as
+		| { header?: { glibcVersionRuntime?: unknown } }
+		| undefined;
+	const glibc = report?.header?.glibcVersionRuntime;
+	return `linux-${process.arch}-${glibc ? "glibc" : "non-glibc"}`;
+}
+
+function storageFailureMessage(error: unknown, platform: string): string {
+	if (error instanceof AnalyticsDatabaseOpenError) {
+		return `${error.message}\nExisting files were not replaced. Repair or restore them before retrying.\nNo analytics are being collected.`;
+	}
+	if (error instanceof NewerSchemaError) {
+		return `${error.message}\nUpdate pi-analytics before using this database.\nNo analytics are being collected.`;
+	}
+	if (error instanceof ChecksumMismatchError) {
+		return `${error.message}\nRestore a known database backup or update pi-analytics.\nNo analytics are being collected.`;
+	}
+	if (error instanceof MigrationFailedError) {
+		return `${error.message}\nThe previous valid schema was preserved.\nNo analytics are being collected.`;
+	}
+	return unavailableMessage(platform);
+}
+
+function unavailableMessage(platform: string): string {
+	return [
+		"Analytics storage is unavailable.",
+		`Platform: ${platform}`,
+		"Supported: Linux glibc x64/arm64, macOS arm64, Windows x64.",
+		"No analytics are being collected.",
+	].join("\n");
+}
+
+function safeNotify(ctx: ExtensionContext, message: string, level: "info" | "warning"): void {
+	try {
+		ctx.ui.notify(message, level);
+	} catch {
+		// A replaced Pi context cannot receive lifecycle feedback.
+	}
+}
+
+export default createAnalyticsExtension();