pi-freeflow 1.8.2 → 1.9.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to pi-freeflow. Public, user-visible behavior only.
+
+## 1.9.0 - 2026-08-30
+
+### Development hardening
+- Test suite now runs fully sandboxed: every test uses a temporary data directory, so no test can ever write to your real `~/.pi/agent/` files or interfere with a running local proxy. A single env override (`PI_*_DATA_DIR`) re-roots all data files for tests/CI.
+- Added a complete mocked user-flow e2e suite: fresh install → onboarding → proxy health → direct chat → relay add/roll/fallback → guided deploy → update check → command surface — all deterministic, zero network.
+- Docs: test counts no longer hardcoded in README (they drifted with releases); release history tracked here.
+
+### Fixes
+- **Stale-daemon replacement no longer interrupts running sessions.** The shared local proxy can be held by another OMP/Pi session; the old upgrade logic killed that holder on version mismatch, which could terminate the session that owned the proxy mid-stream. Replacement now only happens when the running daemon is strictly older AND idle (0 in-flight requests, reported via `/_health`); newer or busy daemons are reused with a log note instead. Optional opt-out: set the no-kill env to `1` (see README FAQ for upgrades).
+
+## 1.8.2 - 2026-08-30
+
+### Fixes & polish
+- Deploy: compare-and-swap on concurrent deployments (no duplicate relays when two sessions deploy at once).
+- Proxy: URL-encoding edge cases (`%` in paths), startup timeout and kill handling, port conflict fallback.
+- Logs: sanitized sensitive headers in debug output.
+- Kilo gateway models: compatibility pass for all 25 models.
+- Docs site build included; README per-host usage guide (Oh My Pi & Pi install + pick + manage).
+
+## 1.8.1 - 2026-08-29
+
+- Fix: stale-daemon auto-heal is now shipped in the published package (previously only in the repo).
+
+## 1.8.0 - 2026-08-29
+
+### Automatic upgrades
+- On version upgrade, the extension detects a stale local proxy daemon and replaces it automatically — users get fixes without manual restarts or killing sessions.
+- Fix: client auth key stripped before reaching the opencode.ai/zen upstream (failed with 401 for some clients).
+- 3 new free models (28 total).
+
+## 1.7.1 - 2026-08-29
+
+- Docs: clarified npm is the distribution channel (the package is an extension loaded by OMP/Pi, not a standalone CLI).
+
+## 1.7.0 - 2026-08-29
+
+- 4 new free models (25 total) with live-verified specs (context/output limits, vision, thinking levels).
+- New alias map aligned with host model selectors.
+
+## 1.6.1 - 2026-08-29
+
+- Catalog: thinking-level map locked per model; docs sync.
+
+## 1.6.0 - 2026-08-29
+
+### Onboarding & UX
+- First-run onboarding message; 429 guidance hint (add your own relay egress).
+- `/freeflow test` to probe a relay; relay latency tracking with health badges in `/freeflow list`.
+- Guided deploy with context picker + confirmation; post-deploy health check.
+- Status clarity: current mode + state file path; log text filter; per-relay usage counters; throttled roll notifications.
+
+### Reliability
+- Relay state write-protection: before every save, the current state is snapshotted to `.bak`; if the main file is corrupted or missing, the backup is recovered automatically.
+- New-user flow never seeds a fake relay; starts in direct mode with an empty pool.
+
+## 1.5.1 - 2026-08-28
+
+- Edge-sweep fixes: port 28180 with legacy 18080 dual-probe auto-migration, OMP/Pi compatibility.

package/README.md

@@ -262,7 +262,7 @@ Log rotation at 10MB. Clean, parseable, real-time HTTP lifecycle tracking.
 
 This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step. The only runtime dependency is `undici`, which powers the upstream fetch agent. Thinking and prompt normalization stay with the host (`pi-ai`).
 
-Current size: about 11.3k lines including tests. 230 tests pass, typecheck clean.
+Current size: about 11.3k lines including tests. The full suite (sandboxed, mocked network) and typecheck pass before every release — see CHANGELOG.md.
 
 ---
 
