pi-freeflow 1.2.0 → 1.3.0

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,
+	};
+}

package/src/models.ts

@@ -0,0 +1,343 @@
+/**
+ * Static model definitions and upstream routing catalogs for pi-freeflow
+ *
+ * Defines the 23 verified free models:
+ * - 9 OpenCode Zen models (2 Responses API + 7 Chat Completions)
+ * - 14 KiloCode Keyless Gateway models (11 OpenRouter format + 3 Standard format)
+ */
+
+import type { ModelDef, Upstream } from "./types.ts";
+
+/**
+ * OpenCode Zen free models verified against the live catalog and inference APIs.
+ * Endpoint: https://opencode.ai/zen/v1
+ */
+export const OPENCODE_MODELS: ModelDef[] = [
+	{
+		id: "deepseek-v4-flash-free",
+		name: "DeepSeek V4 Flash (1M)",
+		reasoning: true,
+		contextWindow: 1_000_000,
+		maxTokens: 384_000,
+		input: ["text"],
+		thinkingLevelMap: {
+			off: null,
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "x-preview-f-free",
+		name: "Ox Alpha (1M)",
+		reasoning: true,
+		contextWindow: 1_048_576,
+		maxTokens: 131_072,
+		input: ["text", "image"],
+		thinkingLevelMap: {
+			off: null,
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "muse-spark-1.2-contributor-free",
+		name: "Muse Spark 1.2 (1M)",
+		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 (1M)",
+		reasoning: true,
+		contextWindow: 1_048_576,
+		maxTokens: 131_072,
+		input: ["text", "image"],
+		thinkingLevelMap: {
+			off: null,
+			minimal: "low",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "high",
+			max: "high",
+		},
+	},
+	{
+		id: "hy3-free",
+		name: "Hy3 (262K)",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 128_000,
+		input: ["text"],
+		thinkingLevelMap: {
+			off: null,
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "nemotron-3-ultra-free",
+		name: "Nemotron 3 Ultra (1M)",
+		reasoning: true,
+		contextWindow: 1_000_000,
+		maxTokens: 128_000,
+		input: ["text"],
+		thinkingLevelMap: {
+			off: null,
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "nemotron-3.5-lightning-free",
+		name: "Nemotron 3.5 Lightning (1M)",
+		reasoning: true,
+		contextWindow: 1_000_000,
+		maxTokens: 262_144,
+		input: ["text"],
+		thinkingLevelMap: {
+			off: null,
+			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,
+		input: ["text"],
+		thinkingLevelMap: {
+			off: null,
+			minimal: "high",
+			low: "high",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+	{
+		id: "laguna-s-2.1-free",
+		name: "Laguna S 2.1 (1M)",
+		reasoning: true,
+		contextWindow: 1_048_576,
+		maxTokens: 131_072,
+		input: ["text"],
+		thinkingLevelMap: {
+			off: null,
+			minimal: "low",
+			low: "low",
+			medium: "high",
+			high: "high",
+			xhigh: "max",
+			max: "max",
+		},
+	},
+];
+
+/**
+ * Backward compatibility alias for OPENCODE_MODELS
+ */
+export const KNOWN_MODELS = OPENCODE_MODELS;
+
+/**
+ * KiloCode Gateway free models (keyless — https://kilo.ai/docs/gateway).
+ * Endpoint: https://api.kilo.ai/api/gateway/chat/completions
+ */
+export const KILO_MODELS: ModelDef[] = [
+	{
+		id: "dots-studio/dots-3-note-preview:free",
+		name: "Dots3-Note Preview (512K)",
+		reasoning: true,
+		contextWindow: 512_000,
+		maxTokens: 512_000,
+		input: ["text", "image"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "stepfun/step-3.7-flash:free",
+		name: "Step 3.7 Flash",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 262_144,
+		input: ["text", "image"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+		name: "Nemotron 3 Nano Omni",
+		reasoning: true,
+		contextWindow: 256_000,
+		maxTokens: 65_536,
+		input: ["text", "image"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "nvidia/nemotron-3-ultra-550b-a55b:free",
+		name: "Nemotron 3 Ultra 550B (1M)",
+		reasoning: true,
+		contextWindow: 1_000_000,
+		maxTokens: 65_536,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "nvidia/nemotron-3.5-lightning:free",
+		name: "Nemotron 3.5 Lightning (Kilo)",
+		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 120B",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 262_144,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "tencent/hy3:free",
+		name: "Tencent Hy3 (Kilo)",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 128_000,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "cohere/north-mini-code:free",
+		name: "North Mini Code",
+		reasoning: true,
+		contextWindow: 256_000,
+		maxTokens: 64_000,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "poolside/laguna-s-2.1:free",
+		name: "Laguna S 2.1 (Kilo)",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 32_768,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "poolside/laguna-xs-2.1:free",
+		name: "Laguna XS 2.1",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 32_768,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "liquid/lfm-2.5-2.6b:free",
+		name: "Liquid LFM 2.5",
+		reasoning: true,
+		contextWindow: 65_536,
+		maxTokens: 8_192,
+		input: ["text"],
+		thinkingFormat: "openrouter",
+	},
+	{
+		id: "kilo-auto/free",
+		name: "Kilo Auto",
+		reasoning: false,
+		contextWindow: 256_000,
+		maxTokens: 10_000,
+		input: ["text"],
+	},
+	{
+		id: "openrouter/free",
+		name: "OpenRouter Auto",
+		reasoning: false,
+		contextWindow: 200_000,
+		maxTokens: 65_536,
+		input: ["text"],
+	},
+	{
+		id: "nvidia/nemotron-3.5-content-safety:free",
+		name: "Nemotron Content Safety",
+		reasoning: false,
+		contextWindow: 128_000,
+		maxTokens: 8_192,
+		input: ["text"],
+	},
+];
+
+/**
+ * Set of all KiloCode model IDs for fast lookup
+ */
+export const KILO_MODEL_IDS = new Set<string>(KILO_MODELS.map((m) => m.id));
+
+/**
+ * Combined list of all 23 static free models
+ */
+export const ALL_MODELS: ModelDef[] = [...OPENCODE_MODELS, ...KILO_MODELS];
+
+/**
+ * Map of model ID -> ModelDef
+ */
+export const MODEL_MAP = new Map<string, ModelDef>(
+	ALL_MODELS.map((m) => [m.id, m]),
+);
+
+/**
+ * Lookup a model definition by ID
+ */
+export function getModelDef(id: string): ModelDef | undefined {
+	return MODEL_MAP.get(id);
+}
+
+/**
+ * Check if a model ID belongs to KiloCode Gateway
+ */
+export function isKiloModel(id: string): boolean {
+	return KILO_MODEL_IDS.has(id);
+}
+
+/**
+ * Determine the upstream provider for a given model ID
+ */
+export function getModelUpstream(id: string): Upstream {
+	return isKiloModel(id) ? "kilo" : "opencode";
+}