pi-freeflow 1.2.0 → 1.2.1

package/src/deploy.ts

@@ -0,0 +1,126 @@
+/**
+ * Automated Vercel Edge Relay deployer for pi-freeflow
+ *
+ * Deploys a private 3-file Vercel edge proxy with strict target domain whitelisting.
+ * The provided API token is held in-memory only and never persisted to disk or logs.
+ */
+
+import { VERCEL_API } from "./config.ts";
+import { log, logError } from "./logger.ts";
+
+/**
+ * Hardened Edge Worker code deployed to Vercel.
+ * Strictly whitelists OpenCode Zen and KiloCode Gateway endpoints to prevent open proxy abuse.
+ */
+export const VERCEL_RELAY_WORKER = `// Only the 2 upstreams pi-freeflow 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 });
+}`;
+
+/**
+ * Deploy a fresh Vercel Edge Relay project in-memory.
+ *
+ * @param token Vercel personal access token (used in-memory only)
+ * @param name Unique project/deployment name (e.g. pi-freeflow-relay-abc123)
+ * @param onProgress Optional callback for user-facing progress updates
+ * @returns Deployed HTTPS relay URL
+ */
+export 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 repository required)
+	onProgress?.("Uploading relay files to Vercel…");
+	log("info", `Starting Vercel deployment: ${name}`);
+
+	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 } };
+		const errMsg = e?.error?.message || `Vercel deploy failed (HTTP ${dep.status})`;
+		logError(`Vercel deployment failed to create: ${errMsg}`);
+		throw new Error(errMsg);
+	}
+
+	const depJson = (await dep.json()) as { id?: string; uid?: string; projectId?: string };
+	const depId = depJson.id || depJson.uid;
+	const projectId = depJson.projectId || name;
+
+	// 2. Make the deployment public (disable SSO protection if enabled on team)
+	try {
+		await fetch(`${VERCEL_API}/v9/projects/${projectId}`, {
+			method: "PATCH",
+			headers: auth,
+			body: JSON.stringify({ ssoProtection: null }),
+		});
+	} catch {}
+
+	// 3. Poll until READY state (3s interval, 120s maximum timeout)
+	onProgress?.("Waiting for Edge 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}` },
+		});
+		if (s.ok) {
+			const j = (await s.json()) as { readyState?: string; url?: string };
+			if (j.readyState === "READY" && j.url) {
+				const deployedUrl = `https://${j.url}`;
+				log("info", `Vercel relay successfully deployed: ${deployedUrl}`);
+				return deployedUrl;
+			}
+			if (j.readyState === "ERROR" || j.readyState === "CANCELED") {
+				const err = `Deployment failed with state: ${j.readyState}`;
+				logError(err);
+				throw new Error(err);
+			}
+		}
+		await new Promise<void>((r) => setTimeout(r, 3000));
+	}
+
+	const timeoutErr = "Deployment timed out (120s)";
+	logError(timeoutErr);
+	throw new Error(timeoutErr);
+}

package/src/index.ts

