pi-free 2.0.15 → 2.1.0

package/lib/paths.ts

@@ -0,0 +1,90 @@
+/**
+ * Centralized path resolution for ~/.pi/ data files.
+ *
+ * These helpers constrain file paths to the user's pi data directory
+ * to prevent arbitrary-file-write vulnerabilities from attacker-controlled
+ * environment variables. All env-var file overrides must resolve to a
+ * path inside ~/.pi/ or be rejected.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir as _nodeHomedir } from "node:os";
+import { basename, join, resolve, sep } from "node:path";
+
+/**
+ * The user's home directory.
+ *
+ * On POSIX, `node:os.homedir()` already respects the `HOME` env var.
+ * On Windows, it uses `USERPROFILE` and ignores `HOME`. We prefer `HOME`
+ * (set by tests and various cross-platform tooling) and fall back to
+ * `USERPROFILE` and then to `node:os.homedir()`.
+ */
+function resolveHomeDir(): string {
+	if (process.env.HOME) return process.env.HOME;
+	if (process.env.USERPROFILE) return process.env.USERPROFILE;
+	return _nodeHomedir();
+}
+
+/** The user's pi data directory (~/.pi). */
+export const PI_DATA_DIR = join(resolveHomeDir(), ".pi");
+
+/** Maximum basename length for override env vars. */
+const MAX_BASENAME_LENGTH = 128;
+
+/** Characters that are not allowed in a basename. */
+const FORBIDDEN_CHARS_RE = /[/\\\0]/;
+
+/**
+ * Ensure a directory exists, creating it (and parents) if missing.
+ * Idempotent — safe to call repeatedly.
+ */
+export function ensureDir(dir: string): void {
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+}
+
+/**
+ * Resolve a file path from an env-var override, constrained to ~/.pi/.
+ *
+ * The env var may override only the *filename* (not the directory).
+ * If the env var is unset or empty, returns the default path.
+ * If the env var contains a path separator or null byte, the override
+ * is rejected and the default path is used.
+ *
+ * @param envValue - Raw env var value (may be undefined/empty)
+ * @param defaultFilename - Default filename inside ~/.pi/
+ * @returns A path string that is guaranteed to be inside ~/.pi/
+ */
+export function resolveSafeDataFile(
+	envValue: string | undefined,
+	defaultFilename: string,
+): string {
+	if (!envValue) {
+		return join(PI_DATA_DIR, defaultFilename);
+	}
+
+	// Reject any path separator — only allow bare filenames
+	if (FORBIDDEN_CHARS_RE.test(envValue)) {
+		return join(PI_DATA_DIR, defaultFilename);
+	}
+
+	// Reject empty after trim, overly long, or suspicious filenames
+	const trimmed = envValue.trim();
+	if (
+		!trimmed ||
+		trimmed === "." ||
+		trimmed === ".." ||
+		trimmed.length > MAX_BASENAME_LENGTH
+	) {
+		return join(PI_DATA_DIR, defaultFilename);
+	}
+
+	// Final safety check: resolve and verify the result is still inside PI_DATA_DIR
+	const candidate = resolve(join(PI_DATA_DIR, basename(trimmed)));
+	if (candidate !== PI_DATA_DIR && !candidate.startsWith(PI_DATA_DIR + sep)) {
+		return join(PI_DATA_DIR, defaultFilename);
+	}
+
+	return candidate;
+}

package/lib/probe-cache.ts

@@ -5,10 +5,9 @@
  * background cleanup can avoid spending quota on the same checks every session.
  */
 
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { createJSONStore } from "./json-persistence.ts";
 import { createLogger } from "./logger.ts";
+import { PI_DATA_DIR } from "./paths.ts";
 
 const _logger = createLogger("probe-cache");
 
@@ -35,7 +34,7 @@ interface ProbeCacheData {
 	providers: Record<string, ProviderProbeCache>;
 }
 