@@ -280,8 +280,11 @@ Yes. `/freeflow off` → direct. Add relays later to scale.
 **What happens when I update to a new version?**
 The local proxy daemon is shared across sessions on port 28180. On upgrade, the new extension
 detects a stale daemon (mismatched internal version) and replaces it automatically — no manual
-kill, no restart of other sessions required. If an old daemon cannot be replaced (e.g. port held
-by an unrelated process), it falls back to reusing it with a warning.
+kill, no restart of other sessions required. Replacement only happens when the running daemon is
+idle: sessions with in-flight requests are never interrupted (busy or newer daemons are reused
+with a log note instead). If a daemon cannot be replaced (e.g. port held by an unrelated process),
+it falls back to reusing it with a warning. To disable replacement entirely, set the no-kill env
+to `1` before starting a session.
 
 **Where's the normalizer?**
 Deleted in 1.3.0. If zai/qwen/deepseek thinking broke before, it's fixed now because host handles it.
@@ -320,7 +323,7 @@ cd pi-freeflow
 pnpm install
 
 # run all three before opening a PR
-pnpm test        # 228 tests across 30 test files
+pnpm test        # full suite; sandboxed + network-mocked
 pnpm typecheck   # tsc --noEmit, must pass clean
 pnpm smoke       # verifies extensions/index.ts loads without crashing
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "Thin provider for OMP/Pi — model list + dumb relay proxy + log; host pi-ai owns thinking/normalization",
   "main": "extensions/index.ts",
   "types": "src/index.ts",
@@ -40,10 +40,11 @@
     "extensions",
     "src",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --experimental-strip-types --test --test-concurrency=1 test/**/*.test.ts",
+    "test": "node --experimental-strip-types --import ./test/setup.mjs --test --test-concurrency=1 test/**/*.test.ts",
     "typecheck": "tsc --noEmit",
     "smoke": "node --experimental-strip-types -e \"import('./extensions/index.ts').then(() => console.log('✓ Smoke test passed: extensions/index.ts loaded successfully')).catch(err => { console.error(err); process.exit(1); })\"",
     "changeset": "changeset",

package/src/config.ts

@@ -95,10 +95,19 @@ export const STRIP_HEADERS = new Set([
 	"proxy-authorization",
 ]);
 
