pi-freeflow 1.2.0 → 1.3.0

package/src/config.ts

@@ -0,0 +1,145 @@
+/**
+ * Configuration and path resolution for pi-freeflow
+ */
+
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Upstream } from "./types.ts";
+
+// ── Upstream endpoints ──────────────────────────────────────────────
+export const UPSTREAM_OPENCODE = "https://opencode.ai/zen";
+export const KILO_CHAT_URL = "https://api.kilo.ai/api/gateway/chat/completions";
+export const OPENCODE_API_URL = `${UPSTREAM_OPENCODE}/v1`;
+
+// ── Network & Server defaults ───────────────────────────────────────
+export const DEFAULT_PORT = 18080;
+export const HOST = "127.0.0.1";
+export const DEFAULT_HOST = "127.0.0.1";
+
+export function resolvePort(): number {
+	const envPort = process.env.FREEFLOW_PORT;
+	if (envPort) {
+		const parsed = Number(envPort);
+		if (Number.isFinite(parsed) && parsed > 0 && parsed <= 65535) {
+			return parsed;
+		}
+	}
+	return DEFAULT_PORT;
+}
+
+export const PORT = resolvePort();
+
+// ── OpenCode client headers ─────────────────────────────────────────
+export const OPENCODE_USER_AGENT = "opencode/latest/1.14.50/cli";
+export const OPENCODE_CLIENT = "cli";
+export const OPENCODE_PROJECT = "default";
+export const OPENCODE_SESSION = randomUUID();
+
+export 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 and Deployment constants ──────────────────────────────────
+export const DEFAULT_RELAY_URL = "";
+export const VERCEL_API = "https://api.vercel.com";
+export const RELAY_MAX_TOKENS = 131_072;
+
+// ── Catalog & Logging constants ─────────────────────────────────────
+export const CATALOG_CACHE_TTL_MS = 86_400_000; // 24 hours — delegate to host fetchDynamicModels
+export const LOG_MAX_BYTES = 5 * 1024 * 1024; // 5MB
+export const LOG_MAX_FILES = 3;
+
+// ── Rate Limit Maxima ───────────────────────────────────────────────
+export const RATE_LIMIT_MAX: Record<Upstream, number> = {
+	opencode: 200, // public free quota: requests per UTC day per IP
+	kilo: 200, // documented gateway quota: requests per 1-hour window per IP
+};
+
+// ── Whitelists & Security ───────────────────────────────────────────
+export const ALLOWED_PATH_PATTERN = /^\/v1\/[a-zA-Z0-9/_.,\-?&=]*$/;
+export const PATH_TRAVERSAL_PATTERN = /\.\./;
+export const ALLOWED_METHODS = new Set(["GET", "POST", "OPTIONS", "HEAD"]);
+
+export const STRIP_HEADERS = new Set([
+	"authorization",
+	"host",
+	"content-length",
+	"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",
+]);
+
+// ── File Path Resolvers ─────────────────────────────────────────────
+
+export function resolveRelayStatePath(): string {
+	try {
+		return path.join(homedir(), ".pi", "agent", "pi-freeflow-relay-state.json");
+	} catch {
+		return path.join(
+			path.dirname(fileURLToPath(import.meta.url)),
+			"..",
+			".relay-state.json",
+		);
+	}
+}
+
+export 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",
+		);
+	}
+}
+
+export function resolveCatalogCachePath(): string {
+	try {
+		return path.join(
+			homedir(),
+			".pi",
+			"agent",
+			"pi-freeflow-catalog-cache.json",
+		);
+	} catch {
+		return path.join(
+			path.dirname(fileURLToPath(import.meta.url)),
+			"..",
+			".catalog-cache.json",
+		);
+	}
+}
+
+export function resolveDebugStatePath(): string {
+	try {
+		return path.join(homedir(), ".pi", "agent", "pi-freeflow-debug.json");
+	} catch {
+		return path.join(
+			path.dirname(fileURLToPath(import.meta.url)),
+			"..",
+			".debug-state.json",
+		);
+	}
+}
+
+export const RELAY_STATE_FILE = resolveRelayStatePath();
+export const LOG_FILE = resolveLogFilePath();
+export const CATALOG_CACHE_FILE = resolveCatalogCachePath();
+export const DEBUG_STATE_FILE = resolveDebugStatePath();

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,244 @@
+/**
+ * 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 "./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) => {
+		const freshRelayState = resolveRelayState();
+		setActiveRelayState(freshRelayState, false);
+		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");
+		}
+	});
+}