proxitor 0.16.0 → 0.17.0

package/dist/cli.mjs

@@ -7,12 +7,13 @@ import tty, { ReadStream } from "node:tty";
 import { formatWithOptions, isDeepStrictEqual, styleText } from "node:util";
 import * as l$1 from "node:readline";
 import l__default from "node:readline";
-import { existsSync, mkdirSync, readFileSync, readdirSync, unwatchFile, watchFile, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unwatchFile, watchFile, writeFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import { createServer } from "node:net";
 import { STATUS_CODES, createServer as createServer$1 } from "node:http";
 import { Http2ServerRequest, constants } from "node:http2";
 import { Readable } from "node:stream";
+import { readFile, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -16271,6 +16272,20 @@ const ttlSchema = _enum([
 	"omit",
 	"skip"
 ]);
+const OBSERVABILITY_DEFAULTS = {
+	routerMetadata: true,
+	hitThreshold: 80,
+	sideMaxTokens: 4096,
+	sessionMaxEntries: 4096,
+	sessionTtlMs: 6e5
+};
+const observabilityConfigSchema = object({
+	routerMetadata: boolean().default(OBSERVABILITY_DEFAULTS.routerMetadata),
+	hitThreshold: number$1().int().min(0).max(100).default(OBSERVABILITY_DEFAULTS.hitThreshold),
+	sideMaxTokens: number$1().int().positive().default(OBSERVABILITY_DEFAULTS.sideMaxTokens),
+	sessionMaxEntries: number$1().int().positive().default(OBSERVABILITY_DEFAULTS.sessionMaxEntries),
+	sessionTtlMs: number$1().int().positive().default(OBSERVABILITY_DEFAULTS.sessionTtlMs)
+}).default(OBSERVABILITY_DEFAULTS);
 const modelOverrideSchema = object({
 	provider: providerConfigSchema.optional(),
 	headers: record(string$1(), string$1()).optional(),
@@ -16298,6 +16313,7 @@ const proxyConfigSchema = object({
 	rewriteBlockTtl: triStateSchema.default("skip"),
 	sessionId: triStateSchema.default("auto"),
 	normalizeVolatileSystem: boolean().default(false),
+	observability: observabilityConfigSchema,
 	modelOverrides: record(string$1().min(1), modelOverrideSchema).optional()
 }).strict();
 const DEFAULTS = proxyConfigSchema.parse({});
@@ -19554,7 +19570,7 @@ async function runConfigMenu(client) {
 }
 //#endregion
 //#region src/version.ts
-const version = "0.16.0";
+const version = "0.17.0";
 //#endregion
 //#region src/commands/doctor.ts
 const DEFAULT_TIMEOUT_MS = 3e3;
@@ -19898,6 +19914,7 @@ var FileWatchingConfigSource = class {
 	pending = false;
 	watching = false;
 	lastCollisionSig = "";
+	listeners = [];
 	constructor(options) {
 		this.current = options.initial;
 		this.warnSlugCollisions(options.initial.modelOverrides);
@@ -19912,6 +19929,20 @@ var FileWatchingConfigSource = class {
 	get() {
 		return this.current;
 	}
+	subscribe(listener) {
+		this.listeners.push(listener);
+		return () => {
+			const i = this.listeners.indexOf(listener);
+			if (i !== -1) this.listeners.splice(i, 1);
+		};
+	}
+	/** Notify subscribers after a successful reload. A throwing subscriber
+	* must not abort the reload or skip the remaining subscribers. */
+	notify(config) {
+		for (const listener of this.listeners) try {
+			listener(config);
+		} catch {}
+	}
 	/** Warn only when the collision set changes, so reloading an unchanged config doesn't re-log. */
 	warnSlugCollisions(overrides) {
 		const collisions = detectSlugCollisions(overrides ?? void 0);
@@ -19943,6 +19974,7 @@ var FileWatchingConfigSource = class {
 			this.warnSlugCollisions(next.modelOverrides);
 			if (restartNeeded) logger.warn("host/port changed — restart proxitor to apply (live reload does not re-bind the socket)");
 			logger.info(`Config reloaded${diff ? ` — ${diff}` : " (no material changes)"}`);
+			this.notify(next);
 			return { ok: true };
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
@@ -22779,6 +22811,12 @@ function withJsonContentType(headers) {
 		"content-type": "application/json"
 	};
 }
+function withRouterMetadata(headers, enabled) {
+	return enabled ? {
+		...headers,
+		"x-openrouter-metadata": "enabled"
+	} : headers;
+}
 const buildUpstreamReq = createMiddleware(async (c, next) => {
 	c.set("forwardBody", resolveForwardBody({
 		reqId: c.var.reqId,
@@ -22793,6 +22831,7 @@ const buildUpstreamReq = createMiddleware(async (c, next) => {
 	});
 	if (c.var.effectiveSessionId !== void 0) headers = withSessionId(headers, c.var.effectiveSessionId);
 	if (c.var.bodyMutated) headers = withJsonContentType(headers);
+	headers = withRouterMetadata(headers, c.var.config.observability.routerMetadata);
 	c.set("upstreamHeaders", headers);
 	await next();
 });
@@ -22838,9 +22877,10 @@ function parseForwardBody(body) {
 		return null;
 	}
 }
-/** `response` is filled later by dumpResponse, once the upstream stream completes. */
+/** Writes the request half; `response` is filled later by dumpResponse. Returns
+* the file path so the response half can find it without a reqId→path lookup. */
 function dumpRequest(meta) {
-	if (!dumpEnabled()) return;
+	if (!dumpEnabled()) return void 0;
 	ensureDir(dumpDir());
 	const record = {
 		reqId: meta.reqId,
@@ -22851,156 +22891,313 @@ function dumpRequest(meta) {
 		request: parseForwardBody(meta.forwardBody),
 		response: null
 	};
-	writeFileSync(filePath(meta.reqId, meta.model), `${JSON.stringify(record, null, 2)}\n`);
+	const path = filePath(meta.reqId, meta.model);
+	writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`);
+	return path;
 }
-function dumpResponse(reqId, status, usage) {
+async function dumpResponse(obs) {
 	if (!dumpEnabled()) return;
-	const dir = dumpDir();
-	if (!existsSync(dir)) return;
-	const name = readdirSync(dir).find((f) => f.endsWith(`${reqId}.json`));
-	if (!name) return;
-	const path = join(dir, name);
+	const path = obs.dumpPath;
+	if (path === void 0) return;
 	try {
-		const record = JSON.parse(readFileSync(path, "utf-8"));
-		const { cacheRead = 0, cacheCreate = 0, inputTokens = 0 } = usage ?? {};
+		const record = JSON.parse(await readFile(path, "utf-8"));
+		const r = obs.routing;
 		record.response = {
-			status,
-			cacheRead,
-			cacheCreate,
-			inputTokens,
-			hitPct: inputTokens > 0 ? Number((cacheRead / inputTokens * 100).toFixed(2)) : 0
+			status: obs.status,
+			label: obs.outcome.label,
+			requestType: obs.requestType,
+			model: obs.model,
+			sessionId: obs.sessionId ?? null,
+			toolsCount: obs.toolsCount,
+			inputTokens: obs.usage.inputTokens,
+			cacheRead: obs.usage.cacheRead,
+			cacheCreate: obs.usage.cacheCreate,
+			hitPct: obs.outcome.hitPct,
+			...r ? {
+				provider: r.provider,
+				strategy: r.strategy,
+				region: r.region ?? null,
+				attempt: r.attempt,
+				fallback: r.fallback,
+				generationId: r.generationId ?? null
+			} : {
+				provider: null,
+				strategy: null,
+				region: null,
+				attempt: null,
+				fallback: false,
+				generationId: null
+			}
 		};
-		writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`);
+		await writeFile(path, `${JSON.stringify(record, null, 2)}\n`);
 	} catch {}
 }
 //#endregion
-//#region src/proxy/cache-logging.ts
-function applyOpenAIDetails(details, result) {
-	let found = false;
-	if (typeof details.cached_tokens === "number" && details.cached_tokens > 0) {
-		result.cacheRead = details.cached_tokens;
-		found = true;
-	}
-	if (typeof details.cache_write_tokens === "number" && details.cache_write_tokens > 0) {
-		result.cacheCreate = details.cache_write_tokens;
-		found = true;
-	}
-	return found;
-}
-function applyAnthropicUsage(usage, result) {
-	if (typeof usage.cache_read_input_tokens === "number" && usage.cache_read_input_tokens > 0) result.cacheRead = usage.cache_read_input_tokens;
-	if (typeof usage.cache_creation_input_tokens === "number" && usage.cache_creation_input_tokens > 0) result.cacheCreate = usage.cache_creation_input_tokens;
-	if (typeof usage.input_tokens === "number" && usage.input_tokens > 0) result.inputTokens = usage.input_tokens + result.cacheRead + result.cacheCreate;
-}
-function applyOpenAIUsage(usage, result) {
-	const promptDetails = usage.prompt_tokens_details;
-	if (typeof promptDetails === "object" && promptDetails !== null) applyOpenAIDetails(promptDetails, result);
-	if (result.cacheRead === 0 && result.cacheCreate === 0) {
-		const inputDetails = usage.input_tokens_details;
-		if (typeof inputDetails === "object" && inputDetails !== null) applyOpenAIDetails(inputDetails, result);
-	}
-	if (typeof usage.prompt_tokens === "number" && usage.prompt_tokens > 0) result.inputTokens = usage.prompt_tokens;
-	else if (typeof usage.input_tokens === "number" && usage.input_tokens > 0) result.inputTokens = usage.input_tokens;
-}
-function extractFromUsage(usage, result) {
-	if (typeof usage.cache_read_input_tokens === "number" || typeof usage.cache_creation_input_tokens === "number") applyAnthropicUsage(usage, result);
-	else applyOpenAIUsage(usage, result);
+//#region src/proxy/observability/extract.ts
+function num(v) {
+	return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+/** First non-empty candidate — the generation id may live at the root or under message/response. */
+function firstStringId(vals) {
+	for (const v of vals) if (typeof v === "string" && v.length > 0) return v;
+}
+function applyAnthropic(usage, r, cr, cc) {
+	if (cr !== void 0) r.cacheRead = cr;
+	if (cc !== void 0) r.cacheCreate = cc;
+	const inp = num(usage.input_tokens);
+	if (inp !== void 0) r.inputTokens = inp + r.cacheRead + r.cacheCreate;
+}
+function applyOpenAI(usage, r) {
+	const details = usage.prompt_tokens_details ?? usage.input_tokens_details;
+	if (details && typeof details === "object") {
+		const cached = num(details.cached_tokens);
+		if (cached !== void 0) r.cacheRead = cached;
+		const write = num(details.cache_write_tokens);
+		if (write !== void 0) r.cacheCreate = write;
+	}
+	const prompt = num(usage.prompt_tokens) ?? num(usage.input_tokens);
+	if (prompt !== void 0) r.inputTokens = prompt;
+}
+/** Find the usage object, unwrapping Anthropic `message`/`response` SSE containers. */
+function usageObject(parsed) {
+	for (const c of [
+		parsed.message,
+		parsed.response,
+		parsed
+	]) if (c && typeof c === "object" && "usage" in c) {
+		const u = c.usage;
+		if (u && typeof u === "object") return u;
+	}
+}
+function parseUsage(parsed) {
+	if (!parsed || typeof parsed !== "object") return void 0;
+	const usage = usageObject(parsed);
+	if (usage === void 0) return void 0;
+	const r = {
+		present: true,
+		inputTokens: 0,
+		cacheRead: 0,
+		cacheCreate: 0
+	};
+	const cr = num(usage.cache_read_input_tokens);
+	const cc = num(usage.cache_creation_input_tokens);
+	if (cr !== void 0 || cc !== void 0) applyAnthropic(usage, r, cr, cc);
+	else applyOpenAI(usage, r);
+	return r;
+}
+/** Provider from endpoints[].available (selected first), then the last attempt; '' is absent. */
+function resolveProvider(meta) {
+	const avail = meta.endpoints?.available;
+	if (Array.isArray(avail)) {
+		const selected = avail.find((e) => e.selected === true);
+		const selProvider = selected ? selected.provider : avail[0]?.provider;
+		if (selProvider) return selProvider;
+	}
+	const attempts = meta.attempts;
+	if (Array.isArray(attempts)) {
+		const last = attempts.at(-1)?.provider;
+		if (last) return last;
+	}
+}
+function parseRouting(parsed) {
+	if (!parsed || typeof parsed !== "object") return void 0;
+	const root = parsed;
+	const meta = root.openrouter_metadata ?? root.message?.openrouter_metadata ?? root.response?.openrouter_metadata;
+	if (!meta || typeof meta !== "object") return void 0;
+	const provider = resolveProvider(meta);
+	if (!provider) return void 0;
+	const attempt = num(meta.attempt) ?? 1;
+	const generationId = firstStringId([
+		root.id,
+		root.message?.id,
+		root.response?.id
+	]);
+	return {
+		provider,
+		strategy: typeof meta.strategy === "string" ? meta.strategy : "unknown",
+		region: typeof meta.region === "string" ? meta.region : void 0,
+		attempt,
+		fallback: attempt > 1,
+		generationId
+	};
 }
-/** @internal */
-function extractCacheUsage(bodyText) {
+function fold(parsed, acc) {
+	const u = parseUsage(parsed);
+	if (u) if (!acc.usage) acc.usage = { ...u };
+	else {
+		const a = acc.usage;
+		if (u.cacheRead > 0) a.cacheRead = u.cacheRead;
+		if (u.cacheCreate > 0) a.cacheCreate = u.cacheCreate;
+		if (u.inputTokens > 0) a.inputTokens = u.inputTokens;
+	}
+	const rt = parseRouting(parsed);
+	if (rt) acc.routing = rt;
+}
+/** Strip a leading UTF-8 BOM (U+FEFF) — trim() no longer removes it (ES2019). */
+function stripBom(s) {
+	return s.charCodeAt(0) === 65279 ? s.slice(1) : s;
+}
+/** Parse one SSE `data:` line into the accumulator. Shared by the stateless and streaming folds. */
+function parseDataLine(line, acc) {
+	const trimmed = stripBom(line).trim();
+	if (!trimmed.startsWith("data:")) return;
+	const payload = trimmed.slice(5).trim();
+	if (payload === "" || payload === "[DONE]") return;
 	try {
-		const parsed = JSON.parse(bodyText);
-		if (typeof parsed !== "object" || parsed === null) return void 0;
-		const usage = parsed.usage;
-		if (typeof usage !== "object" || usage === null) return void 0;
-		const result = {
-			cacheRead: 0,
-			cacheCreate: 0,
-			inputTokens: 0
+		fold(JSON.parse(payload), acc);
+	} catch {}
+}
+function extractFromFullText(text, isSSE) {
+	if (!isSSE) try {
+		const parsed = JSON.parse(stripBom(text));
+		return {
+			usage: parseUsage(parsed),
+			routing: parseRouting(parsed)
 		};
-		extractFromUsage(usage, result);
-		return result;
 	} catch {
-		return;
+		return {};
+	}
+	const acc = {};
+	for (const line of text.split("\n")) parseDataLine(line, acc);
+	return acc;
+}
+/** Stateful fold over an SSE byte stream — O(1) memory, fragmentation-safe. */
+var SseUsageAccumulator = class {
+	buffer = "";
+	offset = 0;
+	done = false;
+	decoder = new TextDecoder();
+	acc = {};
+	feed(chunk) {
+		if (this.done) return;
+		this.buffer += this.decoder.decode(chunk, { stream: true });
+		let nl = this.buffer.indexOf("\n", this.offset);
+		while (nl !== -1) {
+			this.process(this.buffer.slice(this.offset, nl));
+			this.offset = nl + 1;
+			nl = this.buffer.indexOf("\n", this.offset);
+		}
+		if (this.offset > 0) {
+			this.buffer = this.buffer.slice(this.offset);
+			this.offset = 0;
+		}
 	}
-}
-function extractFromEvent(parsed, result) {
-	if (typeof parsed !== "object" || parsed === null) return false;
-	const record = parsed;
-	const usage = (record.message ?? record.response ?? parsed).usage;
-	if (typeof usage !== "object" || usage === null) return false;
-	const before = result.cacheRead + result.cacheCreate;
-	extractFromUsage(usage, result);
-	return result.cacheRead + result.cacheCreate > before;
-}
-/** @internal */
-function extractCacheUsageFromSSE(fullText) {
-	const result = {
-		cacheRead: 0,
-		cacheCreate: 0,
-		inputTokens: 0
-	};
-	let found = false;
-	for (const line of fullText.split("\n")) {
-		if (!line.startsWith("data:")) continue;
-		const payload = line.slice(5).trim();
-		if (payload === "[DONE]") continue;
-		try {
-			if (extractFromEvent(JSON.parse(payload), result)) found = true;
-		} catch {}
+	result() {
+		if (this.done) return this.acc;
+		this.done = true;
+		this.buffer += this.decoder.decode();
+		if (this.buffer.length > 0) this.process(this.buffer.slice(this.offset));
+		this.buffer = "";
+		this.offset = 0;
+		return this.acc;
 	}
-	return found ? result : void 0;
-}
-function formatCacheUsage(usage, reqId) {
-	const parts = [];
-	if (usage.cacheRead > 0) parts.push(`read: ${usage.cacheRead}`);
-	if (usage.cacheCreate > 0) parts.push(`write: ${usage.cacheCreate}`);
-	const pct = usage.inputTokens > 0 && usage.cacheRead > 0 ? ` (${(usage.cacheRead / usage.inputTokens * 100).toFixed(1)}% hit)` : "";
-	logger.info(withReq(reqId, parts.length > 0 ? `Cache ${parts.join(", ")} tokens${pct}` : "Cache: no cached tokens"));
-}
-function createLoggingStream(contentType, reqId, status) {
-	const isDumpEnabled = dumpEnabled();
-	const isSSE = contentType.toLowerCase().includes("text/event-stream");
-	const chunks = isDumpEnabled || !isSSE ? [] : null;
-	let tailText = "";
-	return new TransformStream({
-		transform(chunk, controller) {
-			controller.enqueue(chunk);
-			if (chunks) chunks.push(chunk);
+	process(line) {
+		parseDataLine(line, this.acc);
+	}
+};
+//#endregion
+//#region src/proxy/cache-logging.ts
+/**
+* Wraps the upstream body so usage/routing is observed once on ANY termination
+* path (clean close, client cancel, upstream error) via finalize() — a bare
+* TransformStream skips flush() on upstream errors, orphaning the dump.
+*/
+function createLoggingStream(source, contentType, status, ctx) {
+	const accumulator = contentType.toLowerCase().includes("text/event-stream") ? new SseUsageAccumulator() : void 0;
+	const decoder = new TextDecoder();
+	const chunks = [];
+	let finalized = false;
+	const finalize = () => {
+		if (finalized) return;
+		finalized = true;
+		try {
+			let extracted;
+			if (accumulator) extracted = accumulator.result();
 			else {
-				const decoder = new TextDecoder();
-				tailText += decoder.decode(chunk, { stream: true });
-				if (tailText.length > 4096) tailText = tailText.slice(-4096);
+				let text = "";
+				for (const c of chunks) text += decoder.decode(c, { stream: true });
+				text += decoder.decode();
+				extracted = extractFromFullText(text, false);
 			}
-		},
-		flush() {
+			ctx.observability.observe(ctx.reqCtx, extracted, status);
+		} catch (err) {
+			logger.debug(withReq(ctx.reqCtx.reqId, `Cache observability failed: ${err instanceof Error ? err.message : err}`));
+		}
+	};
+	const reader = source.getReader();
+	return new ReadableStream({
+		async pull(controller) {
 			try {
-				const decoder = new TextDecoder();
-				const text = chunks ? `${chunks.reduce((acc, chunk) => acc + decoder.decode(chunk, { stream: true }), "")}${decoder.decode()}` : `\n${tailText}${decoder.decode()}`;
-				const usage = isSSE ? extractCacheUsageFromSSE(text) : extractCacheUsage(text);
-				if (usage) formatCacheUsage(usage, reqId);
-				if (isDumpEnabled) dumpResponse(reqId, status, usage);
+				const { done, value } = await reader.read();
+				if (done) {
+					finalize();
+					controller.close();
+					return;
+				}
+				if (value) {
+					if (accumulator) accumulator.feed(value);
+					else chunks.push(value);
+					controller.enqueue(value);
+				}
 			} catch (err) {
-				logger.debug(withReq(reqId, `Cache usage extraction failed: ${err instanceof Error ? err.message : err}`));
+				finalize();
+				controller.error(err);
 			}
+		},
+		cancel() {
+			finalize();
+			reader.cancel().catch(() => {});
 		}
 	});
 }
-function buildUpstreamResponseWithLogging(upstream, method, reqId) {
+function buildUpstreamResponseWithLogging(upstream, method, ctx) {
 	const headers = buildResponseHeaders(upstream.headers);
-	if (method === "HEAD" || !upstream.body) return new Response(null, {
-		status: upstream.status,
-		headers
-	});
+	if (method === "HEAD" || !upstream.body) {
+		ctx.observability.observe(ctx.reqCtx, {}, upstream.status);
+		return new Response(null, {
+			status: upstream.status,
+			headers
+		});
+	}
 	const contentType = upstream.headers.get("content-type") ?? "";
 	const lower = contentType.toLowerCase();
-	const body = lower.includes("application/json") || lower.includes("text/event-stream") ? upstream.body.pipeThrough(createLoggingStream(contentType, reqId, upstream.status)) : upstream.body;
+	if (!(lower.includes("application/json") || lower.includes("text/event-stream"))) {
+		ctx.observability.observe(ctx.reqCtx, {}, upstream.status);
+		return new Response(upstream.body, {
+			status: upstream.status,
+			headers
+		});
+	}
+	const body = createLoggingStream(upstream.body, contentType, upstream.status, ctx);
 	return new Response(body, {
 		status: upstream.status,
 		headers
 	});
 }
 //#endregion
+//#region src/proxy/observability/classify.ts
+function classifyRequestType(ctx, opts) {
+	const budget = ctx.maxTokens === void 0 || ctx.maxTokens <= 0 ? Number.POSITIVE_INFINITY : ctx.maxTokens;
+	return ctx.toolsCount === 0 && budget <= opts.sideMaxTokens ? "side" : "main";
+}
+function classifyCacheOutcome(usage, ctx, opts) {
+	if (!usage.present) return {
+		label: "NOUSAGE",
+		type: ctx.requestType,
+		hitPct: 0
+	};
+	const raw = usage.inputTokens > 0 ? usage.cacheRead / usage.inputTokens * 100 : 0;
+	const hitPct = Math.min(100, raw);
+	let label;
+	if (usage.cacheRead === 0) label = ctx.isFirstForSession ? "COLD" : "MISS";
+	else label = hitPct >= opts.hitThresholdPct ? "HIT" : "PARTIAL";
+	return {
+		label,
+		type: ctx.requestType,
+		hitPct: Number(hitPct.toFixed(1))
+	};
+}
+//#endregion
 //#region src/proxy/utils/error.ts
 function formatMetadata(meta) {
 	const parts = [];
@@ -23031,7 +23228,7 @@ function extractErrorDetail(bodyText) {
 //#endregion
 //#region src/proxy/middleware/forward-request.ts
 const DUPLEX_HALF = { duplex: "half" };
-function buildErrorResponse(err, ctx) {
+function buildErrorResponse(err, ctx, observeUnhandled) {
 	if (err instanceof TypeError) {
 		logger.error(withReq(ctx.reqId, "Upstream fetch error:"), err);
 		return Response.json({ error: {
@@ -23043,6 +23240,7 @@ function buildErrorResponse(err, ctx) {
 		logger.warn(withReq(ctx.reqId, `Aborted: ${ctx.method} ${ctx.path}`));
 		return new Response(null, { status: 499 });
 	}
+	observeUnhandled?.();
 	throw err;
 }
 async function buildUpstreamErrorResponse(upstream, ctx) {
@@ -23051,14 +23249,16 @@ async function buildUpstreamErrorResponse(upstream, ctx) {
 	const truncated = detail.length > 300 ? `${detail.slice(0, 300)}…` : detail;
 	(upstream.status >= 500 ? logger.error : logger.warn)(withReq(ctx.reqId, `${ctx.method} ${ctx.path} ← ${upstream.status} (${Date.now() - ctx.startedAt}ms): ${truncated}`));
 	const responseHeaders = buildResponseHeaders(upstream.headers);
-	if (ctx.method === "HEAD") return new Response(null, {
-		status: upstream.status,
-		headers: responseHeaders
-	});
-	return new Response(bodyText, {
-		status: upstream.status,
-		headers: responseHeaders
-	});
+	return {
+		response: ctx.method === "HEAD" ? new Response(null, {
+			status: upstream.status,
+			headers: responseHeaders
+		}) : new Response(bodyText, {
+			status: upstream.status,
+			headers: responseHeaders
+		}),
+		extracted: extractFromFullText(bodyText, false)
+	};
 }
 const forwardRequest = createMiddleware(async (c) => {
 	const { upstreamUrl, forwardBody, upstreamHeaders, reqId, path, startedAt, method } = c.var;
@@ -23075,13 +23275,30 @@ const forwardRequest = createMiddleware(async (c) => {
 	const upstreamShort = upstreamUrl.replace(/^https?:\/\//, "");
 	const modelLog = c.var.modelName ? ` model=${c.var.modelName}` : "";
 	logger.info(withReq(reqId, `${method} ${path} → ${upstreamShort}${ctx.bodyMutated ? " [inject]" : ""}${modelLog}`));
-	if (dumpEnabled()) dumpRequest({
+	const dumpPath = dumpEnabled() ? dumpRequest({
 		reqId,
 		method,
 		path,
 		model: c.var.modelName,
 		forwardBody
-	});
+	}) : void 0;
+	const parsedBody = c.var.parsedBody;
+	const toolsCount = Array.isArray(parsedBody?.tools) ? parsedBody.tools.length : 0;
+	const maxTokens = parsedBody?.max_tokens ?? parsedBody?.max_completion_tokens ?? parsedBody?.max_output_tokens;
+	const requestType = classifyRequestType({
+		toolsCount,
+		maxTokens
+	}, { sideMaxTokens: c.var.config.observability.sideMaxTokens });
+	const reqCtx = {
+		reqId,
+		model: c.var.modelName ?? "",
+		sessionId: c.var.effectiveSessionId,
+		toolsCount,
+		maxTokens,
+		requestType,
+		dumpPath
+	};
+	const observability = c.var.observability;
 	let upstream;
 	try {
 		upstream = await fetch(upstreamUrl, {
@@ -23092,13 +23309,32 @@ const forwardRequest = createMiddleware(async (c) => {
 			...forwardBody ? DUPLEX_HALF : {}
 		});
 	} catch (err) {
-		return buildErrorResponse(err, ctx);
+		const response = buildErrorResponse(err, ctx, () => observability.observe(reqCtx, {}, 500));
+		observability.observe(reqCtx, {}, response.status);
+		return response;
 	} finally {
 		c.req.raw.signal.removeEventListener("abort", onClientAbort);
 	}
-	if (upstream.status >= 400) return buildUpstreamErrorResponse(upstream, ctx);
+	if (upstream.status >= 400) {
+		let extracted = {};
+		let response;
+		try {
+			({response, extracted} = await buildUpstreamErrorResponse(upstream, ctx));
+		} catch {
+			logger.debug(withReq(reqId, `upstream ${upstream.status} error body unreadable; observing without detail`));
+			response = new Response(null, {
+				status: upstream.status,
+				headers: buildResponseHeaders(upstream.headers)
+			});
+		}
+		observability.observe(reqCtx, extracted, upstream.status);
+		return response;
+	}
 	logger.info(withReq(reqId, `${method} ${path} ← ${upstream.status} (${Date.now() - startedAt}ms)`));
-	return buildUpstreamResponseWithLogging(upstream, method, reqId);
+	return buildUpstreamResponseWithLogging(upstream, method, {
+		reqCtx,
+		observability
+	});
 });
 //#endregion
 //#region src/proxy/paths.ts
@@ -23435,6 +23671,172 @@ const setupRequest = createMiddleware(async (c, next) => {
 	await next();
 });
 //#endregion
+//#region src/proxy/observability/session-tracker.ts
+var SessionTracker = class {
+	seen = /* @__PURE__ */ new Map();
+	constructor(opts, now = Date.now) {
+		this.opts = opts;
+		this.now = now;
+	}
+	opts;
+	now;
+	isFirstAndRemember(sessionId) {
+		if (sessionId === void 0) return true;
+		const t = this.now();
+		const prev = this.seen.get(sessionId);
+		const fresh = prev !== void 0 && t - prev < this.opts.ttlMs;
+		if (prev !== void 0) this.seen.delete(sessionId);
+		else if (this.seen.size >= this.opts.maxEntries) this.evictOne();
+		this.seen.set(sessionId, t);
+		return !fresh;
+	}
+	/** Drop the LRU entry (first by Map order). A refresh moves the key to the
+	* end, so iteration order is lastSeen order — the first entry is most stale. */
+	evictOne() {
+		const oldest = this.seen.keys().next().value;
+		if (oldest !== void 0) this.seen.delete(oldest);
+	}
+	/** Apply a reloaded capacity/TTL without discarding remembered sessions —
+	* shrinking evicts LRU entries, growing is a no-op, TTL applies on the next
+	* freshness check. Rebuilding would wipe the map and misclassify as COLD. */
+	applyConfig(opts) {
+		this.opts = opts;
+		while (this.seen.size > opts.maxEntries) this.evictOne();
+	}
+};
+//#endregion
+//#region src/proxy/observability/sinks.ts
+const wrap = (code) => (s) => `\x1b[${code}m${s}\x1b[0m`;
+const PAINT = {
+	HIT: wrap("32"),
+	PARTIAL: wrap("33"),
+	MISS: wrap("31"),
+	COLD: wrap("2"),
+	NOUSAGE: wrap("90")
+};
+function colorizeLabel(label, useColor) {
+	return useColor ? PAINT[label](label) : label;
+}
+function formatLine(obs, useColor = false) {
+	const { label, hitPct } = obs.outcome;
+	const parts = [colorizeLabel(label, useColor)];
+	if (label === "HIT" || label === "PARTIAL") parts.push(`${hitPct.toFixed(0)}%`);
+	if (obs.usage.cacheRead > 0) parts.push(`read ${obs.usage.cacheRead}`);
+	if (obs.usage.cacheCreate > 0) parts.push(`write ${obs.usage.cacheCreate}`);
+	if (obs.usage.present) parts.push(`in ${obs.usage.inputTokens}`);
+	if (obs.routing) parts.push(`provider=${obs.routing.provider}`);
+	if (obs.model) parts.push(obs.model);
+	parts.push(`[${obs.requestType}]`);
+	return withReq(obs.reqId, parts.join("  "));
+}
+var LiveLineSink = class {
+	useColor;
+	constructor(useColor = () => process.stdout.isTTY === true) {
+		this.useColor = useColor;
+	}
+	emit(obs) {
+		logger.info(formatLine(obs, this.useColor()));
+	}
+};
+var DumpSink = class {
+	inflight = 0;
+	waiters = [];
+	maxConcurrent;
+	maxWaiters;
+	dump;
+	enabled;
+	constructor(deps = {}) {
+		this.maxConcurrent = deps.maxConcurrent ?? 16;
+		this.maxWaiters = deps.maxWaiters ?? 256;
+		this.dump = deps.dump ?? dumpResponse;
+		this.enabled = deps.enabled ?? dumpEnabled;
+	}
+	emit(obs) {
+		if (!this.enabled()) return;
+		const run = () => {
+			this.inflight += 1;
+			this.dump(obs).catch((err) => {
+				logger.debug(withReq(obs.reqId, `DumpSink failed: ${err instanceof Error ? err.message : err}`));
+			}).finally(() => {
+				this.inflight -= 1;
+				const next = this.waiters.shift();
+				if (next) next();
+			});
+		};
+		if (this.inflight < this.maxConcurrent) run();
+		else if (this.waiters.length < this.maxWaiters) this.waiters.push(run);
+		else logger.debug(withReq(obs.reqId, "DumpSink queue full — dump dropped"));
+	}
+};
+//#endregion
+//#region src/proxy/observability/observability.ts
+var Observability = class {
+	tracker;
+	sinks;
+	hitThresholdPct;
+	constructor(tracker, sinks, hitThresholdPct) {
+		this.tracker = tracker;
+		this.sinks = sinks;
+		this.hitThresholdPct = hitThresholdPct;
+	}
+	/** Classify and dispatch one observation to every sink. Never throws: the
+	* response pipeline calls this on many termination paths, so a failure must
+	* degrade to a debug log, not escape to the client. */
+	observe(req, extracted, status) {
+		try {
+			const usage = extracted.usage ?? {
+				present: false,
+				inputTokens: 0,
+				cacheRead: 0,
+				cacheCreate: 0
+			};
+			const isFirst = this.tracker.isFirstAndRemember(req.sessionId);
+			const outcome = classifyCacheOutcome(usage, {
+				requestType: req.requestType,
+				isFirstForSession: isFirst
+			}, { hitThresholdPct: this.hitThresholdPct });
+			const obs = {
+				dumpPath: req.dumpPath,
+				reqId: req.reqId,
+				status,
+				model: req.model,
+				sessionId: req.sessionId,
+				requestType: req.requestType,
+				toolsCount: req.toolsCount,
+				usage,
+				outcome,
+				routing: extracted.routing
+			};
+			for (const sink of this.sinks) try {
+				sink.emit(obs);
+			} catch (err) {
+				logger.debug(withReq(obs.reqId, `Observability sink failed: ${err instanceof Error ? err.message : err}`));
+			}
+		} catch (err) {
+			logger.debug(withReq(req.reqId, `Observability observe failed: ${err instanceof Error ? err.message : err}`));
+		}
+	}
+	/** Apply a hot-reloaded config in place — must not discard remembered
+	* sessions, or an unrelated reload misclassifies the next request as COLD. */
+	reconfigure(config) {
+		const o = config.observability;
+		this.hitThresholdPct = o.hitThreshold;
+		this.tracker.applyConfig({
+			maxEntries: o.sessionMaxEntries,
+			ttlMs: o.sessionTtlMs
+		});
+	}
+};
+function createObservability(config, sinks) {
+	const o = config.observability;
+	const tracker = new SessionTracker({
+		maxEntries: o.sessionMaxEntries,
+		ttlMs: o.sessionTtlMs
+	});
+	const built = [new LiveLineSink(), new DumpSink()];
+	return new Observability(tracker, sinks ?? built, o.hitThreshold);
+}
+//#endregion
 //#region src/proxy.ts
 const injectChain = [
 	parseBody,
@@ -23446,8 +23848,11 @@ const injectChain = [
 ];
 function createProxyServer(source, onReady) {
 	const app = new Hono();
+	const observability = createObservability(source.get());
+	source.subscribe((config) => observability.reconfigure(config));
 	app.use("*", async (c, next) => {
 		c.set("config", source.get());
+		c.set("observability", observability);
 		await next();
 	});
 	app.get("/health", (c) => {