-const CACHE_FILE = join(homedir(), ".pi", "probe-cache.json");
+const CACHE_FILE = `${PI_DATA_DIR}/probe-cache.json`;
 const _cache = createJSONStore<ProbeCacheData>(CACHE_FILE, { providers: {} });
 
 export function getModelsDueForProbe(
@@ -61,26 +60,27 @@ export function getModelsDueForProbe(
 	});
 }
 
-export function recordModelProbeResults(
+export async function recordModelProbeResults(
 	providerId: string,
 	results: ModelProbeResult[],
-): void {
+): Promise<void> {
 	if (results.length === 0) return;
 
-	const data = _cache.load();
-	const provider = (data.providers[providerId] ??= {
-		provider: providerId,
-		models: {},
+	await _cache.update((data) => {
+		const provider = (data.providers[providerId] ??= {
+			provider: providerId,
+			models: {},
+		});
+		const lastProbedAt = new Date().toISOString();
+
+		for (const result of results) {
+			provider.models[result.modelId] = {
+				lastProbedAt,
+				status: result.status,
+			};
+		}
+
+		return data;
 	});
-	const lastProbedAt = new Date().toISOString();
-
-	for (const result of results) {
-		provider.models[result.modelId] = {
-			lastProbedAt,
-			status: result.status,
-		};
-	}
-
-	_cache.save(data);
 	_logger.debug(`Recorded ${results.length} probe results for ${providerId}`);
 }

package/lib/provider-cache.ts

@@ -9,10 +9,9 @@
  * 3. If API fails: use cached models as fallback
  */
 
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { createJSONStore } from "./json-persistence.ts";
 import { createLogger } from "./logger.ts";
+import { resolveSafeDataFile } from "./paths.ts";
 import type { ProviderModelConfig } from "./types.ts";
 
 const _logger = createLogger("provider-cache");
@@ -38,10 +37,31 @@ interface CacheData {
 // Cache Store
 // =============================================================================
 
-const CACHE_FILE = join(homedir(), ".pi", "provider-cache.json");
+const CACHE_FILE = resolveSafeDataFile(
+	process.env.PI_FREE_PROVIDER_CACHE,
+	"provider-cache.json",
+);
 
 const _cache = createJSONStore<CacheData>(CACHE_FILE, { providers: {} });
 
+export const DEFAULT_PROVIDER_CACHE_TTL_MS = 60 * 60 * 1000;
+
+function getProviderCacheEntry(
+	providerId: string,
+): CachedProviderModels | undefined {
+	try {
+		const data = _cache.load();
+		const cached = data?.providers?.[providerId];
+		if (!cached || !Array.isArray(cached.models)) return undefined;
+		return cached;
+	} catch (error) {
+		_logger.warn(`Failed to load provider cache for ${providerId}`, {
+			error: error instanceof Error ? error.message : String(error),
+		});
+		return undefined;
+	}
+}
+
 /**
  * Load cached models for a provider.
  * Returns undefined if no cache exists.
@@ -49,8 +69,7 @@ const _cache = createJSONStore<CacheData>(CACHE_FILE, { providers: {} });
 export function loadProviderCache(
 	providerId: string,
 ): ProviderModelConfig[] | undefined {
-	const data = _cache.load();
-	const cached = data.providers[providerId];
+	const cached = getProviderCacheEntry(providerId);
 
 	if (!cached) {
 		return undefined;
@@ -61,25 +80,50 @@ export function loadProviderCache(
 		fetchedAt: cached.fetchedAt,
 	});
 
-	return cached.models;
+	return structuredClone(cached.models);
+}
+
+/**
+ * Return the age of a provider cache entry in milliseconds.
+ * Returns undefined if no cache exists or the timestamp is invalid.
+ */
+function getProviderCacheAgeMs(providerId: string): number | undefined {
+	const cached = getProviderCacheEntry(providerId);
+	if (!cached) return undefined;
+
+	const fetchedAt = new Date(cached.fetchedAt).getTime();
+	if (Number.isNaN(fetchedAt)) return undefined;
+	const age = Date.now() - fetchedAt;
+	if (age < -5000) return undefined;
+	return Math.max(0, age);
+}
+
+/**
+ * Check whether a provider cache entry is fresh enough to skip network refresh.
+ */
+export function isProviderCacheFresh(
+	providerId: string,
+	maxAgeMs: number,
+): boolean {
+	const age = getProviderCacheAgeMs(providerId);
+	return age !== undefined && age <= maxAgeMs;
 }
 
 /**
  * Save models to cache for a provider.
  */
-export function saveProviderCache(
+export async function saveProviderCache(
 	providerId: string,
 	models: ProviderModelConfig[],
-): void {
-	const data = _cache.load();
-
-	data.providers[providerId] = {
-		provider: providerId,
-		models,
-		fetchedAt: new Date().toISOString(),
-	};
-
-	_cache.save(data);
+): Promise<void> {
+	await _cache.update((data) => {
+		data.providers[providerId] = {
+			provider: providerId,
+			models: structuredClone(models),
+			fetchedAt: new Date().toISOString(),
+		};
+		return data;
+	});
 
 	_logger.debug(`Saved ${models.length} models to cache for ${providerId}`);
 }
@@ -87,20 +131,22 @@ export function saveProviderCache(
 /**
  * Clear cached models for a provider.
  */
-export function clearProviderCache(providerId: string): void {
-	const data = _cache.load();
-
-	if (data.providers[providerId]) {
-		delete data.providers[providerId];
-		_cache.save(data);
-		_logger.debug(`Cleared cache for ${providerId}`);
-	}
+export async function clearProviderCache(providerId: string): Promise<void> {
+	await _cache.update((data) => {
+		if (data.providers[providerId]) {
+			delete data.providers[providerId];
+			_logger.debug(`Cleared cache for ${providerId}`);
+		}
+		return data;
+	});
 }
 
 /**
  * Clear all provider caches.
  */
-export function clearAllProviderCaches(): void {
-	_cache.save({ providers: {} });
-	_logger.debug("Cleared all provider caches");
+export async function clearAllProviderCaches(): Promise<void> {
+	await _cache.update(() => {
+		_logger.debug("Cleared all provider caches");
+		return { providers: {} };
+	});
 }

package/lib/provider-compat.ts

@@ -1,9 +1,7 @@
 import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { ModelIdentity } from "./types.ts";
 
-export interface ProviderModelIdentity {
-	id: string;
-	name?: string;
-}
+export type ProviderModelIdentity = ModelIdentity;
 
 export const DEEPSEEK_PROXY_COMPAT: NonNullable<ProviderModelConfig["compat"]> =
 	{
@@ -14,16 +12,39 @@ export const DEEPSEEK_PROXY_COMPAT: NonNullable<ProviderModelConfig["compat"]> =
 		thinkingFormat: "deepseek",
 	};
 
+/** Kimi K2.6 on OpenRouter needs reasoning_content on assistant messages
+ *  (OpenRouter issue #5309) but doesn't use the DeepSeek thinking format. */
+const KIMI_PROXY_COMPAT: NonNullable<ProviderModelConfig["compat"]> = {
+	supportsStore: false,
+	supportsDeveloperRole: false,
+	supportsReasoningEffort: true,
+	requiresReasoningContentOnAssistantMessages: true,
+};
+
+function getModelHaystack(model: ProviderModelIdentity): string {
+	return [model.id, model.name, model.family, model.provider]
+		.filter(Boolean)
+		.join(" ")
+		.toLowerCase();
+}
+
 export function isDeepSeekModel(model: ProviderModelIdentity): boolean {
-	const haystack = `${model.id} ${model.name ?? ""}`.toLowerCase();
-	return haystack.includes("deepseek");
+	return getModelHaystack(model).includes("deepseek");
+}
+
+/** MiMo/Xiaomi reasoning models expose OpenAI-compatible reasoning controls
+ * through gateways such as Cline/OpenRouter, but they are not DeepSeek-format. */
+function isMimoModel(model: ProviderModelIdentity): boolean {
+	const haystack = getModelHaystack(model);
+	return haystack.includes("mimo") || haystack.includes("xiaomi");
 }
 
 export function isLikelyReasoningModel(model: ProviderModelIdentity): boolean {
-	const haystack = `${model.id} ${model.name ?? ""}`.toLowerCase();
+	const haystack = getModelHaystack(model);
 	return (
 		isDeepSeekModel(model) ||
 		haystack.includes("minimax") ||
+		isMimoModel(model) ||
 		haystack.includes("kimi") ||
 		haystack.includes("qwen3.7") ||
 		haystack.includes("qwen3-7") ||
@@ -35,6 +56,28 @@ export function isLikelyReasoningModel(model: ProviderModelIdentity): boolean {
 	);
 }
 
+/**
+ * Models that the gateway/proxy exposes as a DeepSeek-style reasoning
+ * format — use the canonical DEEPSEEK_PROXY_COMPAT (full feature set +
+ * thinkingFormat).
+ */
+function isDeepSeekStyleModel(model: ProviderModelIdentity): boolean {
+	const id = model.id.toLowerCase();
+	return (
+		isDeepSeekModel(model) ||
+		id.includes("qwen3.7") ||
+		id.includes("qwen3-7")
+	);
+}
+
+/**
+ * Kimi variants need the same reasoning_content replay as DeepSeek-style
+ * models but without the thinkingFormat override.
+ */
+function isKimiModel(model: ProviderModelIdentity): boolean {
+	return model.id.toLowerCase().includes("kimi");
+}
+
 /**
  * For gateway/proxy providers that mask the upstream DeepSeek base URL,
  * add explicit compat so pi-ai preserves and replays reasoning_content.
@@ -42,38 +85,11 @@ export function isLikelyReasoningModel(model: ProviderModelIdentity): boolean {
 export function getProxyModelCompat(
 	model: ProviderModelIdentity,
 ): ProviderModelConfig["compat"] | undefined {
-	if (isDeepSeekModel(model)) {
-		return DEEPSEEK_PROXY_COMPAT;
-	}
-
-	// MiniMax on OpenRouter/Cline uses reasoning_content (DeepSeek format)
-	if (model.id.toLowerCase().includes("minimax")) {
-		return {
-			supportsStore: false,
-			supportsDeveloperRole: false,
-			supportsReasoningEffort: true,
-			requiresReasoningContentOnAssistantMessages: true,
-			thinkingFormat: "deepseek",
-		};
-	}
-
-	// Qwen 3.7+ on OpenRouter/Cline uses reasoning_content (DeepSeek format)
-	if (
-		model.id.toLowerCase().includes("qwen3.7") ||
-		model.id.toLowerCase().includes("qwen3-7")
-	) {
+	if (isDeepSeekStyleModel(model)) {
 		return DEEPSEEK_PROXY_COMPAT;
 	}
-
-	// Kimi K2.6 needs reasoning_content on assistant messages (OpenRouter issue #5309)
-	if (model.id.toLowerCase().includes("kimi")) {
-		return {
-			supportsStore: false,
-			supportsDeveloperRole: false,
-			supportsReasoningEffort: true,
-			requiresReasoningContentOnAssistantMessages: true,
-		};
+	if (isKimiModel(model) || isMimoModel(model)) {
+		return KIMI_PROXY_COMPAT;
 	}
-
 	return undefined;
 }

package/lib/provider-probe.ts

@@ -0,0 +1,188 @@
+/**
+ * Generic Provider Probe Helper
+ *
+ * Provides a reusable auto-probe factory for providers whose free model
+ * availability may change over time (expired promotions, rate limits,
+ * server spin-down).
+ *
+ * Usage:
+ *   const probe = createProviderProbe({
+ *     providerId: "deepinfra",
+ *     probeModel: async (apiKey, modelId) => { ... return "ok"|"broken"|"unknown"; },
+ *   });
+ *   const broken = await probe.run(apiKey, models);
+ *   // broken is a string[] of model IDs that returned "broken"
+ *
+ * The helper handles:
+ *   - Batching probe requests (default batchSize=5)
+ *   - Probe-cache integration (skip recently-probed models, persist results)
+ *   - Auto-hiding broken models in config (provider-scoped)
+ *   - Re-registration after hiding
+ */
+
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { updateConfig } from "../config.ts";
+import { createLogger } from "./logger.ts";
+import {
+	getModelsDueForProbe,
+	recordModelProbeResults,
+	type ModelProbeResult,
+} from "./probe-cache.ts";
+
+const _logger = createLogger("provider-probe");
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type ProbeModelFn = (
+	apiKey: string,
+	modelId: string,
+) => Promise<"ok" | "broken" | "unknown">;
+
+export interface ProviderProbeOptions {
+	/** Provider identifier (used for probe-cache key and config hiding). */
+	providerId: string;
+	/** Provider-specific probe function. */
+	probeModel: ProbeModelFn;
+	/** Max concurrent probes per batch (default: 5). */
+	batchSize?: number;
+	/**
+	 * Whether broken models should be auto-hidden in config.
+	 * Default: true for most providers; false for transient promotions.
+	 */
+	autoHide?: boolean;
+}
+
+export interface ProviderProbe {
+	/**
+	 * Run the probe against the given models.
+	 *
+	 * @param apiKey - The provider's API key
+	 * @param models - Models to test (typically free models)
+	 * @param options.useCache - When true, skip models with fresh probe-cache entries
+	 * @param options.onBroken - Optional callback fired per broken model (e.g., for notifications)
+	 * @returns Array of broken model IDs
+	 */
+	run: (
+		apiKey: string,
+		models: ProviderModelConfig[],
+		options?: {
+			useCache?: boolean;
+			onBroken?: (brokenIds: string[]) => void;
+		},
+	) => Promise<string[]>;
+
+	/**
+	 * Convenience: wire lazy async auto-probe into session_start.
+	 * Returns a fire-and-forget session_start handler that schedules one probe.
+	 */
+	autoProbeHandler: (
+		apiKey: string,
+		models: ProviderModelConfig[],
+	) => () => void;
+}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+export function createProviderProbe(
+	options: ProviderProbeOptions,
+): ProviderProbe {
+	const { providerId, probeModel, batchSize = 5, autoHide = true } = options;
+
+	const run: ProviderProbe["run"] = async (
+		apiKey,
+		models,
+		opts = {},
+	): Promise<string[]> => {
+		const { useCache = false, onBroken } = opts;
+
+		// Determine which models need probing
+		const modelIdsToProbe = useCache
+			? new Set(
+					getModelsDueForProbe(
+						providerId,
+						models.map((m) => m.id),
+					),
+				)
+			: undefined;
+		const probeCandidates = modelIdsToProbe
+			? models.filter((m) => modelIdsToProbe.has(m.id))
+			: models;
+
+		if (probeCandidates.length === 0) {
+			_logger.info(`[probe] ${providerId}: probe cache is fresh`);
+			return [];
+		}
+
+		_logger.info(
+			`[probe] ${providerId}: probing ${probeCandidates.length} models (batch ${batchSize})`,
+		);
+
+		// Batch probes
+		const broken: string[] = [];
+		const cacheableResults: ModelProbeResult[] = [];
+
+		for (let i = 0; i < probeCandidates.length; i += batchSize) {
+			const batch = probeCandidates.slice(i, i + batchSize);
+			const results = await Promise.all(
+				batch.map(async (m) => {
+					const status = await probeModel(apiKey, m.id);
+					return { id: m.id, status };
+				}),
+			);
+			for (const r of results) {
+				if (r.status === "broken") broken.push(r.id);
+				if (r.status !== "unknown") {
+					cacheableResults.push({ modelId: r.id, status: r.status });
+				}
+			}
+		}
+
+		// Persist probe results to cache
+		await recordModelProbeResults(providerId, cacheableResults);
+
+		if (broken.length === 0) {
+			_logger.info(`[probe] ${providerId}: all models accessible`);
+			return [];
+		}
+
+		// Optional auto-hide — use updateConfig for atomic RMW to prevent
+		// concurrent probes from clobbering each other's hidden_models.
+		if (autoHide) {
+			await updateConfig((cfg) => {
+				const existingHidden = new Set(cfg.hidden_models ?? []);
+				for (const id of broken) existingHidden.add(`${providerId}/${id}`);
+				return { hidden_models: Array.from(existingHidden) };
+			});
+			_logger.info(
+				`[probe] ${providerId}: auto-hidden ${broken.length} broken models`,
+			);
+		}
+
+		onBroken?.(broken);
+		_logger.info(`[probe] ${providerId}: found ${broken.length} broken models`);
+		return broken;
+	};
+
+	const autoProbeHandler: ProviderProbe["autoProbeHandler"] = (
+		apiKey,
+		models,
+	) => {
+		let done = false;
+		return () => {
+			if (done) return;
+			done = true;
+			_logger.info(`[probe] Starting lazy auto-probe for ${providerId}...`);
+			run(apiKey, models, { useCache: true }).catch((err) => {
+				_logger.warn(`[probe] ${providerId}: auto-probe failed`, {
+					error: err instanceof Error ? err.message : String(err),
+				});
+			});
+		};
+	};
+
+	return { run, autoProbeHandler };
+}

package/lib/registry.ts

@@ -5,10 +5,7 @@
  * without creating a circular dependency.
  */
 
-import type {
-	ExtensionAPI,
-	ProviderModelConfig,
-} from "@earendil-works/pi-coding-agent";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import { getFreeOnly, getProviderShowPaid, saveConfig } from "../config.ts";
 import { createLogger } from "./logger.ts";
 
@@ -221,7 +218,6 @@ function applyFilterToProvider(
 }
 
 export function applyGlobalFilter(
-	_pi: ExtensionAPI,
 	freeOnly: boolean,
 	options: { force?: boolean } = {},
 ): void {

package/lib/session-start-metrics.ts

@@ -0,0 +1,46 @@
+/**
+ * Session-start timing helpers.
+ *
+ * Pi-lens logs the total cost of session_start via debug messages. Extensions
+ * like pi-free attach async handlers to session_start that can materially
+ * increase that cost (model refresh, accessibility probes, etc.). This module
+ * wraps handlers so those delays show up in the logs and can be audited.
+ */
+
+import { createLogger } from "./logger.ts";
+
+const _logger = createLogger("session-start-metrics");
+
+/**
+ * Wrap a session_start handler so its wall-clock duration is logged.
+ * The label should identify the provider/feature being timed.
+ */
+export function wrapSessionStartHandler<TArgs extends unknown[]>(
+	label: string,
+	handler: (...args: TArgs) => void | Promise<void>,
+): (...args: TArgs) => Promise<void> {
+	return async (...args) => {
+		const start = Date.now();
+		try {
+			await handler(...args);
+		} finally {
+			_logger.info(`session_start ${label}: ${Date.now() - start}ms`);
+		}
+	};
+}
+
+/**
+ * Time a synchronous or asynchronous block and log its duration.
+ * Returns the result of the block.
+ */
+export async function timeAsync<T>(
+	label: string,
+	block: () => T | Promise<T>,
+): Promise<T> {
+	const start = Date.now();
+	try {
+		return await block();
+	} finally {
+		_logger.info(`${label}: ${Date.now() - start}ms`);
+	}
+}