@narumitw/pi-analytics 0.45.0

package/src/skills.ts

@@ -0,0 +1,83 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import type { InputSource } from "@earendil-works/pi-coding-agent";
+
+export interface AvailableSkill {
+	name: string;
+	filePath: string;
+}
+
+export interface PendingExplicitSkill {
+	name: string;
+	observedAtMs: number;
+	source: "interactive" | "rpc";
+}
+
+export function explicitSkillName(text: string): string | undefined {
+	return text.match(/^\/skill:([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)(?:\s|$)/u)?.[1];
+}
+
+export class SkillTracker {
+	private pending: PendingExplicitSkill | undefined;
+	private readonly skillByPath = new Map<string, string>();
+	private readonly availableNames = new Set<string>();
+
+	constructor(private readonly cwd: string) {}
+
+	observeInput(text: string, source: InputSource, now: number): void {
+		if (source === "extension") return;
+		const name = explicitSkillName(text);
+		this.pending = name ? { name, observedAtMs: now, source } : undefined;
+	}
+
+	consumeExplicitSkill(): PendingExplicitSkill | undefined {
+		const pending = this.pending;
+		this.pending = undefined;
+		return pending;
+	}
+
+	clearPending(): void {
+		this.pending = undefined;
+	}
+
+	hasAvailableSkill(name: string): boolean {
+		return this.availableNames.has(name);
+	}
+
+	async setAvailableSkills(skills: readonly AvailableSkill[]): Promise<void> {
+		this.skillByPath.clear();
+		this.availableNames.clear();
+		const seenNames = new Set<string>();
+		for (const skill of skills) {
+			if (seenNames.has(skill.name)) continue;
+			seenNames.add(skill.name);
+			this.availableNames.add(skill.name);
+			const canonical = await canonicalPath(skill.filePath).catch(() =>
+				path.resolve(this.cwd, skill.filePath),
+			);
+			this.skillByPath.set(canonical, skill.name);
+		}
+	}
+
+	async matchSuccessfulRead(input: {
+		toolName: string;
+		input: unknown;
+		isError: boolean;
+	}): Promise<string | undefined> {
+		if (input.toolName !== "read" || input.isError || !isRecord(input.input)) return undefined;
+		const rawPath = input.input.path;
+		if (typeof rawPath !== "string" || rawPath.length === 0) return undefined;
+		const normalized = rawPath.startsWith("@") ? rawPath.slice(1) : rawPath;
+		const absolute = path.resolve(this.cwd, normalized);
+		const canonical = await canonicalPath(absolute).catch(() => absolute);
+		return this.skillByPath.get(canonical);
+	}
+}
+
+function canonicalPath(filePath: string): Promise<string> {
+	return realpath(filePath);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/storage/database.ts

@@ -0,0 +1,126 @@
+import { chmod, lstat, mkdir, open } from "node:fs/promises";
+import path from "node:path";
+import type { Database } from "@tursodatabase/database";
+import {
+	ChecksumMismatchError,
+	MigrationFailedError,
+	migrateDatabase,
+	NewerSchemaError,
+} from "./migrations.js";
+
+export interface TursoModule {
+	connect(
+		path: string,
+		options?: { timeout?: number; defaultQueryTimeout?: number },
+	): Promise<Database>;
+}
+
+export class AnalyticsStorageUnavailableError extends Error {
+	constructor(cause: unknown) {
+		super("Local analytics storage is unavailable on this runtime.", { cause });
+		this.name = "AnalyticsStorageUnavailableError";
+	}
+}
+
+export class AnalyticsDatabaseOpenError extends Error {
+	constructor(cause: unknown) {
+		super("The local analytics database could not be opened safely.", { cause });
+		this.name = "AnalyticsDatabaseOpenError";
+	}
+}
+
+export interface OpenedAnalyticsDatabase {
+	readonly connection: Database;
+	readonly path: string;
+	close(): Promise<void>;
+}
+
+export async function openAnalyticsDatabase(options: {
+	path: string;
+	loadModule?: () => Promise<TursoModule>;
+	connectionTimeoutMs?: number;
+	queryTimeoutMs?: number;
+}): Promise<OpenedAnalyticsDatabase> {
+	const loadModule = options.loadModule ?? defaultModuleLoader;
+	let module: TursoModule;
+	try {
+		module = await loadModule();
+	} catch (error) {
+		throw new AnalyticsStorageUnavailableError(error);
+	}
+
+	let database: Database | undefined;
+	try {
+		await mkdir(path.dirname(options.path), { recursive: true, mode: 0o700 });
+		await preparePrivateFile(options.path);
+		await preparePrivateFile(`${options.path}-wal`);
+		database = await module.connect(options.path, {
+			timeout: options.connectionTimeoutMs ?? 5_000,
+			defaultQueryTimeout: options.queryTimeoutMs ?? 5_000,
+		});
+		await migrateDatabase(database);
+		await protectDatabaseFiles(options.path);
+		let closed = false;
+		return {
+			connection: database,
+			path: options.path,
+			async close() {
+				if (closed) return;
+				closed = true;
+				await database?.close();
+			},
+		};
+	} catch (error) {
+		await database?.close().catch(() => undefined);
+		if (isMigrationError(error)) throw error;
+		throw new AnalyticsDatabaseOpenError(error);
+	}
+}
+
+async function protectDatabaseFiles(databasePath: string): Promise<void> {
+	for (const filePath of [databasePath, `${databasePath}-wal`, `${databasePath}-shm`]) {
+		await preparePrivateFile(filePath, filePath.endsWith("-shm"));
+	}
+}
+
+async function preparePrivateFile(filePath: string, optional = false): Promise<void> {
+	if (optional) {
+		try {
+			await lstat(filePath);
+		} catch (error) {
+			if (isNodeError(error) && error.code === "ENOENT") return;
+			throw error;
+		}
+	} else {
+		try {
+			const handle = await open(filePath, "wx", 0o600);
+			await handle.close();
+		} catch (error) {
+			if (!isNodeError(error) || error.code !== "EEXIST") throw error;
+		}
+	}
+	const metadata = await lstat(filePath);
+	if (!metadata.isFile() || metadata.isSymbolicLink()) {
+		throw new Error("Analytics database files must be regular files, not links.");
+	}
+	if (process.platform !== "win32") await chmod(filePath, 0o600);
+}
+
+function isMigrationError(
+	error: unknown,
+): error is ChecksumMismatchError | MigrationFailedError | NewerSchemaError {
+	return (
+		error instanceof ChecksumMismatchError ||
+		error instanceof MigrationFailedError ||
+		error instanceof NewerSchemaError
+	);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+async function defaultModuleLoader(): Promise<TursoModule> {
+	const specifier = "@tursodatabase/database";
+	return import(specifier);
+}

package/src/storage/migrations.ts

@@ -0,0 +1,257 @@
+import { createHash } from "node:crypto";
+import type { Database, Transaction } from "@tursodatabase/database";
+
+export interface SchemaMigration {
+	version: number;
+	name: string;
+	statements: readonly string[];
+}
+
+export class ChecksumMismatchError extends Error {
+	constructor(version: number) {
+		super(`Analytics migration v${version} no longer matches its applied checksum.`);
+		this.name = "ChecksumMismatchError";
+	}
+}
+
+export class MigrationFailedError extends Error {
+	readonly version: number;
+	readonly migrationName: string;
+
+	constructor(migration: SchemaMigration, cause: unknown) {
+		super(`Analytics migration v${migration.version} (${migration.name}) failed.`, { cause });
+		this.name = "MigrationFailedError";
+		this.version = migration.version;
+		this.migrationName = migration.name;
+	}
+}
+
+export class NewerSchemaError extends Error {
+	constructor(databaseVersion: number, supportedVersion: number) {
+		super(
+			`Analytics database schema v${databaseVersion} is newer than supported v${supportedVersion}.`,
+		);
+		this.name = "NewerSchemaError";
+	}
+}
+
+const CREATE_MIGRATIONS_TABLE = `
+CREATE TABLE IF NOT EXISTS schema_migrations (
+	version INTEGER PRIMARY KEY,
+	name TEXT NOT NULL,
+	checksum TEXT NOT NULL,
+	applied_at_ms INTEGER NOT NULL
+)`;
+
+export const ANALYTICS_MIGRATIONS: readonly SchemaMigration[] = [
+	{
+		version: 1,
+		name: "initial-analytics-schema",
+		statements: [
+			`CREATE TABLE response_runs (
+				id TEXT PRIMARY KEY,
+				started_at_ms INTEGER NOT NULL,
+				finished_at_ms INTEGER NOT NULL,
+				duration_ms INTEGER NOT NULL,
+				trigger_source TEXT NOT NULL,
+				initial_provider TEXT,
+				initial_model TEXT,
+				outcome TEXT NOT NULL,
+				attempt_count INTEGER NOT NULL,
+				generation_count INTEGER NOT NULL,
+				tool_call_count INTEGER NOT NULL,
+				tool_error_count INTEGER NOT NULL,
+				skill_activation_count INTEGER NOT NULL,
+				provider_error_count INTEGER NOT NULL,
+				recovered_error_count INTEGER NOT NULL
+			)`,
+			`CREATE TABLE model_generations (
+				id TEXT PRIMARY KEY,
+				run_id TEXT NOT NULL,
+				ordinal INTEGER NOT NULL,
+				provider TEXT,
+				model TEXT,
+				thinking_level TEXT,
+				started_at_ms INTEGER NOT NULL,
+				finished_at_ms INTEGER,
+				duration_ms INTEGER,
+				stop_reason TEXT,
+				outcome TEXT NOT NULL,
+				UNIQUE(run_id, ordinal)
+			)`,
+			`CREATE TABLE provider_responses (
+				generation_id TEXT NOT NULL,
+				ordinal INTEGER NOT NULL,
+				occurred_at_ms INTEGER NOT NULL,
+				status INTEGER NOT NULL,
+				PRIMARY KEY(generation_id, ordinal)
+			)`,
+			`CREATE TABLE provider_errors (
+				id TEXT PRIMARY KEY,
+				run_id TEXT NOT NULL,
+				generation_id TEXT,
+				occurred_at_ms INTEGER NOT NULL,
+				provider TEXT,
+				model TEXT,
+				category TEXT NOT NULL,
+				recovered INTEGER NOT NULL,
+				terminal INTEGER NOT NULL
+			)`,
+			`CREATE TABLE tool_calls (
+				id TEXT PRIMARY KEY,
+				run_id TEXT NOT NULL,
+				ordinal INTEGER NOT NULL,
+				tool_name TEXT NOT NULL,
+				provider TEXT,
+				model TEXT,
+				started_at_ms INTEGER NOT NULL,
+				finished_at_ms INTEGER,
+				duration_ms INTEGER,
+				is_error INTEGER NOT NULL,
+				completion_state TEXT NOT NULL,
+				UNIQUE(run_id, ordinal)
+			)`,
+			`CREATE TABLE skill_activations (
+				id TEXT PRIMARY KEY,
+				run_id TEXT NOT NULL,
+				occurred_at_ms INTEGER NOT NULL,
+				skill_name TEXT NOT NULL,
+				initiated_by TEXT NOT NULL,
+				provider TEXT,
+				model TEXT,
+				UNIQUE(run_id, skill_name)
+			)`,
+			"CREATE INDEX response_runs_by_time ON response_runs(started_at_ms)",
+			"CREATE INDEX generations_by_model_time ON model_generations(provider, model, started_at_ms)",
+			"CREATE INDEX tools_by_name_time ON tool_calls(tool_name, started_at_ms)",
+			"CREATE INDEX skills_by_name_time ON skill_activations(skill_name, occurred_at_ms)",
+			"CREATE INDEX skills_by_model_time ON skill_activations(provider, model, occurred_at_ms)",
+			"CREATE INDEX provider_errors_by_category_time ON provider_errors(category, occurred_at_ms)",
+			"CREATE INDEX provider_responses_by_time ON provider_responses(occurred_at_ms)",
+		],
+	},
+];
+
+export async function migrateDatabase(
+	database: Database,
+	options: {
+		migrations?: readonly SchemaMigration[];
+		retryAttempts?: number;
+		retryDelayMs?: number;
+	} = {},
+): Promise<void> {
+	const migrations = options.migrations ?? ANALYTICS_MIGRATIONS;
+	validateRegistry(migrations);
+	const attempts = options.retryAttempts ?? 8;
+	const retryDelayMs = options.retryDelayMs ?? 10;
+	await withConflictRetry(() => database.exec(CREATE_MIGRATIONS_TABLE), attempts, retryDelayMs);
+	await withConflictRetry(() => applyMigrations(database, migrations), attempts, retryDelayMs);
+}
+
+function applyMigrations(
+	database: Database,
+	migrations: readonly SchemaMigration[],
+): Promise<void> {
+	const apply = database.transactionAsync(async (transaction) => {
+		const applied = (await transaction.all(
+			"SELECT version, name, checksum FROM schema_migrations ORDER BY version",
+		)) as Array<{ version: number; name: string; checksum: string }>;
+		const supportedVersion = migrations.at(-1)?.version ?? 0;
+		const databaseVersion = applied.at(-1)?.version ?? 0;
+		if (databaseVersion > supportedVersion) {
+			throw new NewerSchemaError(databaseVersion, supportedVersion);
+		}
+		for (const [index, row] of applied.entries()) {
+			const migration = migrations[index];
+			if (!migration || row.version !== migration.version) {
+				throw new Error("Analytics migration history is not contiguous.");
+			}
+			if (row.name !== migration.name || row.checksum !== migrationChecksum(migration)) {
+				throw new ChecksumMismatchError(row.version);
+			}
+		}
+		for (const migration of migrations.slice(applied.length)) {
+			await applyOne(transaction, migration);
+		}
+	});
+	return apply.exclusive();
+}
+
+async function applyOne(transaction: Transaction, migration: SchemaMigration): Promise<void> {
+	try {
+		for (const statement of migration.statements) await transaction.exec(statement);
+		await transaction.run(
+			"INSERT INTO schema_migrations(version, name, checksum, applied_at_ms) VALUES (?, ?, ?, ?)",
+			migration.version,
+			migration.name,
+			migrationChecksum(migration),
+			Date.now(),
+		);
+	} catch (error) {
+		throw new MigrationFailedError(migration, error);
+	}
+}
+
+export function migrationChecksum(migration: SchemaMigration): string {
+	return createHash("sha256")
+		.update(
+			JSON.stringify({
+				version: migration.version,
+				name: migration.name,
+				statements: migration.statements,
+			}),
+		)
+		.digest("hex");
+}
+
+function validateRegistry(migrations: readonly SchemaMigration[]): void {
+	for (const [index, migration] of migrations.entries()) {
+		const expected = index + 1;
+		if (migration.version !== expected) {
+			throw new Error(
+				`Analytics migration versions must be contiguous; expected v${expected}, received v${migration.version}.`,
+			);
+		}
+		if (!migration.name.trim()) throw new Error(`Analytics migration v${expected} has no name.`);
+		if (migration.statements.length === 0) {
+			throw new Error(`Analytics migration v${expected} has no statements.`);
+		}
+	}
+}
+
+async function withConflictRetry<T>(
+	operation: () => Promise<T>,
+	attempts: number,
+	delayMs: number,
+): Promise<T> {
+	let lastError: unknown;
+	for (let attempt = 0; attempt < Math.max(1, attempts); attempt += 1) {
+		try {
+			return await operation();
+		} catch (error) {
+			lastError = error;
+			if (!isTransactionConflict(error) || attempt + 1 >= attempts) throw error;
+			await delay(delayMs * (attempt + 1));
+		}
+	}
+	throw lastError;
+}
+
+function isTransactionConflict(error: unknown): boolean {
+	const message =
+		error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+	if (
+		message.includes("statement was interrupted") ||
+		message.includes("database is locked") ||
+		message.includes("database is busy")
+	) {
+		return true;
+	}
+	return error instanceof Error && error.cause !== undefined
+		? isTransactionConflict(error.cause)
+		: false;
+}
+
+function delay(milliseconds: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, Math.max(0, milliseconds)));
+}