@@ -0,0 +1,243 @@
+/**
+ * pi-freeflow — Modular, high-resiliency LLM extension for Pi & Oh My Pi (OMP)
+ *
+ * Provides access to 23 free models (9 OpenCode Zen + 14 KiloCode Gateway) with:
+ * - Single-port daemon reuse on 18080 across concurrent subagents
+ * - Multi-cloud rolling egress relays (Vercel Edge, Cloudflare, Deno)
+ * - 0ms instant startup with verified static catalog and background live health checks
+ * - Per-model thinking/reasoning translation and streaming SSE pass-through
+ */
+
+import type * as http from "node:http";
+import {
+	getAliveCatalog,
+	readCatalogCache,
+	refreshCatalog,
+	setAliveCatalog,
+} from "./catalog.ts";
+import { createCommandSpec, updateStatusBar } from "./commands.ts";
+import { DEFAULT_HOST, HOST, PORT } from "./config.ts";
+import { log, logInfo, logWarn } from "./logger.ts";
+import { ALL_MODELS, KILO_MODEL_IDS } from "./models.ts";
+import { isProxyAlive, startProxy } from "./proxy.ts";
+import { resetRateLimits } from "./rate-limiter.ts";
+import {
+	getActiveRelayState,
+	resolveRelayState,
+	setActiveRelayState,
+	setStatusUi,
+} from "./relay-state.ts";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ProviderConfig,
+	RegisteredModel,
+} from "./types.ts";
+
+// Re-export all sub-modules for clean library and programmatic usage
+export * from "./types.ts";
+export * from "./config.ts";
+export * from "./logger.ts";
+export * from "./rate-limiter.ts";
+export * from "./models.ts";
+export * from "./catalog.ts";
+export * from "./relay-state.ts";
+export * from "./relay.ts";
+export * from "./deploy.ts";
+export * from "./normalizer.ts";
+export * from "./stream-pipe.ts";
+export * from "./proxy.ts";
+export * from "./commands.ts";
+
+/**
+ * Construct standard ProviderConfig for pi-ai / OMP registration.
+ */
+export function buildProviderConfig(
+	models: RegisteredModel[],
+	port: number = PORT,
+): ProviderConfig {
+	return {
+		baseUrl: `http://${HOST}:${port}/v1`,
+		apiKey: "placeholder",
+		api: "openai-completions",
+		compat: { supportsDeveloperRole: false },
+		models: models.map((m) => {
+			const efforts = m.thinkingLevelMap
+				? (Object.keys(m.thinkingLevelMap) as (keyof typeof m.thinkingLevelMap)[]).filter(
+						(k) => m.thinkingLevelMap![k] !== null && k !== "off",
+					)
+				: ["minimal", "low", "medium", "high", "xhigh"];
+
+			return {
+				id: m.id,
+				name: m.name,
+				api: m.api,
+				reasoning: m.reasoning,
+				thinking: m.reasoning
+					? {
+							mode: "effort",
+							efforts: efforts.length > 0 ? efforts : ["low", "high", "max"],
+						}
+					: undefined,
+				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,
+								},
+			};
+		}),
+	};
+}
+
+/**
+ * Main extension entrypoint
+ */
+export default async function (pi: ExtensionAPI): Promise<void> {
+	logInfo("pi-freeflow extension initializing...");
+
+
+	let server: http.Server | null = null;
+	let actualPort = PORT;
+
+	// 2. Single-Port Shared Pattern: Check if daemon is already running (e.g. parent session)
+	const alreadyRunning = await isProxyAlive(PORT);
+	if (alreadyRunning) {
+		logInfo(
+			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${PORT}`,
+		);
+		actualPort = PORT;
+	} else {
+		try {
+			const r = await startProxy();
+			server = r.server;
+			actualPort = r.port;
+		} catch (e) {
+			log(
+				"error",
+				"extension inactive — could not bind proxy port. resolve the port conflict and restart pi.",
+				{ error: String(e) },
+			);
+			return;
+		}
+	}
+
+	// 3. Instant 0ms Static Catalog Registration
+	// Register static models immediately on boot so Pi/OMP picker is populated with zero latency!
+	const initialCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
+		...m,
+		source: KILO_MODEL_IDS.has(m.id) ? "kilo" : "opencode",
+	}));
+	setAliveCatalog(initialCatalog);
+	pi.registerProvider(
+		"freeflow",
+		buildProviderConfig(initialCatalog, actualPort),
+	);
+
+	// 4. Background Catalog Refresh
+	// Asynchronously probe live upstreams and update the provider if alive model list changes
+	refreshCatalog(false)
+		.then((aliveModels) => {
+			if (aliveModels.length > 0) {
+				setAliveCatalog(aliveModels);
+				pi.registerProvider(
+					"freeflow",
+					buildProviderConfig(aliveModels, actualPort),
+				);
+				logInfo(
+					`Catalog refreshed: ${aliveModels.length} models verified active`,
+				);
+			}
+		})
+		.catch((err) => {
+			logWarn("Background catalog refresh failed; retaining static catalog", {
+				error: String(err),
+			});
+		});
+
+	// 5. Register slash command
+	const commandSpec = createCommandSpec(pi, (updatedModels) => {
+		pi.registerProvider(
+			"freeflow",
+			buildProviderConfig(updatedModels, actualPort),
+		);
+	});
+	pi.registerCommand("freeflow", commandSpec);
+
+	// 6. Lifecycle Listeners
+	pi.on?.("session_start", async (_event, ctx: ExtensionContext) => {
+		const freshRelayState = resolveRelayState();
+		setActiveRelayState(freshRelayState, false);
+		setStatusUi(ctx.ui);
+
+		let provider: string | undefined;
+		let modelId: string | undefined;
+		if (ctx && typeof ctx === "object" && "model" in ctx && ctx.model && typeof ctx.model === "object") {
+			const m = ctx.model;
+			if ("provider" in m && typeof m.provider === "string") {
+				provider = m.provider;
+			}
+			if ("id" in m && typeof m.id === "string") {
+				modelId = m.id;
+			}
+		}
+		const isFreeFlow =
+			provider === "freeflow" ||
+			Boolean(modelId && getAliveCatalog().some((m) => m.id === modelId));
+
+		if (isFreeFlow) {
+			updateStatusBar(ctx.ui);
+		} else {
+			ctx.ui?.setStatus?.("freeflow", undefined);
+		}
+	});
+
+	pi.on?.("model_select", async (event, ctx: ExtensionContext) => {
+		setStatusUi(ctx.ui);
+		let provider: string | undefined;
+		let modelId: string | undefined;
+		if (event && typeof event === "object" && "model" in event && event.model && typeof event.model === "object") {
+			const m = event.model;
+			if ("provider" in m && typeof m.provider === "string") {
+				provider = m.provider;
+			}
+			if ("id" in m && typeof m.id === "string") {
+				modelId = m.id;
+			}
+		}
+		const isFreeFlow =
+			provider === "freeflow" ||
+			Boolean(modelId && getAliveCatalog().some((m) => m.id === modelId));
+
+		if (isFreeFlow) {
+			updateStatusBar(ctx.ui);
+		} else {
+			ctx.ui?.setStatus?.("freeflow", undefined);
+		}
+	});
+
+	pi.on?.("session_shutdown", () => {
+		if (server) {
+			logInfo("shutting down proxy daemon...");
+			server.close();
+			server = null;
+			resetRateLimits();
+			logInfo("shutdown complete");
+		}
+	});
+}

package/src/logger.ts

@@ -0,0 +1,327 @@
+/**
+ * Structured, leveled, rotating, request-aware logger for pi-freeflow
+ */
+
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+	DEBUG_STATE_FILE,
+	LOG_FILE,
+	LOG_MAX_BYTES,
+	LOG_MAX_FILES,
+} from "./config.ts";
+import type { DebugState, LogLevel } from "./types.ts";
+
+export const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+	audit: 4,
+};
+
+let cachedDebugState: DebugState | null | undefined = undefined;
+let cachedDebugMtime = 0;
+let cachedDebugAt = 0;
+
+/**
+ * Load persisted debug state from disk with a 1-second in-memory mtime cache.
+ */
+export function loadDebugState(): DebugState | null {
+	const now = Date.now();
+	if (cachedDebugState !== undefined && now - cachedDebugAt < 1000) {
+		return cachedDebugState;
+	}
+
+	try {
+		if (!fs.existsSync(DEBUG_STATE_FILE)) {
+			cachedDebugState = null;
+			cachedDebugAt = now;
+			return null;
+		}
+
+		const stat = fs.statSync(DEBUG_STATE_FILE);
+		if (stat.mtimeMs === cachedDebugMtime && cachedDebugState !== undefined) {
+			cachedDebugAt = now;
+			return cachedDebugState;
+		}
+
+		const raw = fs.readFileSync(DEBUG_STATE_FILE, "utf8");
+		const parsed = JSON.parse(raw) as DebugState;
+		if (typeof parsed?.debug === "boolean") {
+			cachedDebugState = parsed;
+			cachedDebugMtime = stat.mtimeMs;
+			cachedDebugAt = now;
+			return parsed;
+		}
+	} catch {
+		// Non-fatal if parsing or reading fails
+	}
+
+	cachedDebugState = null;
+	cachedDebugAt = now;
+	return null;
+}
+
+/**
+ * Atomically persist debug state to disk.
+ */
+export function saveDebugState(s: DebugState): void {
+	try {
+		const dir = path.dirname(DEBUG_STATE_FILE);
+		if (!fs.existsSync(dir)) {
+			fs.mkdirSync(dir, { recursive: true });
+		}
+		const tmp = `${DEBUG_STATE_FILE}.${randomUUID()}.tmp`;
+		fs.writeFileSync(tmp, JSON.stringify(s, null, 2), "utf8");
+		fs.renameSync(tmp, DEBUG_STATE_FILE);
+
+		try {
+			const stat = fs.statSync(DEBUG_STATE_FILE);
+			cachedDebugState = s;
+			cachedDebugMtime = stat.mtimeMs;
+			cachedDebugAt = Date.now();
+		} catch {
+			cachedDebugState = s;
+			cachedDebugAt = Date.now();
+		}
+	} catch (err) {
+		// Avoid recursive logger calls on save failure
+	}
+}
+
+/**
+ * Calculate the active minimum log level threshold based on state and env.
+ */
+export function getMinLogLevel(): number {
+	const dbg = loadDebugState();
+	if (dbg?.debug) {
+		return LOG_LEVEL_ORDER.debug;
+	}
+	if (dbg?.level && dbg.level in LOG_LEVEL_ORDER) {
+		return LOG_LEVEL_ORDER[dbg.level];
+	}
+
+	const raw = (process.env.FREEFLOW_LOG_LEVEL || "info").toLowerCase();
+
+	if (raw in LOG_LEVEL_ORDER) {
+		return LOG_LEVEL_ORDER[raw as LogLevel];
+	}
+
+	const isEnvDebug =
+		process.env.FREEFLOW_DEBUG === "1" ||
+		process.env.FREEFLOW_DEBUG === "true";
+
+	if (isEnvDebug) {
+		return LOG_LEVEL_ORDER.debug;
+	}
+
+	return LOG_LEVEL_ORDER.info;
+}
+
+export function shouldLog(level: LogLevel): boolean {
+	return LOG_LEVEL_ORDER[level] >= getMinLogLevel();
+}
+
+export function isDebugEnabled(): boolean {
+	return LOG_LEVEL_ORDER.debug >= getMinLogLevel();
+}
+
+/**
+ * Rotate log files if current log file size exceeds LOG_MAX_BYTES.
+ * Rotates: log -> log.1 -> log.2 -> log.3 ... up to LOG_MAX_FILES.
+ */
+export function rotateLogsIfNeeded(targetFile: string = LOG_FILE): void {
+	try {
+		if (!fs.existsSync(targetFile)) return;
+		const stat = fs.statSync(targetFile);
+		if (stat.size <= LOG_MAX_BYTES) return;
+
+		for (let i = LOG_MAX_FILES; i >= 1; i--) {
+			const src = i === 1 ? targetFile : `${targetFile}.${i - 1}`;
+			const dst = `${targetFile}.${i}`;
+			try {
+				if (fs.existsSync(src)) {
+					if (i === LOG_MAX_FILES && fs.existsSync(dst)) {
+						fs.unlinkSync(dst);
+					} else if (fs.existsSync(dst)) {
+						fs.unlinkSync(dst);
+					}
+					fs.renameSync(src, dst);
+				}
+			} catch {
+				// Ignore rotation step error and continue
+			}
+		}
+	} catch {
+		// Ignore rotation errors
+	}
+}
+
+/**
+ * Safely format metadata object and optional requestId for log output.
+ */
+export function formatLogMeta(
+	meta?: Record<string, unknown>,
+	reqId?: string,
+): string {
+	const parts: string[] = [];
+	if (reqId) {
+		parts.push(`req=${reqId}`);
+	}
+
+	if (meta && Object.keys(meta).length > 0) {
+		const safe: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(meta)) {
+			if (typeof v === "string" && v.length > 800) {
+				safe[k] = `${v.slice(0, 800)}…(${v.length})`;
+			} else if (v instanceof Error) {
+				safe[k] = {
+					name: v.name,
+					message: v.message,
+					stack: v.stack?.split("\n").slice(0, 3).join(" | "),
+				};
+			} else {
+				safe[k] = v;
+			}
+		}
+		parts.push(JSON.stringify(safe));
+	}
+
+	return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+}
+
+/**
+ * Write a structured log entry to disk if level passes threshold.
+ */
+export function log(
+	level: LogLevel,
+	message: string,
+	meta?: Record<string, unknown>,
+	reqId?: string,
+): void {
+	if (!shouldLog(level)) return;
+
+	try {
+		const ts = new Date().toISOString();
+		const reqTag = reqId ? ` [${reqId}]` : "";
+		const line = `[${ts}] [${level.toUpperCase()}]${reqTag} ${message}${formatLogMeta(meta)}\n`;
+
+		rotateLogsIfNeeded(LOG_FILE);
+
+		const dir = path.dirname(LOG_FILE);
+		if (!fs.existsSync(dir)) {
+			fs.mkdirSync(dir, { recursive: true });
+		}
+		fs.appendFileSync(LOG_FILE, line, "utf8");
+	} catch {
+		// Fallback silent failure
+	}
+}
+
+export function logDebug(
+	message: string,
+	meta?: Record<string, unknown>,
+	reqId?: string,
+): void {
+	log("debug", message, meta, reqId);
+}
+
+export function logInfo(
+	message: string,
+	meta?: Record<string, unknown>,
+	reqId?: string,
+): void {
+	log("info", message, meta, reqId);
+}
+
+export function logWarn(
+	message: string,
+	meta?: Record<string, unknown>,
+	reqId?: string,
+): void {
+	log("warn", message, meta, reqId);
+}
+
+export function logError(
+	message: string,
+	meta?: Record<string, unknown>,
+	reqId?: string,
+): void {
+	log("error", message, meta, reqId);
+}
+
+export function logAudit(
+	message: string,
+	meta?: Record<string, unknown>,
+	reqId?: string,
+): void {
+	log("audit", message, meta, reqId);
+}
+
+export interface ReadRecentLogsResult {
+	lines: string[];
+	totalMatched: number;
+	totalLines: number;
+	logFile: string;
+}
+
+/**
+ * Read recent log entries from log file and its rotated archives.
+ */
+export function readRecentLogs(
+	filterLevel?: LogLevel | null,
+	filterReqId?: string | null,
+	count = 25,
+): ReadRecentLogsResult {
+	const files: string[] = [
+		LOG_FILE,
+		`${LOG_FILE}.1`,
+		`${LOG_FILE}.2`,
+		`${LOG_FILE}.3`,
+	].filter((f) => fs.existsSync(f));
+
+	if (files.length === 0) {
+		return {
+			lines: [],
+			totalMatched: 0,
+			totalLines: 0,
+			logFile: LOG_FILE,
+		};
+	}
+
+	let allLines: string[] = [];
+	for (const f of files) {
+		try {
+			const content = fs.readFileSync(f, "utf8");
+			const lines = content.trim().split("\n").filter(Boolean);
+			allLines = lines.concat(allLines);
+		} catch {
+			// Skip unreadable rotated files
+		}
+	}
+
+	let filtered = allLines;
+	if (filterLevel) {
+		const levelTag = `[${filterLevel.toUpperCase()}]`;
+		filtered = filtered.filter((l) => l.includes(levelTag));
+	}
+
+	if (filterReqId) {
+		const cleanedReqId = filterReqId.replace(/^req=/, "");
+		filtered = filtered.filter(
+			(l) => l.includes(cleanedReqId) || l.includes(`[${cleanedReqId}]`),
+		);
+	}
+
+	const clampedCount = Math.min(200, Math.max(1, count));
+	const resultLines = filtered.slice(-clampedCount);
+
+	return {
+		lines: resultLines,
+		totalMatched: filtered.length,
+		totalLines: allLines.length,
+		logFile: LOG_FILE,
+	};
+}