pi-freeflow 1.1.7 → 1.1.9

package/extensions/index.ts

@@ -10,6 +10,7 @@ import https from "node:https";
 import { homedir } from "node:os";
 import path from "node:path";
 import { Readable } from "node:stream";
+import type { ReadableStream as WebReadableStream } from "node:stream/web";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 
@@ -174,8 +175,11 @@ let aliveCatalog: RegisteredModel[] = [];
 async function relayFetch(
 	url: string,
 	opts: RequestInit = {},
+	reqId?: string,
 ): Promise<Response> {
+	const rid = reqId || randomUUID().slice(0, 8);
 	if (!relayState.enabled) {
+		log("debug", `relayFetch: direct (relay disabled) -> ${url}`, undefined, rid);
 		return fetch(url, opts);
 	}
 
@@ -193,7 +197,22 @@ async function relayFetch(
 				? (opts.body.length / 1024).toFixed(1)
 				: "0";
 
-	log("info", `request starting (${bodySizeKB}KB payload) -> ${url}`);
+	log("info", `request starting (${bodySizeKB}KB payload) -> ${url}`, undefined, rid);
+	if (isDebugEnabled()) {
+		try {
+			const bodyPreview = typeof opts.body === "string" ? opts.body.slice(0, 1200) : "";
+			const modelMatch = bodyPreview.match(/"model"\s*:\s*"([^"]+)"/);
+			const streamMatch = bodyPreview.match(/"stream"\s*:\s*(true|false)/);
+			log("debug", `request detail`, {
+				model: modelMatch?.[1],
+				stream: streamMatch?.[1],
+				sizeKB: bodySizeKB,
+				relayTarget,
+				relayPath,
+				candidates: candidates.length,
+			}, rid);
+		} catch {}
+	}
 
 	for (let i = 0; i < candidates.length; i++) {
 		const targetUrl = candidates[i];
@@ -207,6 +226,7 @@ async function relayFetch(
 			headers.set("x-relay-target", relayTarget);
 			headers.set("x-relay-path", relayPath);
 			headers.set("host", targetHost);
+			headers.set("x-request-id", rid);
 			const signal = opts.signal || AbortSignal.timeout(300_000);
 			const res = await fetch(targetUrl, { ...opts, headers, signal });
 			const elapsed = ((Date.now() - attemptStart) / 1000).toFixed(1);
@@ -218,6 +238,7 @@ async function relayFetch(
 					"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 },
+					rid,
 				);
 				break;
 			}
@@ -228,6 +249,7 @@ async function relayFetch(
 					"warn",
 					`relay ${targetUrl} returned HTTP ${res.status} in ${elapsed}s — rolling to next relay`,
 					{ upstream: url, status: res.status },
+					rid,
 				);
 				continue;
 			}
@@ -237,12 +259,19 @@ async function relayFetch(
 			if (relayState.url !== targetUrl) {
 				log("info", `active relay auto-switched to ${targetUrl}`, {
 					previous: relayState.url,
-				});
+				}, rid);
 				relayState.url = targetUrl;
 				saveRelayState(relayState);
 			}
 
-			log("info", `relay ${targetUrl} succeeded (HTTP ${res.status} in ${elapsed}s)`);
+			log("info", `relay ${targetUrl} succeeded (HTTP ${res.status} in ${elapsed}s)`, undefined, rid);
+			if (isDebugEnabled()) {
+				log("debug", `relay headers`, {
+					status: res.status,
+					contentType: res.headers.get("content-type"),
+					via: res.headers.get("via") || res.headers.get("x-vercel-id") || "direct",
+				}, rid);
+			}
 
 			// Update TUI status
 			const label = shortRelayLabel(targetUrl);
@@ -261,6 +290,7 @@ async function relayFetch(
 				"warn",
 				`relay ${targetUrl} fetch error in ${elapsed}s — rolling to next relay`,
 				{ upstream: url, error: String(err) },
+				rid,
 			);
 			continue;
 		}
@@ -272,21 +302,22 @@ async function relayFetch(
 		log("warn", "relays bypassed/exhausted — attempting direct fetch to upstream", {
 			upstream: url,
 			sizeKB: bodySizeKB,
-		});
+		}, rid);
 		const directHeaders = new Headers(opts.headers);
 		directHeaders.delete("x-relay-target");
 		directHeaders.delete("x-relay-path");
 		directHeaders.set("host", u.host);