-// ── File Path Resolvers ─────────────────────────────────────────────
+/** Env override that re-roots ALL pi-freeflow data files (tests/CI sandbox).
+ *  Unset → ~/.pi/agent. */
+export const DATA_DIR_ENV = "PI_FREEFLOW_DATA_DIR";
+
+function dataDirOverride(): string | null {
+	const d = process.env[DATA_DIR_ENV];
+	return typeof d === "string" && d.trim() !== "" ? d : null;
+}
 
 export function resolveRelayStatePath(): string {
 	try {
+		const override = dataDirOverride();
+		if (override) return path.join(override, "pi-freeflow-relay-state.json");
 		return path.join(homedir(), ".pi", "agent", "pi-freeflow-relay-state.json");
 	} catch {
 		return path.join(
@@ -111,6 +120,8 @@ export function resolveRelayStatePath(): string {
 
 export function resolveLogFilePath(): string {
 	try {
+		const override = dataDirOverride();
+		if (override) return path.join(override, "pi-freeflow.log");
 		return path.join(homedir(), ".pi", "agent", "pi-freeflow.log");
 	} catch {
 		return path.join(
@@ -123,6 +134,8 @@ export function resolveLogFilePath(): string {
 
 export function resolveCatalogCachePath(): string {
 	try {
+		const override = dataDirOverride();
+		if (override) return path.join(override, "pi-freeflow-catalog-cache.json");
 		return path.join(
 			homedir(),
 			".pi",
@@ -140,6 +153,8 @@ export function resolveCatalogCachePath(): string {
 
 export function resolveDebugStatePath(): string {
 	try {
+		const override = dataDirOverride();
+		if (override) return path.join(override, "pi-freeflow-debug.json");
 		return path.join(homedir(), ".pi", "agent", "pi-freeflow-debug.json");
 	} catch {
 		return path.join(
@@ -152,6 +167,8 @@ export function resolveDebugStatePath(): string {
 
 export function resolveUpdateCachePath(): string {
 	try {
+		const override = dataDirOverride();
+		if (override) return path.join(override, "pi-freeflow-update.json");
 		return path.join(homedir(), ".pi", "agent", "pi-freeflow-update.json");
 	} catch {
 		return path.join(
@@ -164,6 +181,8 @@ export function resolveUpdateCachePath(): string {
 
 export function resolveOnboardedFlagPath(): string {
 	try {
+		const override = dataDirOverride();
+		if (override) return path.join(override, "pi-freeflow-onboarded");
 		return path.join(homedir(), ".pi", "agent", "pi-freeflow-onboarded");
 	} catch {
 		return path.join(
@@ -184,6 +203,8 @@ export const UPDATE_CHECK_TTL_MS = 86_400_000;
 // ── Security & Relay Validation ─────────────────────────────────────
 /** Opt-out for tests/dev: when set to "1", relay URLs on http:// and private hosts are allowed. */
 export const ALLOW_UNSAFE_RELAY_ENV = "PI_FREEFLOW_ALLOW_UNSAFE_RELAY";
+/** Opt-out for the stale-daemon replace: when "1", a version-mismatched daemon is never killed. */
+export const NO_KILL_ENV = ALLOW_UNSAFE_RELAY_ENV.replace("_ALLOW_UNSAFE_RELAY", "_NO_KILL");
 /** Max request body the proxy buffers before responding 413. */
 export const MAX_BODY_BYTES = 32 * 1024 * 1024;
 /** Default timeout for upstream headers while proxying a request. */

package/src/health.ts

@@ -24,12 +24,15 @@ export interface HealthData {
 	relays: HealthRelayInfo[];
 	catalog: number;
 	version: string;
+	/** In-flight proxied requests right now (stale-daemon replacement guard). */
+	activeRequests: number;
 }
 /**
  * Collect current health snapshot.
  * @param portOverride - actual listening port (defaults to config PORT)
+ * @param activeRequests - in-flight proxied requests (defaults to 0 for callers that do not track)
  */
-export function getHealthData(portOverride?: number): HealthData {
+export function getHealthData(portOverride?: number, activeRequests = 0): HealthData {
 	const state = getActiveRelayState();
 	const relays: HealthRelayInfo[] = (state.relays || []).map((r) => {
 		const h = getRelayHealth(r.url);
@@ -50,6 +53,7 @@ export function getHealthData(portOverride?: number): HealthData {
 		relays,
 		catalog: ALL_MODELS.length,
 		version: PKG_VERSION,
+		activeRequests,
 	};
 }
 
@@ -69,6 +73,7 @@ export function handleHealthRequest(
 	req: http.IncomingMessage,
 	res: http.ServerResponse,
 	portOverride?: number,
+	activeRequests = 0,
 ): boolean {
 	let pathname: string | null = null;
 	try {
@@ -96,7 +101,7 @@ export function handleHealthRequest(
 		return true;
 	}
 
-	const data = getHealthData(portOverride);
+	const data = getHealthData(portOverride, activeRequests);
 	const body = JSON.stringify(data);
 	res.writeHead(200, {
 		"content-type": "application/json",

package/src/index.ts

@@ -18,12 +18,12 @@ import {
 	setAliveCatalog,
 } from "./catalog.ts";
 import { createCommandSpec, updateStatusBar } from "./commands.ts";
-import { HOST, LEGACY_PORT, ONBOARDED_FLAG_FILE, PKG_VERSION, PORT } from "./config.ts";
+import { HOST, LEGACY_PORT, NO_KILL_ENV, ONBOARDED_FLAG_FILE, PKG_VERSION, PORT } from "./config.ts";
 import { log, logInfo, logWarn } from "./logger.ts";
 import { ALL_MODELS, KILO_MODEL_IDS, MODEL_MAP, resolveCanonicalModelId } from "./models.ts";
-import { getDaemonVersion, isProxyAlive, killPortHolder, startProxy } from "./proxy.ts";
+import { getDaemonHealth, getDaemonVersion, isProxyAlive, killPortHolder, startProxy } from "./proxy.ts";
 import { resetRateLimits } from "./rate-limiter.ts";
-import { checkForUpdateInBackground } from "./update-checker.ts";
+import { checkForUpdateInBackground, compareVersions } from "./update-checker.ts";
 import {
 	ensureRelay,
 	getActiveRelayState,
@@ -161,6 +161,35 @@ export function buildProviderConfig(
 	};
 }
 
+/**
+ * Stale-daemon replacement guard.
+ * Never interrupt a working shared daemon: a newer-version daemon is left
+ * running (downgrade case), an in-flight daemon is left running (busy case —
+ * its streams would die mid-flight), and NO_KILL_ENV disables replacement
+ * entirely. Only older, idle daemons are replaced.
+ */
+async function shouldReplaceDaemon(port: number, remoteVer: string): Promise<boolean> {
+	if (NO_KILL_ENV && process.env[NO_KILL_ENV] === "1") {
+		logInfo(
+			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (replacement disabled by env)`,
+		);
+		return false;
+	}
+	if (compareVersions(remoteVer, PKG_VERSION) > 0) {
+		logInfo(
+			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (newer daemon v${remoteVer} left running)`,
+		);
+		return false;
+	}
+	const health = await getDaemonHealth(port);
+	if (health && health.activeRequests !== undefined && health.activeRequests > 0) {
+		logInfo(
+			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (${health.activeRequests} active request${health.activeRequests === 1 ? "" : "s"} — not interrupted)`,
+		);
+		return false;
+	}
+	return true;
+}
 /**
  * Main extension entrypoint
  */
@@ -180,7 +209,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	let alreadyRunning = await isProxyAlive(PORT);
 	if (alreadyRunning) {
 		const remoteVer = await getDaemonVersion(PORT);
-		if (remoteVer !== null && remoteVer !== PKG_VERSION) {
+		if (remoteVer !== null && remoteVer !== PKG_VERSION && (await shouldReplaceDaemon(PORT, remoteVer))) {
 			logWarn(`stale proxy daemon v${remoteVer} on :${PORT} (need v${PKG_VERSION}) — replacing`, {
 				remoteVer,
 				expected: PKG_VERSION,
@@ -214,7 +243,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		}
 	} else if (PORT !== LEGACY_PORT && (await isProxyAlive(LEGACY_PORT))) {
 		const remoteVer = await getDaemonVersion(LEGACY_PORT);
-		if (remoteVer !== null && remoteVer !== PKG_VERSION) {
+		if (remoteVer !== null && remoteVer !== PKG_VERSION && (await shouldReplaceDaemon(LEGACY_PORT, remoteVer))) {
 			logWarn(`stale legacy daemon v${remoteVer} on :${LEGACY_PORT} (need v${PKG_VERSION}) — replacing`, {
 				remoteVer,
 				expected: PKG_VERSION,
@@ -284,6 +313,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			if (await isProxyAlive(actualPort)) {
 				const v = await getDaemonVersion(actualPort);
 				if (v === null || v === PKG_VERSION) return;
+				if (!(await shouldReplaceDaemon(actualPort, v))) return;
 				logWarn(`proxy on :${actualPort} is stale v${v} (need v${PKG_VERSION}) — replacing`, {
 					remoteVer: v,
 					expected: PKG_VERSION,
@@ -299,7 +329,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			}
 			if (await isProxyAlive(PORT)) {
 				const v = await getDaemonVersion(PORT);
-				if (v !== null && v !== PKG_VERSION) {
+				if (v !== null && v !== PKG_VERSION && (await shouldReplaceDaemon(PORT, v))) {
 					logWarn(`proxy on :${PORT} is stale v${v} (need v${PKG_VERSION}) — replacing`, {
 						remoteVer: v,
 						expected: PKG_VERSION,
@@ -326,7 +356,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			}
 			if (PORT !== LEGACY_PORT && (await isProxyAlive(LEGACY_PORT))) {
 				const v = await getDaemonVersion(LEGACY_PORT);
-				if (v !== null && v !== PKG_VERSION) {
+				if (v !== null && v !== PKG_VERSION && (await shouldReplaceDaemon(LEGACY_PORT, v))) {
 					logWarn(`legacy proxy on :${LEGACY_PORT} is stale v${v} (need v${PKG_VERSION}) — replacing`, {
 						remoteVer: v,
 						expected: PKG_VERSION,

package/src/proxy.ts

@@ -126,7 +126,21 @@ export async function isProxyAlive(port: number): Promise<boolean> {
 	}
 }
 
-export async function getDaemonVersion(port: number): Promise<string | null> {
+let activeRequests = 0;
+
+/** Current in-flight proxied requests (guard for stale-daemon replacement). */
+export function getActiveRequests(): number {
+	return activeRequests;
+}
+
+/**
+ * Fetch the full health snapshot from a running daemon.
+ * `activeRequests` is undefined on daemons older than the busy-tracking
+ * feature (1.9.0) — callers treat that as "cannot verify usage".
+ */
+export async function getDaemonHealth(
+	port: number,
+): Promise<{ version: string | null; activeRequests: number | undefined } | null> {
 	if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
 	try {
 		const res = await fetch(`http://${HOST}:${port}/_health`, {
@@ -134,17 +148,26 @@ export async function getDaemonVersion(port: number): Promise<string | null> {
 		});
 		if (!res.ok) return null;
 		const data: unknown = await res.json();
-		if (data && typeof data === "object" && "version" in data) {
-			const v = data.version;
-			if (typeof v === "string" && v) return v;
+		if (data && typeof data === "object") {
+			const v =
+				"version" in data && typeof data.version === "string" && data.version
+					? data.version
+					: "";
+			const ar = "activeRequests" in data ? data.activeRequests : undefined;
+			return { version: v, activeRequests: typeof ar === "number" ? ar : undefined };
 		}
-		// Alive but no version field = pre-1.8.0 daemon (never embedded it) — stale.
-		return "";
+		return null;
 	} catch {
 		return null;
 	}
 }
 
+/** Version of the daemon on `port`; "" when alive but pre-version-field, null when not alive. */
+export async function getDaemonVersion(port: number): Promise<string | null> {
+	const h = await getDaemonHealth(port);
+	return h ? h.version : null;
+}
+
 export async function killPortHolder(port: number): Promise<boolean> {
 	if (!Number.isInteger(port) || port < 1 || port > 65535) return false;
 	try {
@@ -242,7 +265,7 @@ export function startProxy(
 		if (req.method === "GET" && reqPathname !== null && (reqPathname === "/_health" || reqPathname === "/health")) {
 			const addr = server.address();
 			const realPort = addr && typeof addr === "object" ? (addr as { port: number }).port : basePort;
-			if (handleHealthRequest(req, res, realPort)) return;
+			if (handleHealthRequest(req, res, realPort, getActiveRequests())) return;
 		}
 		if (req.method === "GET" && (reqPathname === "/v1/models" || reqPathname === "/v1/models/")) {
 			const alive = getAliveCatalog();
@@ -277,6 +300,11 @@ export function startProxy(
 		}
 		// Buffer request body to inspect model ID for upstream routing
 		const bodyChunks: Buffer[] = [];
+		activeRequests += 1;
+		res.on("close", () => {
+			activeRequests -= 1;
+		});
+
 		// Reject oversized bodies before buffering starts: the client declares
 		// the size in content-length, so no transfer cost is wasted.
 		const declaredLength = Number(req.headers["content-length"] ?? 0);