pi-freeflow 1.0.0

package/extensions/index.ts

@@ -0,0 +1,1529 @@
+/**
+ * bansos — pi extension (with KiloCode free support)
+ *
+ * OpenCode models + KiloCode gateway free models
+ */
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import { homedir } from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+
+// ── Configuration ──────────────────────────────────────────────────
+const UPSTREAM_OPENCODE = "https://opencode.ai/zen";
+// KiloCode gateway — OpenAI-compatible; free models are keyless (200 req/hr per IP)
+const KILO_CHAT_URL = "https://api.kilo.ai/api/gateway/chat/completions";
+const PORT = Number(process.env.BANSOS_PORT) || 18080;
+const HOST = "127.0.0.1";
+const API = `${UPSTREAM_OPENCODE}/v1`;
+const OPENCODE_USER_AGENT = "opencode/latest/1.14.50/cli";
+const OPENCODE_CLIENT = "cli";
+const OPENCODE_PROJECT = "default";
+const OPENCODE_SESSION = randomUUID();
+
+function opencodeHeaders(): Record<string, string> {
+	return {
+		"User-Agent": OPENCODE_USER_AGENT,
+		"x-opencode-client": OPENCODE_CLIENT,
+		"x-opencode-project": OPENCODE_PROJECT,
+		"x-opencode-session": OPENCODE_SESSION,
+		"x-opencode-request": randomUUID(),
+	};
+}
+
+// ── Relay egress (vercel/cloudflare worker, x-relay-target pattern) ──────────
+// Same logic as 9router ProxyFetch: when enabled, redirect upstream calls to a
+// relay URL and inject x-relay-target / x-relay-path headers. Body untouched →
+// SSE streaming passes through unchanged. Toggle live via /bansos command.
+// No built-in default relay — a published package must not bake in any one
+// user's personal relay URL. Bring your own via /bansos deploy or /bansos url.
+const DEFAULT_RELAY_URL = "";
+// State lives OUTSIDE the package dir so npm updates don't wipe it.
+// Uses ~/.pi/agent/pi-bansos-relay-state.json (stable), falls back to
+// package-root .relay-state.json for dev/local installs.
+function resolveRelayStatePath(): string {
+	try {
+		const primary = path.join(homedir(), ".pi", "agent", "pi-freeflow-relay-state.json");
+		const legacy = path.join(homedir(), ".pi", "agent", "pi-bansos-relay-state.json");
+		if (!fs.existsSync(primary) && fs.existsSync(legacy)) {
+			try { fs.copyFileSync(legacy, primary); } catch {}
+		}
+		return primary;
+	} catch {
+		return path.join(
+			path.dirname(fileURLToPath(import.meta.url)),
+			"..",
+			".relay-state.json",
+		);
+	}
+}
+function resolveLogFilePath(): string {
+	try {
+		return path.join(homedir(), ".pi", "agent", "pi-freeflow.log");
+	} catch {
+		return path.join(
+			path.dirname(fileURLToPath(import.meta.url)),
+			"..",
+			"pi-freeflow.log",
+		);
+	}
+}
+const LOG_FILE = resolveLogFilePath();
+const RELAY_STATE_FILE = resolveRelayStatePath();
+type KnownRelay = { url: string; label?: string; addedAt?: string };
+type RelayState = { enabled: boolean; url: string; relays: KnownRelay[] };
+function loadRelayState(): RelayState {
+	try {
+		const s = JSON.parse(fs.readFileSync(RELAY_STATE_FILE, "utf8"));
+		const relays: KnownRelay[] = Array.isArray(s?.relays) ? s.relays : [];
+		return {
+			enabled: Boolean(s?.enabled),
+			url: typeof s?.url === "string" ? s.url.trim() : "",
+			relays,
+		};
+	} catch {
+		return { enabled: false, url: "", relays: [] };
+	}
+}
+function saveRelayState(s: RelayState): void {
+	try {
+		fs.writeFileSync(RELAY_STATE_FILE, JSON.stringify(s));
+	} catch (e) {
+		log("warn", "could not persist relay state", { error: String(e) });
+	}
+}
+// dedupe-add a relay to the known list
+function ensureRelay(s: RelayState, url: string, label?: string): void {
+	if (!url || s.relays.some((r) => r.url === url)) return;
+	s.relays.push({ url, label, addedAt: new Date().toISOString() });
+}
+function removeRelay(s: RelayState, url: string): void {
+	s.relays = s.relays.filter((r) => r.url !== url);
+}
+function resolveRelayState(): RelayState {
+	const s = loadRelayState();
+	// migrate legacy {enabled,url}: seed the known list with default + active url
+	if (!s.relays.length) {
+		ensureRelay(s, DEFAULT_RELAY_URL, "9Router default");
+		if (s.url && s.url !== DEFAULT_RELAY_URL) ensureRelay(s, s.url, "previous");
+	}
+	if (!s.url) s.url = DEFAULT_RELAY_URL;
+	return s;
+}
+let relayState: RelayState = resolveRelayState();
+let statusUi: ExtensionUIContext | null = null;
+function shortRelayLabel(url: string): string {
+	const hit = relayState.relays.find((r) => r.url === url);
+	if (hit?.label) return hit.label;
+	try { return new URL(url).host.split(".")[0]; } catch { return url.slice(0, 18); }
+}
+function getOrderedRelayUrls(): string[] {
+	relayState = loadRelayState();
+	if (relayState.relays && relayState.relays.length > 0) {
+		const active = (relayState.url || "").trim();
+		let activeIdx = relayState.relays.findIndex((r) => r.url === active);
+		if (activeIdx < 0) activeIdx = 0;
+		const ordered: string[] = [];
+		for (let i = 0; i < relayState.relays.length; i++) {
+			const r = relayState.relays[(activeIdx + i) % relayState.relays.length];
+			if (r?.url?.trim()) ordered.push(r.url.trim());
+		}
+		return ordered.length > 0 ? ordered : [DEFAULT_RELAY_URL];
+	}
+	if (relayState.url?.trim()) return [relayState.url.trim()];
+	return [DEFAULT_RELAY_URL];
+}
+function isRetriableStatus(status: number): boolean {
+	return (
+		status === 429 ||
+		status === 502 ||
+		status === 503 ||
+		status === 504 ||
+		status === 408 ||
+		status === 402 ||
+		status === 403 ||
+		status === 500
+	);
+}
+
+// Catalog served at GET /v1/models — ONLY the alive free models we register.
+// Set after health checks. Prevents paid/other upstream models from leaking
+// through the proxy's /v1/models (opencode returns 60 models incl. 54 paid).
+type RegisteredModel = ModelDef & { source: Upstream };
+let aliveCatalog: RegisteredModel[] = [];
+
+async function relayFetch(
+	url: string,
+	opts: RequestInit = {},
+): Promise<Response> {
+	if (!relayState.enabled) {
+		return fetch(url, opts);
+	}
+
+	const candidates = getOrderedRelayUrls();
+	let lastResponse: Response | null = null;
+	let lastError: unknown = null;
+	const u = new URL(url);
+	const relayTarget = `${u.protocol}//${u.host}`;
+	const relayPath = `${u.pathname}${u.search}`;
+
+	const bodySizeKB =
+		typeof opts.body === "string"
+			? (opts.body.length / 1024).toFixed(1)
+			: Buffer.isBuffer(opts.body)
+				? (opts.body.length / 1024).toFixed(1)
+				: "0";
+
+	log("info", `request starting (${bodySizeKB}KB payload) -> ${url}`);
+
+	for (let i = 0; i < candidates.length; i++) {
+		const targetUrl = candidates[i];
+		const attemptStart = Date.now();
+		try {
+			const targetHost = new URL(targetUrl).host;
+			const headers = new Headers(opts.headers);
+			headers.set("x-relay-target", relayTarget);
+			headers.set("x-relay-path", relayPath);
+			headers.set("host", targetHost);
+
+			const signal = opts.signal || AbortSignal.timeout(300_000);
+			const res = await fetch(targetUrl, { ...opts, headers, signal });
+			const elapsed = ((Date.now() - attemptStart) / 1000).toFixed(1);
+
+			// Vercel 504 Gateway Timeout on heavy prompts (>50KB or >25s):
+			// Don't cycle through 5 more identical Vercel 25s timeouts. Fast fallback to direct!
+			if (res.status === 504) {
+				log(
+					"warn",
+					`relay ${targetUrl} hit HTTP 504 Gateway Timeout in ${elapsed}s (prompt evaluation exceeded Vercel 25s limit) — fast fallback to direct upstream`,
+					{ upstream: url, sizeKB: bodySizeKB },
+				);
+				break;
+			}
+
+			if (isRetriableStatus(res.status)) {
+				lastResponse = res;
+				log(
+					"warn",
+					`relay ${targetUrl} returned HTTP ${res.status} in ${elapsed}s — rolling to next relay`,
+					{ upstream: url, status: res.status },
+				);
+				continue;
+			}
+
+			// SUCCESS or non-retriable client error (e.g. 200, 400 Bad Request, 404):
+			// If we switched to a different relay because previous failed, update sticky active relay!
+			if (relayState.url !== targetUrl) {
+				log("info", `active relay auto-switched to ${targetUrl}`, {
+					previous: relayState.url,
+				});
+				relayState.url = targetUrl;
+				saveRelayState(relayState);
+			}
+
+			log("info", `relay ${targetUrl} succeeded (HTTP ${res.status} in ${elapsed}s)`);
+
+			// Update TUI status
+			const label = shortRelayLabel(targetUrl);
+			const total = relayState.relays.length || 1;
+			const pos = Math.max(
+				1,
+				relayState.relays.findIndex((r) => r.url === targetUrl) + 1,
+			);
+			statusUi?.setStatus?.("freeflow", `relay: ON | ${label} ${pos}/${total}`);
+
+			return res;
+		} catch (err) {
+			const elapsed = ((Date.now() - attemptStart) / 1000).toFixed(1);
+			lastError = err;
+			log(
+				"warn",
+				`relay ${targetUrl} fetch error in ${elapsed}s — rolling to next relay`,
+				{ upstream: url, error: String(err) },
+			);
+			continue;
+		}
+	}
+
+	// Full fallback: attempt direct fetch to upstream
+	const directStart = Date.now();
+	try {
+		log("warn", "relays bypassed/exhausted — attempting direct fetch to upstream", {
+			upstream: url,
+			sizeKB: bodySizeKB,
+		});
+		const directHeaders = new Headers(opts.headers);
+		directHeaders.delete("x-relay-target");
+		directHeaders.delete("x-relay-path");
+		directHeaders.set("host", u.host);
+		const directRes = await fetch(url, { ...opts, headers: directHeaders });
+		const directElapsed = ((Date.now() - directStart) / 1000).toFixed(1);
+		log("info", `direct fetch returned HTTP ${directRes.status} in ${directElapsed}s`);
+		return directRes;
+	} catch (directErr) {
+		const directElapsed = ((Date.now() - directStart) / 1000).toFixed(1);
+		log("error", `direct fallback also failed in ${directElapsed}s`, {
+			upstream: url,
+			error: String(directErr),
+		});
+		if (lastResponse) return lastResponse;
+		throw directErr || lastError;
+	}
+}
+
+// ── Deploy a fresh Vercel relay (same flow as 9Router) ───────────────────────
+// Token is used in-memory only and NEVER persisted. Resulting URL is saved to
+// the relay state and activated. Worker uses the x-relay-target/x-relay-path
+// pattern, identical to the cloudflare/vercel relays 9Router deploys.
+const VERCEL_API = "https://api.vercel.com";
+const VERCEL_RELAY_WORKER = `// Only the 2 upstreams pi-bansos talks to. Anything else = open proxy abuse.
+const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
+export const config = { runtime: "edge" };
+export default async function handler(req) {
+  const target = req.headers.get("x-relay-target");
+  const relayPath = req.headers.get("x-relay-path") || "/";
+  if (!target) return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), { status: 400, headers: { "content-type": "application/json" } });
+  const cleanTarget = target.replace(/\\/$/, "");
+  if (!ALLOWED_TARGETS.includes(cleanTarget)) return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403, headers: { "content-type": "application/json" } });
+  if (!relayPath.startsWith("/")) return new Response(JSON.stringify({ error: "Bad path" }), { status: 400, headers: { "content-type": "application/json" } });
+  const targetUrl = cleanTarget + relayPath;
+  const headers = new Headers(req.headers);
+  headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
+  const response = await fetch(targetUrl, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined, duplex: "half" });
+  return new Response(response.body, { status: response.status, headers: response.headers });
+}`;
+
+async function deployVercelRelay(
+	token: string,
+	name: string,
+	onProgress?: (msg: string) => void,
+): Promise<string> {
+	const auth = {
+		Authorization: `Bearer ${token}`,
+		"Content-Type": "application/json",
+	};
+	// 1. create deployment (3 inline files, no git repo)
+	onProgress?.("Uploading relay to Vercel…");
+	const dep = await fetch(`${VERCEL_API}/v13/deployments`, {
+		method: "POST",
+		headers: auth,
+		body: JSON.stringify({
+			name,
+			files: [
+				{ file: "api/relay.js", data: VERCEL_RELAY_WORKER },
+				{
+					file: "package.json",
+					data: JSON.stringify({ name, version: "1.0.0" }),
+				},
+				{
+					file: "vercel.json",
+					data: JSON.stringify({
+						rewrites: [{ source: "/(.*)", destination: "/api/relay" }],
+					}),
+				},
+			],
+			projectSettings: { framework: null },
+			target: "production",
+		}),
+	});
+	if (!dep.ok) {
+		const e = await dep
+			.json()
+			.catch(() => ({}) as { error?: { message?: string } });
+		throw new Error(
+			e?.error?.message || `Vercel deploy failed (HTTP ${dep.status})`,
+		);
+	}
+	const depJson = await dep.json();
+	const depId = depJson.id || depJson.uid;
+	const projectId = depJson.projectId || name;
+	// 2. make the deployment public (disable SSO protection)
+	await fetch(`${VERCEL_API}/v9/projects/${projectId}`, {
+		method: "PATCH",
+		headers: auth,
+		body: JSON.stringify({ ssoProtection: null }),
+	});
+	// 3. poll until READY (3s interval, 120s timeout — same as 9Router)
+	onProgress?.("Waiting for deployment to go live…");
+	const deadline = Date.now() + 120_000;
+	while (Date.now() < deadline) {
+		const s = await fetch(`${VERCEL_API}/v13/deployments/${depId}`, {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		const j = await s.json();
+		if (j.readyState === "READY") return `https://${j.url}`;
+		if (j.readyState === "ERROR" || j.readyState === "CANCELED")
+			throw new Error(`Deployment failed: ${j.readyState}`);
+		await new Promise((r) => setTimeout(r, 3000));
+	}
+	throw new Error("Deployment timed out (120s)");
+}
+
+// ── Model Definitions ──────────────────────────────────────────────
+type ProviderApi = "openai-completions" | "openai-responses";
+type Upstream = "opencode" | "kilo";
+
+interface ModelDef {
+	id: string;
+	name: string;
+	reasoning: boolean;
+	contextWindow: number;
+	maxTokens: number;
+	api?: ProviderApi;
+	input?: ("text" | "image")[];
+	thinkingFormat?: "openrouter";
+	thinkingLevelMap?: Partial<
+		Record<
+			"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max",
+			string | null
+		>
+	>;
+}
+
+// OpenCode Zen free models verified against the live catalog and inference APIs.
+const KNOWN_MODELS: ModelDef[] = [
+	{
+		id: "x-preview-f-free",
+		name: "Ox Alpha Free",
+		reasoning: true,
+		contextWindow: 1_048_576,
+		maxTokens: 131_072,
+		input: ["text", "image"],
+		thinkingLevelMap: {
+			off: "low",
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "muse-spark-1.2-contributor-free",
+		name: "Muse Spark 1.2 Free",
+		reasoning: true,
+		contextWindow: 1_048_576,
+		maxTokens: 131_072,
+		api: "openai-responses",
+		input: ["text", "image"],
+		thinkingLevelMap: {
+			off: null,
+			minimal: "minimal",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "xhigh",
+			max: "max",
+		},
+	},
+	{
+		id: "mimo-v2.5-free",
+		name: "MiMo V2.5 Free",
+		reasoning: true,
+		contextWindow: 1_048_576,
+		maxTokens: 131_072,
+		input: ["text", "image"],
+		thinkingLevelMap: {
+			off: "low",
+			minimal: "low",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "high",
+			max: "high",
+		},
+	},
+	{
+		id: "hy3-free",
+		name: "Hy3 Free",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 128_000,
+		thinkingLevelMap: {
+			off: "low",
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "nemotron-3-ultra-free",
+		name: "Nemotron 3 Ultra Free",
+		reasoning: true,
+		contextWindow: 1_000_000,
+		maxTokens: 128_000,
+		thinkingLevelMap: {
+			off: "low",
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "nemotron-3.5-lightning-free",
+		name: "Nemotron 3.5 Lightning Free",
+		reasoning: true,
+		contextWindow: 1_000_000,
+		maxTokens: 262_144,
+		thinkingLevelMap: {
+			off: "low",
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "big-pickle",
+		name: "Big Pickle",
+		reasoning: true,
+		contextWindow: 200_000,
+		maxTokens: 32_000,
+		thinkingLevelMap: {
+			off: "high",
+			minimal: "high",
+			low: "high",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "laguna-s-2.1-free",
+		name: "Laguna S 2.1 Free",
+		reasoning: true,
+		contextWindow: 1_048_576,
+		maxTokens: 131_072,
+		thinkingLevelMap: {
+			off: "low",
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+];
+
+// KiloCode gateway free models (keyless — https://kilo.ai/docs/gateway).
+const KILO_MODELS: ModelDef[] = [
+	{
+		id: "kilo-auto/free",
+		name: "Kilo Auto Free",
+		reasoning: false,
+		contextWindow: 256_000,
+		maxTokens: 10_000,
+		input: ["text"],
+	},
+	{
+		id: "stepfun/step-3.7-flash:free",
+		name: "Step 3.7 Flash Free",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 262_144,
+		input: ["text", "image"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "nvidia/nemotron-3-ultra-550b-a55b:free",
+		name: "Nemotron 3 Ultra Free",
+		reasoning: true,
+		contextWindow: 1_000_000,
+		maxTokens: 65_536,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "nvidia/nemotron-3-super-120b-a12b:free",
+		name: "Nemotron 3 Super Free",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 262_144,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "dots-studio/dots-3-note-preview:free",
+		name: "Dots3-Note Preview Free",
+		reasoning: true,
+		contextWindow: 512_000,
+		maxTokens: 512_000,
+		input: ["text", "image"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "cohere/north-mini-code:free",
+		name: "North Mini Code Free",
+		reasoning: true,
+		contextWindow: 256_000,
+		maxTokens: 64_000,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "poolside/laguna-xs-2.1:free",
+		name: "Laguna XS 2.1 Free",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 32_768,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+		name: "Nemotron 3 Nano Omni Free",
+		reasoning: true,
+		contextWindow: 256_000,
+		maxTokens: 65_536,
+		input: ["text", "image"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "openrouter/free",
+		name: "OpenRouter Free (auto)",
+		reasoning: false,
+		contextWindow: 200_000,
+		maxTokens: 65_536,
+		input: ["text"],
+	},
+	{
+		id: "nvidia/nemotron-3.5-lightning:free",
+		name: "Nemotron 3.5 Lightning Free",
+		reasoning: true,
+		contextWindow: 1_000_000,
+		maxTokens: 65_536,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "nvidia/nemotron-3.5-content-safety:free",
+		name: "Nemotron 3.5 Content Safety Free",
+		reasoning: false,
+		contextWindow: 128_000,
+		maxTokens: 8_192,
+		input: ["text"],
+	},
+	{
+		id: "tencent/hy3:free",
+		name: "Tencent Hy3 Free",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 128_000,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "liquid/lfm-2.5-2.6b:free",
+		name: "Liquid LFM 2.5 2.6B Free",
+		reasoning: true,
+		contextWindow: 65_536,
+		maxTokens: 8_192,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "poolside/laguna-s-2.1:free",
+		name: "Laguna S 2.1 Free",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 32_768,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+];
+const KILO_MODEL_IDS = new Set(KILO_MODELS.map((m) => m.id));
+
+// ── Whitelists ─────────────────────────────────────────────────────
+const ALLOWED_PATH_PATTERN = /^\/v1\/[a-zA-Z0-9/_.,\-?&=]*$/;
+const PATH_TRAVERSAL_PATTERN = /\.\./;
+const ALLOWED_METHODS = new Set(["GET", "POST", "OPTIONS", "HEAD"]);
+const STRIP_HEADERS = new Set([
+	"authorization",
+	"host",
+	"x-forwarded-for",
+	"x-forwarded-host",
+	"x-forwarded-proto",
+	"x-real-ip",
+	"x-client-ip",
+	"x-originate-ip",
+	"cookie",
+	"set-cookie",
+	"proxy-connection",
+	"proxy-authorization",
+]);
+
+// ── Logger ─────────────────────────────────────────────────────────
+type LogLevel = "info" | "warn" | "error" | "audit";
+function log(level: LogLevel, message: string, meta?: Record<string, unknown>) {
+	try {
+		const ts = new Date().toISOString();
+		const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
+		const line = `[${ts}] [${level.toUpperCase()}] ${message}${metaStr}\n`;
+		try {
+			if (fs.existsSync(LOG_FILE) && fs.statSync(LOG_FILE).size > 2 * 1024 * 1024) {
+				const backup = `${LOG_FILE}.1`;
+				try { if (fs.existsSync(backup)) fs.unlinkSync(backup); } catch {}
+				fs.renameSync(LOG_FILE, backup);
+			}
+		} catch {}
+		fs.appendFileSync(LOG_FILE, line, "utf8");
+	} catch {}
+}
+
+// ── Rate Limiter ───────────────────────────────────────────────────
+// Kilo documents 200 free requests/hour/IP. OpenCode owns its own daily quota;
+// local limits only stop one Pi process from flooding either upstream.
+const rateLimitMap = new Map<string, { count: number; resetAt: number }>();
+const RATE_LIMIT_MAX: Record<Upstream, number> = {
+	opencode: 200, // public free quota: requests per UTC day/IP
+	kilo: 200, // documented gateway quota: requests per one-hour window/IP
+};
+
+function rateLimitResetAt(upstream: Upstream, now: number): number {
+	if (upstream === "kilo") return now + 60 * 60_000;
+	const nextUtcDay = new Date(now);
+	nextUtcDay.setUTCHours(24, 0, 0, 0);
+	return nextUtcDay.getTime();
+}
+
+function rateLimitKey(upstream: Upstream, ip: string, now: number): string {
+	if (upstream === "kilo") return `${upstream}:${ip}`;
+	return `${upstream}:${new Date(now).toISOString().slice(0, 10)}:${ip}`;
+}
+
+// ponytail: Vercel relay rejects requests that ask for very large max_tokens
+// (response body / duration limits). Clamp at relay layer so direct mode stays
+// unconstrained and model config stays accurate.
+const RELAY_MAX_TOKENS = 131_072;
+
+function checkRateLimit(ip: string, upstream: Upstream): boolean {
+	const now = Date.now();
+	const key = rateLimitKey(upstream, ip, now);
+	const entry = rateLimitMap.get(key);
+	if (!entry || entry.resetAt <= now) {
+		rateLimitMap.set(key, {
+			count: 1,
+			resetAt: rateLimitResetAt(upstream, now),
+		});
+		return true;
+	}
+	if (entry.count >= RATE_LIMIT_MAX[upstream]) return false;
+	entry.count++;
+	return true;
+}
+
+// ── Health Check (OpenCode/Kilo catalogs; no per-model inference) ──
+// Each upstream publishes a model list; fetch it ONCE (cached) and check
+// membership. A 1-token chat probe per model was too slow (large models need
+// 10s+ for the first token). Real usability is validated at chat time (300s).
+let opencodeCatalogP: Promise<Set<string> | null> | null = null;
+function opencodeCatalog(): Promise<Set<string> | null> {
+	if (!opencodeCatalogP)
+		opencodeCatalogP = (async () => {
+			try {
+				const r = await fetch(`${API}/models`, {
+					headers: opencodeHeaders(),
+					signal: AbortSignal.timeout(10_000),
+				});
+				if (!r.ok) return null;
+				const d = await r.json();
+				return new Set<string>(
+					(d?.data ?? []).map((m: { id: string }) => m.id),
+				);
+			} catch {
+				return null;
+			}
+		})();
+	return opencodeCatalogP;
+}
+let kiloCatalogP: Promise<Set<string> | null> | null = null;
+function kiloCatalog(): Promise<Set<string> | null> {
+	if (!kiloCatalogP)
+		kiloCatalogP = (async () => {
+			try {
+				const r = await fetch(
+					KILO_CHAT_URL.replace("/chat/completions", "/models"),
+					{
+						headers: { Authorization: "Bearer kilo-free" },
+						signal: AbortSignal.timeout(10_000),
+					},
+				);
+				if (!r.ok) return null;
+				const d = await r.json();
+				return new Set<string>(
+					(d?.data ?? []).map((m: { id: string }) => m.id),
+				);
+			} catch {
+				return null;
+			}
+		})();
+	return kiloCatalogP;
+}
+
+async function checkModelAlive(id: string): Promise<boolean> {
+	try {
+		const cat = await opencodeCatalog();
+		return cat ? cat.has(id) : false;
+	} catch {
+		return false;
+	}
+}
+
+async function checkKiloAlive(id: string): Promise<boolean> {
+	try {
+		const cat = await kiloCatalog();
+		return cat ? cat.has(id) : false;
+	} catch {
+		return false;
+	}
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+function getClientIP(req: http.IncomingMessage): string {
+	const addr = req.socket.remoteAddress;
+	if (!addr) return "unknown";
+	return addr.startsWith("::ffff:") ? addr.slice(7) : addr;
+}
+
+function validatePath(rawUrl: string): URL | null {
+	const cleaned = rawUrl.replace(/^\/+/, "");
+	if (!ALLOWED_PATH_PATTERN.test(`/${cleaned}`)) return null;
+	if (PATH_TRAVERSAL_PATTERN.test(cleaned)) return null;
+	try {
+		const decoded = decodeURIComponent(cleaned);
+		if (decoded !== cleaned && !ALLOWED_PATH_PATTERN.test(`/${decoded}`))
+			return null;
+	} catch {
+		return null;
+	}
+	try {
+		return new URL(cleaned, `${UPSTREAM_OPENCODE}/`);
+	} catch {
+		return null;
+	}
+}
+
+function sanitizeHeaders(
+	incoming: http.IncomingHttpHeaders,
+	targetHost: string,
+): Record<string, string> {
+	const sanitized: Record<string, string> = {};
+	for (const [key, value] of Object.entries(incoming)) {
+		const lower = key.toLowerCase();
+		if (STRIP_HEADERS.has(lower) || lower.startsWith(":")) continue;
+		if (typeof value === "string") sanitized[lower] = value;
+		else if (Array.isArray(value)) sanitized[lower] = value.join(", ");
+	}
+	sanitized.host = targetHost;
+	Object.assign(sanitized, opencodeHeaders());
+	sanitized["accept-encoding"] = "identity";
+	sanitized.connection = "keep-alive";
+	return sanitized;
+}
+
+// ponytail: shared stream pipe — upstream abort/timeout must end response,
+// not become an uncaught exception that crashes pi.
+function pipeUpstreamStream(
+	nodeStream: Readable,
+	res: http.ServerResponse,
+	req: http.IncomingMessage,
+): void {
+	try {
+		if (typeof res.flushHeaders === "function") {
+			res.flushHeaders();
+		}
+	} catch {}
+
+	nodeStream.on("data", (chunk: Buffer | string) => {
+		try {
+			res.write(chunk);
+			if (typeof (res as any).flush === "function") {
+				(res as any).flush();
+			}
+		} catch {}
+	});
+
+	nodeStream.on("error", (e: unknown) => {
+		log("error", "upstream stream error", { error: String(e) });
+		try {
+			if (!res.headersSent) {
+				res.writeHead(502, { "content-type": "application/json" });
+			}
+			if (!res.writableEnded) {
+				res.end();
+			}
+		} catch {}
+	});
+	nodeStream.on("end", () => {
+		try {
+			if (!res.writableEnded) res.end();
+		} catch {}
+	});
+	nodeStream.on("close", () => {
+		try {
+			if (!res.writableEnded) res.end();
+		} catch {}
+	});
+	req.on("aborted", () => {
+		if (!nodeStream.destroyed) nodeStream.destroy();
+	});
+	req.on("close", () => {
+		if (!nodeStream.destroyed) nodeStream.destroy();
+	});
+}
+
+// ── Start local proxy ──────────────────────────────────────────────
+function startProxy(
+	overridePort?: number,
+): Promise<{ server: http.Server; port: number }> {
+	const basePort = overridePort ?? PORT;
+
+	const server = http.createServer((req, res) => {
+		const clientIP = getClientIP(req);
+
+		if (!ALLOWED_METHODS.has(req.method ?? "")) {
+			res.writeHead(405, { "content-type": "application/json" });
+			res.end(JSON.stringify({ error: "method not allowed" }));
+			return;
+		}
+
+		if (req.method === "OPTIONS") {
+			res.writeHead(204, {
+				"access-control-allow-origin": "*",
+				"access-control-allow-methods": "GET, POST, OPTIONS",
+				"access-control-max-age": "86400",
+			});
+			res.end();
+			return;
+		}
+
+		// Serve ONLY our registered free models. Never forward /v1/models to
+		// upstream (that would leak ~54 paid models into the picker).
+		if (
+			req.method === "GET" &&
+			(req.url === "/v1/models" || req.url === "/v1/models/")
+		) {
+			const body = JSON.stringify({
+				object: "list",
+				data: aliveCatalog.map((m) => ({
+					id: m.id,
+					object: "model",
+					created: 0,
+					owned_by: m.source === "kilo" ? "kilocode" : "opencode",
+				})),
+			});
+			res.writeHead(200, {
+				"content-type": "application/json",
+				"content-length": Buffer.byteLength(body),
+			});
+			res.end(body);
+			return;
+		}
+
+		const target = validatePath(req.url ?? "/");
+		if (!target) {
+			res.writeHead(403, { "content-type": "application/json" });
+			res.end(JSON.stringify({ error: "forbidden" }));
+			return;
+		}
+
+		// Read body to detect model for routing
+		const bodyChunks: Buffer[] = [];
+		req.on("data", (chunk: Buffer) => bodyChunks.push(chunk));
+		req.on("end", async () => {
+			const bodyStr = Buffer.concat(bodyChunks).toString();
+			let isKilo = false;
+			let parsedBody: Record<string, unknown> | null = null;
+
+			try {
+				parsedBody = JSON.parse(bodyStr);
+				if (
+					typeof parsedBody?.model === "string" &&
+					KILO_MODEL_IDS.has(parsedBody.model)
+				) {
+					isKilo = true;
+				}
+			} catch {}
+
+			const upstream: Upstream = isKilo ? "kilo" : "opencode";
+
+			try {
+				if (isKilo && parsedBody) {
+					// KiloCode gateway routing (free models are keyless)
+					const isStream = parsedBody.stream === true;
+					const response = await relayFetch(KILO_CHAT_URL, {
+						method: "POST",
+						headers: {
+							"Content-Type": "application/json",
+							Authorization: "Bearer kilo-free",
+						},
+						body: JSON.stringify(parsedBody),
+						signal: AbortSignal.timeout(300_000),
+					});
+					if (isStream && response.ok && response.body) {
+						const ct =
+							response.headers.get("content-type") || "text/event-stream";
+						res.writeHead(response.status, {
+							"content-type": ct,
+							"cache-control": "no-cache, no-transform",
+							"connection": "keep-alive",
+							"x-accel-buffering": "no",
+						});
+						pipeUpstreamStream(
+							Readable.fromWeb(
+								response.body as unknown as import("stream/web").ReadableStream,
+							),
+							res,
+							req,
+						);
+					} else {
+						const data = await response.text();
+						const ct =
+							response.headers.get("content-type") || "application/json";
+						res.writeHead(response.status, { "content-type": ct });
+						res.end(data);
+					}
+				} else {
+					// OpenCode routing — relay (fetch-based) when enabled, else direct (existing, untouched)
+					// round-robin: any saved relay qualifies, not just single url
+					if (relayState.enabled && (relayState.url || relayState.relays.length > 0)) {
+						const fullUrl = `${UPSTREAM_OPENCODE}${req.url ?? "/"}`;
+						const activeHost = new URL(relayState.url || DEFAULT_RELAY_URL).host;
+						const relayHeaders = sanitizeHeaders(
+							req.headers,
+							activeHost,
+						);
+						try {
+							// ponytail: clamp max_tokens for Vercel relay — large values
+							// cause 400 "Upstream request failed" (response size / duration
+							// limits). Direct mode stays unconstrained.
+							let relayBody = bodyChunks.length
+								? Buffer.concat(bodyChunks)
+								: undefined;
+							if (relayBody && parsedBody) {
+								const mt = parsedBody.max_tokens ?? parsedBody.maxTokens;
+								if (typeof mt === "number" && mt > RELAY_MAX_TOKENS) {
+									parsedBody.max_tokens = RELAY_MAX_TOKENS;
+								}
+								if (typeof parsedBody.reasoning_effort === "string") {
+									const re = parsedBody.reasoning_effort.toLowerCase();
+									if (re === "xhigh" || re === "max") {
+										parsedBody.reasoning_effort = "max";
+									} else if (re === "high" || re === "medium") {
+										parsedBody.reasoning_effort = "high";
+									} else {
+										parsedBody.reasoning_effort = "low";
+									}
+								}
+								relayBody = Buffer.from(JSON.stringify(parsedBody));
+							}
+							const response = await relayFetch(fullUrl, {
+								method: req.method || "POST",
+								headers: relayHeaders,
+								body: relayBody,
+								signal: AbortSignal.timeout(300_000),
+							});
+							const ct =
+								response.headers.get("content-type") || "application/json";
+							if (response.ok && response.body) {
+								const ct =
+									response.headers.get("content-type") || "text/event-stream";
+								res.writeHead(response.status, {
+									"content-type": ct,
+									"cache-control": "no-cache, no-transform",
+									"connection": "keep-alive",
+									"x-accel-buffering": "no",
+								});
+								pipeUpstreamStream(
+									Readable.fromWeb(
+										response.body as unknown as import("stream/web").ReadableStream,
+									),
+									res,
+									req,
+								);
+							} else {
+								const data = await response.text();
+								const ct =
+									response.headers.get("content-type") || "application/json";
+								res.writeHead(response.status, { "content-type": ct });
+								res.end(data);
+							}
+							return; // relay handled the response
+						} catch (e) {
+							log("warn", "opencode relay failed, falling back to direct", {
+								error: String(e),
+							});
+							if (res.headersSent) return; // can't recover mid-stream
+						}
+					}
+					// direct path (existing, untouched)
+					let directBody = Buffer.concat(bodyChunks);
+					if (parsedBody && typeof parsedBody.reasoning_effort === "string") {
+						const re = parsedBody.reasoning_effort.toLowerCase();
+						if (re === "xhigh" || re === "max") {
+							parsedBody.reasoning_effort = "max";
+						} else if (re === "high" || re === "medium") {
+							parsedBody.reasoning_effort = "high";
+						} else {
+							parsedBody.reasoning_effort = "low";
+						}
+						directBody = Buffer.from(JSON.stringify(parsedBody));
+					}
+					const fwd = sanitizeHeaders(req.headers, target.hostname);
+					if (directBody.length > 0) {
+						fwd["content-length"] = String(directBody.byteLength);
+					}
+					const proxy = https.request(
+						{
+							method: req.method,
+							hostname: target.hostname,
+							port: 443,
+							path: target.pathname + target.search,
+							headers: fwd,
+						},
+						(upstream) => {
+							const outHeaders: Record<string, string> = {};
+							for (const h of [
+								"content-type",
+								"cache-control",
+								"x-request-id",
+							]) {
+								const val = upstream.headers[h];
+								if (typeof val === "string") outHeaders[h] = val;
+							}
+							outHeaders["x-content-type-options"] = "nosniff";
+							res.writeHead(upstream.statusCode ?? 502, outHeaders);
+							upstream.pipe(res);
+						},
+					);
+					proxy.on("error", () => {
+						if (!res.headersSent) {
+							res.writeHead(502, { "content-type": "application/json" });
+							res.end(JSON.stringify({ error: "upstream error" }));
+						} else if (!res.writableEnded) {
+							res.end();
+						}
+					});
+					proxy.setTimeout(30_000, () => {
+						proxy.destroy(new Error("timeout"));
+					});
+					req.on("aborted", () => {
+						if (!proxy.destroyed) proxy.destroy();
+					});
+					// ponytail: body already buffered in bodyChunks above for model routing;
+					// req is drained so pipe() would send an empty body → upstream hang → 502.
+					proxy.end(directBody);
+				}
+			} catch (err) {
+				log("error", "proxy error", { error: String(err) });
+				if (!res.headersSent)
+					res.writeHead(502, { "content-type": "application/json" });
+				res.end(JSON.stringify({ error: "internal error" }));
+			}
+		});
+	});
+
+	return new Promise((resolve, reject) => {
+		// ponytail: auto-bump to next free port so multiple pi sessions on one
+		// machine don't fight over 18080. cap at 20 to avoid infinite scan.
+		// use server.address() for the real port: a failed listen()'s callback
+		// still fires on the next successful listen, so the closure `port` is stale.
+		let attempt = 0;
+		let settled = false;
+		const tryListen = (port: number) => {
+			server.once("error", (err: NodeJS.ErrnoException) => {
+				if (settled) return;
+				if (err.code === "EADDRINUSE" && attempt < 20) {
+					attempt++;
+					log("warn", `port ${port} taken — trying ${port + 1}`);
+					tryListen(port + 1);
+					return;
+				}
+				settled = true;
+				log("error", "server error", { code: err.code, message: err.message });
+				reject(err);
+			});
+			server.listen(port, HOST, () => {
+				if (settled) return;
+				settled = true;
+				const addr = server.address();
+				const realPort = addr && typeof addr === "object" ? addr.port : port;
+				log("info", `proxy listening on http://${HOST}:${realPort}`);
+				resolve({ server, port: realPort });
+			});
+		};
+		tryListen(basePort);
+	});
+}
+
+// ── Main extension ─────────────────────────────────────────────────
+export default async function (pi: ExtensionAPI) {
+	log("info", "extension loading...");
+	let server: http.Server;
+	let actualPort: number;
+	try {
+		const r = await startProxy();
+		server = r.server;
+		actualPort = r.port;
+	} catch {
+		log(
+			"error",
+			"extension inactive — could not bind proxy port. resolve the port conflict and restart pi.",
+		);
+		return;
+	}
+
+	// Health check opencode models
+	log("info", `checking ${KNOWN_MODELS.length} opencode model(s)...`);
+	const opencodeChecks = await Promise.all(
+		KNOWN_MODELS.map(async (model) => {
+			const alive = await checkModelAlive(model.id);
+			if (alive) log("info", `✓ ${model.id} is alive`);
+			else log("warn", `✗ ${model.id} is dead — skipping`);
+			return { ...model, alive, source: "opencode" as const };
+		}),
+	);
+
+	// Health check kilo models
+	log("info", `checking ${KILO_MODELS.length} kilo model(s)...`);
+	const kiloChecks = await Promise.all(
+		KILO_MODELS.map(async (model) => {
+			const alive = await checkKiloAlive(model.id);
+			if (alive) log("info", `✓ ${model.id} (kilo) is alive`);
+			else log("warn", `✗ ${model.id} (kilo) is dead — skipping`);
+			return { ...model, alive, source: "kilo" as const };
+		}),
+	);
+
+	const aliveModels = [...opencodeChecks, ...kiloChecks].filter((m) => m.alive);
+	aliveCatalog = aliveModels;
+
+	if (aliveModels.length === 0) {
+		// Don't bail: still register /bansos below so the user can recover
+		// (e.g. switch the relay off) instead of being stranded with no command.
+		log(
+			"warn",
+			"no alive models found — provider inactive; /bansos still available to switch relay off / go direct",
+		);
+	} else {
+		log(
+			"info",
+			`${aliveModels.length} model(s) registered: ${aliveModels.map((m) => m.id).join(", ")}`,
+		);
+
+		const providerConfig = {
+			baseUrl: `http://${HOST}:${actualPort}/v1`,
+			apiKey: "placeholder",
+			api: "openai-completions" as const,
+			compat: { supportsDeveloperRole: false },
+			models: aliveModels.map((m) => ({
+				id: m.id,
+				name: `${m.source === "kilo" ? "KiloCode" : "OpenCode"} · ${m.name}`,
+				api: m.api,
+				reasoning: m.reasoning,
+				thinkingLevelMap: m.thinkingLevelMap,
+				input: m.input ?? ["text"],
+				contextWindow: m.contextWindow,
+				maxTokens: m.maxTokens,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				compat: m.thinkingFormat
+					? { supportsDeveloperRole: false, thinkingFormat: m.thinkingFormat }
+					: m.api === "openai-responses"
+						? { sessionAffinityFormat: "openai-nosession" }
+						: m.source === "kilo"
+							? { supportsDeveloperRole: false, supportsReasoningEffort: false }
+							: { supportsDeveloperRole: false, supportsReasoningEffort: true },
+			})),
+		};
+
+		pi.registerProvider("freeflow", providerConfig);
+		pi.registerProvider("bansos", providerConfig);
+	}
+	// ── /bansos command: toggle relay egress live (on|off|status|url [URL]) ───
+	const commandSpec = {
+		description:
+			"Relay egress: on | off | status | logs | url [URL] | deploy | list | use <URL> | remove <URL>",
+		getArgumentCompletions: (prefix: string) =>
+			["on", "off", "status", "url", "deploy", "list", "use", "remove"]
+				.filter((s) => s.startsWith(prefix))
+				.map((s) => ({ value: s, label: s })),
+		handler: async (args: string, ctx) => {
+			const parts = String(args || "")
+				.trim()
+				.split(/\s+/);
+			const sub = parts[0] || "";
+			const rest = parts.slice(1).join(" ");
+
+			const flash = () => {
+				const activeLabel = shortRelayLabel(relayState.url);
+				const activeIdx = Math.max(1, relayState.relays.findIndex((r) => r.url === relayState.url) + 1);
+				const total = relayState.relays.length || 1;
+				ctx.ui.notify(
+					`Relay ${relayState.enabled ? "ON" : "OFF"}${relayState.enabled ? ` → ${activeLabel} (${activeIdx}/${total})` : " (direct)"} | saved=${relayState.relays.length} (auto-fallback rolling)`,
+					"info",
+				);
+			};
+			const persist = () => {
+				saveRelayState(relayState);
+				statusUi = ctx.ui;
+				ctx.ui.setStatus("freeflow", undefined);
+				ctx.ui.setStatus("bansos", undefined);
+			};
+			// mutate in place so the saved-relays list is preserved across switches
+			const setRelay = (enabled: boolean, url: string, addLabel?: string) => {
+				relayState.enabled = enabled;
+				relayState.url = (url || "").trim() || DEFAULT_RELAY_URL;
+				if (relayState.url) ensureRelay(relayState, relayState.url, addLabel);
+			};
+			const doDeploy = async () => {
+				// Token prompted (not stored). pi's input has no secret mode — shows while typing.
+				const defaultName = `relay-${Date.now().toString(36)}`;
+				const token = (
+					await ctx.ui.input("Vercel API token (vercel-…):", "")
+				)?.trim();
+				if (!token) {
+					ctx.ui.notify("Deploy cancelled — no token", "warning");
+					return;
+				}
+				const name =
+					(
+						await ctx.ui.input("Project name (empty = auto):", defaultName)
+					)?.trim() || defaultName;
+				ctx.ui.setStatus("bansos", "deploying relay…");
+				try {
+					const url = await deployVercelRelay(token, name, (m) =>
+						ctx.ui.notify(m, "info"),
+					);
+					setRelay(true, url, `deployed ${name}`);
+					persist();
+					ctx.ui.notify(`✓ Deployed & active: ${url}`, "info");
+				} catch (e) {
+					ctx.ui.setStatus(
+						"freeflow",
+						`relay: ${relayState.enabled ? "ON" : "OFF"}`,
+					);
+					ctx.ui.notify(`Deploy failed: ${(e as Error).message}`, "error");
+				}
+			};
+			const switchRelay = async () => {
+				if (!relayState.relays.length) {
+					ctx.ui.notify("No saved relays yet", "warning");
+					return;
+				}
+				const fmt = (r: KnownRelay) =>
+					`${r.url === relayState.url ? "★ " : "  "}${r.url}${r.label ? `  (${r.label})` : ""}`;
+				const opts = relayState.relays.map(fmt);
+				const choice = await ctx.ui.select("Switch relay", opts);
+				if (!choice) return;
+				const match = relayState.relays.find((r) => fmt(r) === choice);
+				if (!match) return;
+				setRelay(true, match.url);
+				persist();
+				flash();
+			};
+			const showList = () => {
+				if (!relayState.relays.length) {
+					ctx.ui.notify("No saved relays", "info");
+					return;
+				}
+				const lines = relayState.relays.map(
+					(r) =>
+						`${r.url === relayState.url ? "★" : " "} ${r.url}${r.label ? `  [${r.label}]` : ""}`,
+				);
+				ctx.ui.notify(
+					`Saved relays (${relayState.relays.length}):\n${lines.join("\n")}`,
+					"info",
+				);
+			};
+			const removeRelayMenu = async () => {
+				const removable = relayState.relays.filter(
+					(r) => r.url !== relayState.url,
+				);
+				if (!removable.length) {
+					ctx.ui.notify(
+						"Nothing to remove — the active relay can't be removed (switch first)",
+						"warning",
+					);
+					return;
+				}
+				const fmt = (r: KnownRelay) =>
+					`${r.url}${r.label ? `  (${r.label})` : ""}`;
+				const choice = await ctx.ui.select("Remove relay", removable.map(fmt));
+				if (!choice) return;
+				const match = removable.find((r) => fmt(r) === choice);
+				if (!match) return;
+				removeRelay(relayState, match.url);
+				persist();
+				ctx.ui.notify(`Removed: ${match.url}`, "info");
+			};
+
+			if (sub === "on") {
+				setRelay(true, relayState.url || DEFAULT_RELAY_URL);
+				persist();
+				flash();
+			} else if (sub === "off") {
+				relayState.enabled = false;
+				persist();
+				flash();
+			} else if (sub === "status") {
+				flash();
+			} else if (sub === "list") {
+				showList();
+			} else if (sub === "use") {
+				const url = (
+					rest ||
+					(await ctx.ui.input("Relay URL to activate:", "")) ||
+					""
+				).trim();
+				if (!url) {
+					ctx.ui.notify("No URL given", "warning");
+					return;
+				}
+				setRelay(true, url, "manual");
+				persist();
+				flash();
+			} else if (sub === "logs" || sub === "log") {
+				try {
+					if (!fs.existsSync(LOG_FILE)) {
+						ctx.ui.notify(`No logs recorded yet in ${LOG_FILE}`, "info");
+						return;
+					}
+					const content = fs.readFileSync(LOG_FILE, "utf8");
+					const lines = content.trim().split("\n").slice(-25);
+					ctx.ui.notify(`pi-freeflow logs (last 25 lines from ${LOG_FILE}):\n\n${lines.join("\n")}`, "info");
+				} catch (e) {
+					ctx.ui.notify(`Could not read log file: ${(e as Error).message}`, "error");
+				}
+			} else if (sub === "remove") {
+				const url = (
+					rest ||
+					(await ctx.ui.input("Relay URL to remove:", "")) ||
+					""
+				).trim();
+				if (!url) {
+					ctx.ui.notify("No URL given", "warning");
+					return;
+				}
+				if (url === relayState.url) {
+					ctx.ui.notify(
+						"Can't remove the active relay — switch first",
+						"warning",
+					);
+					return;
+				}
+				if (!relayState.relays.some((r) => r.url === url)) {
+					ctx.ui.notify("Not in saved list", "warning");
+					return;
+				}
+				removeRelay(relayState, url);
+				persist();
+				ctx.ui.notify(`Removed: ${url}`, "info");
+			} else if (sub === "url") {
+				const input =
+					rest ||
+					(await ctx.ui.input(
+						"Relay URL (empty = default):",
+						relayState.url || DEFAULT_RELAY_URL,
+					));
+				setRelay(
+					relayState.enabled,
+					(input || "").trim() || DEFAULT_RELAY_URL,
+					"manual",
+				);
+				persist();
+				flash();
+			} else if (sub === "deploy") {
+				await doDeploy();
+			} else {
+				const choice = await ctx.ui.select("bansos relay", [
+					`Relay: ${relayState.enabled ? "ON" : "OFF"} → ${relayState.url || "direct"}`,
+					"Turn ON",
+					"Turn OFF",
+					"Switch relay…",
+					"Remove relay…",
+					"Set URL",
+					"Deploy Vercel relay…",
+					"List saved relays",
+				]);
+				if (choice === "Turn ON") {
+					setRelay(true, relayState.url || DEFAULT_RELAY_URL);
+					persist();
+					flash();
+				} else if (choice === "Turn OFF") {
+					relayState.enabled = false;
+					persist();
+					flash();
+				} else if (choice === "Switch relay…") {
+					await switchRelay();
+				} else if (choice === "Remove relay…") {
+					await removeRelayMenu();
+				} else if (choice === "Set URL") {
+					const input = await ctx.ui.input(
+						"Relay URL (empty = default):",
+						relayState.url || DEFAULT_RELAY_URL,
+					);
+					setRelay(
+						relayState.enabled,
+						(input || "").trim() || DEFAULT_RELAY_URL,
+						"manual",
+					);
+					persist();
+					flash();
+				} else if (choice === "Deploy Vercel relay…") {
+					await doDeploy();
+				} else if (choice === "List saved relays") {
+					showList();
+				}
+			}
+		},
+	};
+	pi.registerCommand("freeflow", commandSpec);
+	pi.registerCommand("bansos", commandSpec);
+
+	// Reload persisted state on session start/resume (env overrides still win).
+	pi.on("session_start", async (_event, ctx) => {
+		relayState = resolveRelayState();
+		statusUi = ctx.ui;
+		ctx.ui?.setStatus?.("freeflow", undefined);
+		ctx.ui?.setStatus?.("bansos", undefined);
+	});
+
+	// Pi normally pauses after threshold compaction. Queue a follow-up while the
+	// original run is still active so the core agent continues automatically.
+	pi.on("session_compact", (event, ctx) => {
+		if (
+			event.reason !== "threshold" ||
+			event.willRetry ||
+			ctx.isIdle() ||
+			ctx.hasPendingMessages()
+		) {
+			return;
+		}
+		pi.sendUserMessage(
+			"Continue the current task from the compacted context. Do not wait for another user message; proceed with the next required step.",
+			{ deliverAs: "followUp" },
+		);
+	});
+
+	pi.on("session_shutdown", () => {
+		log("info", "shutting down proxy...");
+		server.close();
+		rateLimitMap.clear();
+		log("info", "shutdown complete");
+	});
+}