+		directHeaders.set("x-request-id", rid);
 		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`);
+		log("info", `direct fetch returned HTTP ${directRes.status} in ${directElapsed}s`, undefined, rid);
 		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),
-		});
+		}, rid);
 		if (lastResponse) return lastResponse;
 		throw directErr || lastError;
 	}
@@ -686,23 +717,153 @@ const STRIP_HEADERS = new Set([
 	"proxy-authorization",
 ]);
 
-// ── Logger ─────────────────────────────────────────────────────────
-type LogLevel = "info" | "warn" | "error" | "audit";
-function log(level: LogLevel, message: string, meta?: Record<string, unknown>) {
+// ── Logger (structured, leveled, rotating, request-aware) ─────────
+// Reference: pi-ai SDK diagnostics (provider streaming + thinking deltas)
+//   - api/openai-completions.js: thinkingFormat branches + reasoning_effort mapping
+//   - api/openai-responses-shared.js: reasoning block handling for Responses API
+//   - api/anthropic-messages.js: thinking/thinking_delta + signature handling
+// This logger mirrors that trace plane for offline audit without TUI noise.
+type LogLevel = "debug" | "info" | "warn" | "error" | "audit";
+const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+	audit: 4,
+};
+const LOG_MAX_BYTES = 5 * 1024 * 1024;
+const LOG_MAX_FILES = 3;
+const DEBUG_STATE_FILE = path.join(homedir(), ".pi", "agent", "pi-freeflow-debug.json");
+interface DebugState { debug: boolean; level?: LogLevel }
+let cachedDebugState: DebugState | null | undefined = undefined;
+let cachedDebugMtime = 0;
+let cachedDebugAt = 0;
+function loadDebugState(): DebugState | null {
+	const now = Date.now();
+	// cache for 1s to avoid per-chunk FS hit in hot pipe path
+	if (cachedDebugState !== undefined && now - cachedDebugAt < 1000) {
+		return cachedDebugState;
+	}
 	try {
-		const ts = new Date().toISOString();
-		const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
-		const line = `[${ts}] [${level.toUpperCase()}] ${message}${metaStr}\n`;
+		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 d = JSON.parse(raw) as DebugState;
+		if (typeof d.debug === "boolean") {
+			cachedDebugState = d;
+			cachedDebugMtime = stat.mtimeMs;
+			cachedDebugAt = now;
+			return d;
+		}
+	} catch {}
+	cachedDebugState = null;
+	cachedDebugAt = now;
+	return null;
+}
+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);
+		// update cache
 		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);
+			const stat = fs.statSync(DEBUG_STATE_FILE);
+			cachedDebugState = s;
+			cachedDebugMtime = stat.mtimeMs;
+			cachedDebugAt = Date.now();
+		} catch {
+			cachedDebugState = s;
+			cachedDebugAt = Date.now();
+		}
+	} catch {}
+}
+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 ||
+		process.env.BANSOS_LOG_LEVEL ||
+		"info"
+	).toLowerCase();
+	if (raw in LOG_LEVEL_ORDER) return LOG_LEVEL_ORDER[raw as LogLevel];
+	if (process.env.FREEFLOW_DEBUG === "1" || process.env.FREEFLOW_DEBUG === "true") {
+		return LOG_LEVEL_ORDER.debug;
+	}
+	return LOG_LEVEL_ORDER.info;
+}
+function shouldLog(level: LogLevel): boolean {
+	return LOG_LEVEL_ORDER[level] >= getMinLogLevel();
+}
+function isDebugEnabled(): boolean {
+	return LOG_LEVEL_ORDER.debug >= getMinLogLevel();
+}
+function rotateLogsIfNeeded(): void {
+	try {
+		if (!fs.existsSync(LOG_FILE)) return;
+		if (fs.statSync(LOG_FILE).size <= LOG_MAX_BYTES) return;
+		for (let i = LOG_MAX_FILES - 1; i >= 1; i--) {
+			const src = i === 1 ? LOG_FILE : `${LOG_FILE}.${i - 1}`;
+			const dst = `${LOG_FILE}.${i}`;
+			try {
+				if (fs.existsSync(src)) {
+					if (fs.existsSync(dst)) fs.unlinkSync(dst);
+					fs.renameSync(src, dst);
+				}
+			} catch {}
+		}
+	} catch {}
+}
+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 {
+				safe[k] = v;
 			}
-		} catch {}
+		}
+		parts.push(JSON.stringify(safe));
+	}
+	return parts.length ? ` ${parts.join(" ")}` : "";
+}
+function log(
+	level: LogLevel,
+	message: string,
+	meta?: Record<string, unknown>,
+	reqId?: string,
+): void {
+	if (!shouldLog(level)) return;
+	try {
+		const ts = new Date().toISOString();
+		const line = `[${ts}] [${level.toUpperCase()}]${reqId ? ` [${reqId}]` : ""} ${message}${formatLogMeta(meta, undefined)}\n`;
+		rotateLogsIfNeeded();
 		fs.appendFileSync(LOG_FILE, line, "utf8");
 	} catch {}
 }
+function logDebug(
+	message: string,
+	meta?: Record<string, unknown>,
+	reqId?: string,
+): void {
+	log("debug", message, meta, reqId);
+}
 
 // ── Rate Limiter ───────────────────────────────────────────────────
 // Kilo documents 200 free requests/hour/IP. OpenCode owns its own daily quota;
@@ -984,8 +1145,24 @@ function normalizeRequestBody(
 	body: Record<string, unknown>,
 	isRelay = false,
 	isKilo = false,
+	reqId?: string,
 ): Record<string, unknown> {
-	// 1. Tool choice & empty tools normalization
+	const DBG = isDebugEnabled();
+	const modelId = typeof body.model === "string" ? body.model : "";
+	const modelDef = MODEL_MAP.get(modelId);
+	const isResponsesApi = modelId === "muse-spark-1.2-contributor-free";
+
+	if (DBG) {
+		log("debug", `normalize: incoming model=${modelId} kilo=${isKilo} relay=${isRelay}`, {
+			reasoning_effort: body.reasoning_effort,
+			reasoning: body.reasoning,
+			thinking: (body as Record<string, unknown>).thinking,
+			tool_choice: body.tool_choice,
+			toolsLen: Array.isArray(body.tools) ? body.tools.length : undefined,
+		}, reqId);
+	}
+
+	// 1. Tool choice & empty tools normalization (pi-ai compat: opencode only supports auto)
 	if (Array.isArray(body.tools) && body.tools.length === 0) {
 		delete body.tools;
 		delete body.tool_choice;
@@ -994,26 +1171,57 @@ function normalizeRequestBody(
 		delete body.tool_choice;
 		delete body.tools;
 	} else if (!isKilo && body.tool_choice && body.tool_choice !== "auto") {
-		// OpenCode Zen only supports "auto" or undefined
 		body.tool_choice = "auto";
 	}
 
-	// 2. Reasoning normalization
-	const modelId = typeof body.model === "string" ? body.model : "";
-	const isResponsesApi = modelId === "muse-spark-1.2-contributor-free";
+	// 1b. Anthropic thinking -> OpenAI reasoning_effort auto-translate
+	// Pi sends anthropic `thinking: {type:"enabled",budget_tokens}` when provider is anthropic.
+	// Our proxy is always openai-completions/responses upstream, so translate.
+	// Ref: pi-ai api/anthropic-messages.js (thinking.type adaptive/enabled/disabled) -> api/openai-completions.js (reasoning_effort)
+	const thinkingRaw = (body as Record<string, unknown>).thinking;
+	if (thinkingRaw && typeof thinkingRaw === "object") {
+		const th = thinkingRaw as Record<string, unknown>;
+		if (th.type === "disabled") {
+			delete (body as Record<string, unknown>).thinking;
+			// Mark as off so downstream reasoning mapping can clear effort
+			if (!body.reasoning_effort && !body.reasoning) {
+				body.reasoning_effort = "off";
+			}
+		} else if (th.type === "enabled" || th.type === "adaptive") {
+			delete (body as Record<string, unknown>).thinking;
+			// Preserve budget as hint if no explicit effort set
+			if (!body.reasoning_effort && typeof th.budget_tokens === "number") {
+				const budget = th.budget_tokens as number;
+				if (budget >= 8000) body.reasoning_effort = "xhigh";
+				else if (budget >= 4000) body.reasoning_effort = "high";
+				else if (budget >= 2000) body.reasoning_effort = "medium";
+				else body.reasoning_effort = "low";
+			}
+		}
+	}
+
+	// 2. Reasoning normalization — per-model thinkingLevelMap aware
+	// Ref: pi-ai api/openai-completions.js (compat.thinkingFormat branches) + api/openai-responses-shared.js
+	const mapEffort = (rawEffort: string): string | null | undefined => {
+		const key = rawEffort.toLowerCase() as keyof NonNullable<ModelDef["thinkingLevelMap"]>;
+		if (modelDef?.thinkingLevelMap && key in modelDef.thinkingLevelMap) {
+			return modelDef.thinkingLevelMap[key] as string | null;
+		}
+		if (rawEffort === "xhigh" || rawEffort === "max") {
+			return isResponsesApi ? "xhigh" : (modelId === "x-preview-f-free" ? "max" : "xhigh");
+		}
+		if (rawEffort === "high" || rawEffort === "medium") return "high";
+		if (rawEffort === "minimal") return "minimal";
+		if (rawEffort === "none" || rawEffort === "off") return null;
+		return "low";
+	};
 
 	if (typeof body.reasoning_effort === "string") {
-		const re = body.reasoning_effort.toLowerCase();
-		if (re === "xhigh" || re === "max") {
-			body.reasoning_effort = isResponsesApi ? "xhigh" : (modelId === "x-preview-f-free" ? "max" : "xhigh");
-		} else if (re === "high" || re === "medium") {
-			body.reasoning_effort = "high";
-		} else if (re === "minimal") {
-			body.reasoning_effort = "minimal";
-		} else if (re === "none" || re === "off") {
+		const mapped = mapEffort(body.reasoning_effort);
+		if (mapped === null || mapped === undefined) {
 			delete body.reasoning_effort;
 		} else {
-			body.reasoning_effort = "low";
+			body.reasoning_effort = mapped;
 		}
 	}
 	if (body.reasoning && typeof body.reasoning === "object") {
@@ -1021,21 +1229,17 @@ function normalizeRequestBody(
 		if (r.effort === "none" || r.effort === "off") {
 			delete r.effort;
 		} else if (typeof r.effort === "string") {
-			const re = r.effort.toLowerCase();
-			if (re === "xhigh" || re === "max") {
-				r.effort = "xhigh"; // OpenCode Zen Responses API strictly requires "xhigh"
-			} else if (re === "high" || re === "medium") {
-				r.effort = "high";
-			} else if (re === "minimal") {
-				r.effort = "minimal";
+			const mapped = mapEffort(r.effort);
+			if (mapped === null || mapped === undefined) {
+				delete r.effort;
 			} else {
-				r.effort = "low";
+				r.effort = mapped;
 			}
 		}
+		if (isResponsesApi && r.effort === "max") r.effort = "xhigh";
 	}
 
 	// 3. Max & Min tokens clamping (model-specific clamp + Vercel relay clamp)
-	const modelDef = MODEL_MAP.get(modelId);
 	const modelMax = modelDef?.maxTokens ?? RELAY_MAX_TOKENS;
 	const clampTokens = (val: number): number => {
 		let clamped = val;
@@ -1055,16 +1259,47 @@ function normalizeRequestBody(
 		body.max_output_tokens = clampTokens(body.max_output_tokens);
 	}
 
+	if (DBG) {
+		log("debug", `normalize: outgoing model=${modelId}`, {
+			reasoning_effort: body.reasoning_effort,
+			reasoning: body.reasoning,
+			max_tokens: body.max_tokens,
+			max_output_tokens: body.max_output_tokens,
+		}, reqId);
+	}
+
 	return body;
 }
 
 // ponytail: shared stream pipe — upstream abort/timeout must end response,
 // not become an uncaught exception that crashes pi.
+// Adds lightweight thinking-tag sniffing for debug audit (no payload mutation).
+// Ref: pi-ai api/openai-completions.js (thinkingDelta) + api/openai-responses-shared.js (reasoning)
 function pipeUpstreamStream(
 	nodeStream: Readable,
 	res: http.ServerResponse,
 	req: http.IncomingMessage,
+	reqId?: string,
 ): void {
+	const rid = reqId || randomUUID().slice(0, 8);
+	let totalChunks = 0;
+	let totalBytes = 0;
+	let thinkingChunks = 0;
+	let thinkingBytes = 0;
+	let firstChunkAt: number | null = null;
+	const startAt = Date.now();
+	const sniffThinking = (chunk: Buffer | string): boolean => {
+		const s = typeof chunk === "string" ? chunk : chunk.toString("utf8", 0, Math.min(chunk.length, 4000));
+		return (
+			s.includes("reasoning") ||
+			s.includes("thinking") ||
+			s.includes("<think>") ||
+			s.includes("reasoning_content") ||
+			s.includes("\"type\":\"thinking\"") ||
+			s.includes("thinking_delta")
+		);
+	};
+
 	try {
 		if (typeof res.flushHeaders === "function") {
 			res.flushHeaders();
@@ -1073,15 +1308,29 @@ function pipeUpstreamStream(
 
 	nodeStream.on("data", (chunk: Buffer | string) => {
 		try {
-			res.write(chunk);
-			if (typeof (res as any).flush === "function") {
-				(res as any).flush();
+			if (firstChunkAt === null) {
+				firstChunkAt = Date.now();
+				const ttfb = firstChunkAt - startAt;
+				log("debug", `stream first chunk in ${ttfb}ms`, undefined, rid);
 			}
+			totalChunks++;
+			totalBytes += typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length;
+			if (sniffThinking(chunk)) {
+				thinkingChunks++;
+				thinkingBytes += typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length;
+				if (isDebugEnabled() && thinkingChunks <= 3) {
+					const preview = typeof chunk === "string" ? chunk.slice(0, 600) : chunk.toString("utf8", 0, 600);
+					log("debug", `thinking chunk #${thinkingChunks}`, { preview: preview.slice(0, 400) }, rid);
+				}
+			}
+			res.write(chunk);
+			const maybeFlush = res as unknown as { flush?: () => void };
+			if (typeof maybeFlush.flush === "function") maybeFlush.flush();
 		} catch {}
 	});
 
 	nodeStream.on("error", (e: unknown) => {
-		log("error", "upstream stream error", { error: String(e) });
+		log("error", "upstream stream error", { error: String(e), totalChunks, thinkingChunks }, rid);
 		try {
 			if (!res.headersSent) {
 				res.writeHead(502, { "content-type": "application/json" });
@@ -1092,6 +1341,12 @@ function pipeUpstreamStream(
 		} catch {}
 	});
 	nodeStream.on("end", () => {
+		const elapsed = ((Date.now() - startAt) / 1000).toFixed(1);
+		if (thinkingChunks > 0) {
+			log("info", `stream ended in ${elapsed}s — ${totalChunks} chunks (${(totalBytes/1024).toFixed(1)}KB), thinking: ${thinkingChunks} chunks (${(thinkingBytes/1024).toFixed(1)}KB)`, undefined, rid);
+		} else if (isDebugEnabled()) {
+			log("debug", `stream ended in ${elapsed}s — ${totalChunks} chunks (${(totalBytes/1024).toFixed(1)}KB), no thinking detected`, undefined, rid);
+		}
 		try {
 			if (!res.writableEnded) res.end();
 		} catch {}
@@ -1102,6 +1357,7 @@ function pipeUpstreamStream(
 		} catch {}
 	});
 	req.on("aborted", () => {
+		log("warn", "client aborted — destroying upstream", { totalChunks }, rid);
 		if (!nodeStream.destroyed) nodeStream.destroy();
 	});
 	req.on("close", () => {
@@ -1123,7 +1379,10 @@ function startProxy(
 
 	const server = http.createServer((req, res) => {
 		const clientIP = getClientIP(req);
-
+		const reqId = randomUUID().slice(0, 8);
+		if (isDebugEnabled()) {
+			log("debug", `incoming ${req.method} ${req.url} from ${clientIP}`, { ip: clientIP, method: req.method, url: req.url }, reqId);
+		}
 		if (!ALLOWED_METHODS.has(req.method ?? "")) {
 			res.writeHead(405, { "content-type": "application/json" });
 			res.end(JSON.stringify({ error: "method not allowed" }));
@@ -1173,7 +1432,7 @@ function startProxy(
 		// Read body to detect model for routing
 		const bodyChunks: Buffer[] = [];
 		req.on("error", (err) => {
-			log("warn", "client request error during body buffering", { error: String(err) });
+			log("warn", "client request error during body buffering", { error: String(err) }, reqId);
 			if (!res.headersSent) res.writeHead(400, { "content-type": "application/json" });
 			res.end(JSON.stringify({ error: "bad request" }));
 		});
@@ -1194,13 +1453,17 @@ function startProxy(
 			} catch {}
 
 			const upstream: Upstream = isKilo ? "kilo" : "opencode";
+			if (!checkRateLimit(clientIP, upstream)) {
+				log("warn", `rate limit hit for ${upstream} from ${clientIP}`, { ip: clientIP, upstream }, reqId);
+				res.writeHead(429, { "content-type": "application/json" });
+				res.end(JSON.stringify({ error: "rate limit exceeded" }));
+				return;
+			}
 
 			try {
 				if (isKilo && parsedBody) {
-					// KiloCode gateway routing (free models are keyless)
-					const isStream = parsedBody.stream === true;
 					const kiloBodyObj = structuredClone(parsedBody);
-					normalizeRequestBody(kiloBodyObj, true, isKilo);
+					normalizeRequestBody(kiloBodyObj, true, isKilo, reqId);
 					const response = await relayFetch(KILO_CHAT_URL, {
 						method: "POST",
 						headers: {
@@ -1209,7 +1472,7 @@ function startProxy(
 						},
 						body: JSON.stringify(kiloBodyObj),
 						signal: AbortSignal.timeout(300_000),
-					});
+					}, reqId);
 					if (isStream && response.ok && response.body) {
 						const ct =
 							response.headers.get("content-type") || "text/event-stream";
@@ -1221,10 +1484,11 @@ function startProxy(
 						});
 						pipeUpstreamStream(
 							Readable.fromWeb(
-								response.body as unknown as import("stream/web").ReadableStream,
+								response.body as unknown as WebReadableStream,
 							),
 							res,
 							req,
+							reqId,
 						);
 					} else {
 						const data = await response.text();
@@ -1244,12 +1508,9 @@ function startProxy(
 							activeHost,
 						);
 						try {
-							let relayBody = bodyChunks.length
-								? Buffer.concat(bodyChunks)
-								: undefined;
 							if (relayBody && parsedBody) {
 								const relayBodyObj = structuredClone(parsedBody);
-								normalizeRequestBody(relayBodyObj, true, isKilo);
+								normalizeRequestBody(relayBodyObj, true, isKilo, reqId);
 								relayBody = Buffer.from(JSON.stringify(relayBodyObj));
 							}
 							const response = await relayFetch(fullUrl, {
@@ -1257,7 +1518,7 @@ function startProxy(
 								headers: relayHeaders,
 								body: relayBody,
 								signal: AbortSignal.timeout(300_000),
-							});
+							}, reqId);
 							const ct =
 								response.headers.get("content-type") || "application/json";
 							if (response.ok && response.body) {
@@ -1271,10 +1532,11 @@ function startProxy(
 								});
 								pipeUpstreamStream(
 									Readable.fromWeb(
-										response.body as unknown as import("stream/web").ReadableStream,
+										response.body as unknown as WebReadableStream,
 									),
 									res,
 									req,
+									reqId,
 								);
 							} else {
 								const data = await response.text();
@@ -1286,19 +1548,23 @@ function startProxy(
 							return; // relay handled the response
 						} catch (e) {
 							log("warn", "opencode relay failed, falling back to direct", {
- 								error: String(e),
- 							});
+								error: String(e),
+							}, reqId);
  							if (res.headersSent) return; // can't recover mid-stream
  						}
  					}
  					// direct path (existing, untouched)
- 					let directBody = Buffer.concat(bodyChunks);
- 					if (parsedBody) {
- 						const directBodyObj = structuredClone(parsedBody);
- 						normalizeRequestBody(directBodyObj, false, isKilo);
- 						directBody = Buffer.from(JSON.stringify(directBodyObj));
- 					}
- 					const fwd = sanitizeHeaders(req.headers, target.hostname);
+					// direct path — with debug trace and thinking-aware normalize
+					let directBody = Buffer.concat(bodyChunks);
+					if (parsedBody) {
+						const directBodyObj = structuredClone(parsedBody);
+						normalizeRequestBody(directBodyObj, false, isKilo, reqId);
+						directBody = Buffer.from(JSON.stringify(directBodyObj));
+					}
+					if (isDebugEnabled()) {
+						log("debug", `direct upstream ${target.hostname}${target.pathname} (${directBody.length}B)`, { model: parsedBody?.model, isKilo }, reqId);
+					}
+					const fwd = sanitizeHeaders(req.headers, target.hostname);
  					if (directBody.length > 0) {
  						fwd["content-length"] = String(directBody.byteLength);
  					}
@@ -1323,14 +1589,14 @@ function startProxy(
  							outHeaders["x-content-type-options"] = "nosniff";
  							res.writeHead(upstream.statusCode ?? 502, outHeaders);
  							upstream.on("error", (streamErr) => {
- 								log("error", "upstream stream error in direct proxy", { error: String(streamErr) });
+ 								log("error", "upstream stream error in direct proxy", { error: String(streamErr) }, reqId);
  								if (!res.writableEnded) res.end();
  							});
  							upstream.pipe(res);
  						},
  					);
  					proxy.on("error", (proxyErr) => {
- 						log("error", "proxy socket error", { error: String(proxyErr) });
+ 						log("error", "proxy socket error", { error: String(proxyErr) }, reqId);
  						if (!res.headersSent) {
  							res.writeHead(502, { "content-type": "application/json" });
  							res.end(JSON.stringify({ error: "upstream error" }));
@@ -1355,7 +1621,7 @@ function startProxy(
  					proxy.end(directBody);
  				}
  			} catch (err) {
- 				log("error", "proxy error", { error: String(err) });
+ 				log("error", "proxy error", { error: String(err) }, reqId);
  				if (!res.headersSent)
  					res.writeHead(502, { "content-type": "application/json" });
  				res.end(JSON.stringify({ error: "internal error" }));
@@ -1480,12 +1746,12 @@ export default async function (pi: ExtensionAPI) {
 
 		pi.registerProvider("freeflow", providerConfig);
 	}
-	// ── /bansos command: toggle relay egress live (on|off|status|url [URL]) ───
+	// ── /bansos command: relay + debug + logs ───
 	const commandSpec = {
 		description:
-			"Relay egress: on | off | status | logs | url [URL] | deploy | list | use <URL> | remove <URL> | refresh",
+			"Relay egress: on | off | status | logs [level] [n] | debug on|off|status | url [URL] | deploy | list | use <URL> | remove <URL> | refresh",
 		getArgumentCompletions: (prefix: string) =>
-			["on", "off", "status", "url", "deploy", "list", "use", "remove", "refresh", "models"]
+			["on", "off", "status", "url", "deploy", "list", "use", "remove", "refresh", "models", "logs", "debug", "trace"]
 				.filter((s) => s.startsWith(prefix))
 				.map((s) => ({ value: s, label: s })),
 		handler: async (args: string, ctx) => {
@@ -1623,15 +1889,76 @@ export default async function (pi: ExtensionAPI) {
 				setRelay(true, url, "manual");
 				persist();
 				flash();
-			} else if (sub === "logs" || sub === "log") {
+			} else if (sub === "debug") {
+				const arg = rest.trim().toLowerCase();
+				if (arg === "on" || arg === "enable" || arg === "true") {
+					saveDebugState({ debug: true });
+					ctx.ui.notify("🔍 Debug ON — verbose trace enabled (level=debug). Logs now include request IDs, thinking sniffing, and payload normalize details.", "info");
+				} else if (arg === "off" || arg === "disable" || arg === "false") {
+					saveDebugState({ debug: false });
+					ctx.ui.notify("🔇 Debug OFF — level restored to info. File: " + DEBUG_STATE_FILE, "info");
+				} else if (arg.startsWith("level")) {
+					const lvl = arg.split(/\s+/)[1] as LogLevel | undefined;
+					if (lvl && lvl in LOG_LEVEL_ORDER) {
+						saveDebugState({ debug: false, level: lvl });
+						ctx.ui.notify(`Log level set to ${lvl} (persisted to ${DEBUG_STATE_FILE})`, "info");
+					} else {
+						ctx.ui.notify(`Unknown level: ${lvl} (use debug/info/warn/error)`, "warn");
+					}
+				} else {
+					const st = loadDebugState();
+					const cur = st?.debug ? "debug (ON)" : (st?.level || process.env.FREEFLOW_LOG_LEVEL || "info");
+					ctx.ui.notify(`Debug status: ${cur}\nFile: ${DEBUG_STATE_FILE}\nMinLevel: ${getMinLogLevel()} | isDebug=${isDebugEnabled()}\nUsage: /freeflow debug on|off | /freeflow debug level debug`, "info");
+				}
+			} else if (sub === "logs" || sub === "log" || sub === "trace") {
 				try {
-					if (!fs.existsSync(LOG_FILE)) {
-						ctx.ui.notify("Log file is empty", "info");
+					const rawRest = rest.trim();
+					let filterLevel: LogLevel | null = null;
+					let filterReqId: string | null = null;
+					let count = 25;
+					// trace mode: sub === trace or rest starts with trace/req
+					if (sub === "trace" && rawRest) {
+						filterReqId = rawRest.split(/\s+/)[0];
+					} else if (rawRest) {
+						const tokens = rawRest.split(/\s+/);
+						for (const t of tokens) {
+							const lower = t.toLowerCase();
+							if (lower in LOG_LEVEL_ORDER) filterLevel = lower as LogLevel;
+							else if (/^\d+$/.test(t)) count = Math.min(200, Math.max(5, parseInt(t, 10)));
+							else if (/^[a-f0-9]{6,8}$/i.test(t) || t.startsWith("req=")) filterReqId = t.replace(/^req=/, "");
+							else if (lower === "trace" || lower === "req") continue;
+							else filterReqId = t;
+						}
+					}
+					const files: string[] = [LOG_FILE, `${LOG_FILE}.1`, `${LOG_FILE}.2`].filter((f) => fs.existsSync(f));
+					if (files.length === 0) {
+						ctx.ui.notify("Log file is empty (no logs yet)", "info");
+						return;
+					}
+					let allLines: string[] = [];
+					for (const f of files) {
+						try {
+							const c = fs.readFileSync(f, "utf8");
+							const ls = c.trim().split("\n").filter(Boolean);
+							allLines = ls.concat(allLines);
+						} catch {}
+					}
+					let filtered = allLines;
+					if (filterLevel) {
+						const want = `[${filterLevel.toUpperCase()}]`;
+						filtered = filtered.filter((l) => l.includes(want));
+					}
+					if (filterReqId) {
+						// match [reqId] bracket or req= prefix
+						filtered = filtered.filter((l) => l.includes(filterReqId as string) || l.includes(`[${filterReqId}]`));
+					}
+					const lines = filtered.slice(-count);
+					if (lines.length === 0) {
+						ctx.ui.notify(`No logs matched (level=${filterLevel || "any"} reqId=${filterReqId || "any"} count=${count})`, "warning");
 						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");
+					const header = `pi-freeflow logs (last ${lines.length}/${filtered.length} matched, total ${allLines.length} lines, file: ${LOG_FILE}${filterLevel ? ` level=${filterLevel}` : ""}${filterReqId ? ` req=${filterReqId}` : ""}):`;
+					ctx.ui.notify(`${header}\n\n${lines.join("\n")}`, "info");
 				} catch (e) {
 					ctx.ui.notify(`Could not read log file: ${(e as Error).message}`, "error");
 				}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-freeflow",
 	"type": "module",
-	"version": "1.1.7",
+	"version": "1.1.9",
 	"description": "Personal multi-cloud rolling fallback relay for OpenCode Zen and KiloCode models in OMP/Pi",
 	"keywords": [
 		"pi-package",