@skaile/transform-proxy 0.3.1 → 0.5.0

package/dist/{config-BZsthgP-.mjs → config-DHxYF3Tv.mjs}

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
-import { timingSafeEqual } from "node:crypto";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
-import { existsSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parse } from "yaml";
@@ -46,9 +46,32 @@ function composeTransforms(stages, log = silentLogger) {
 			} catch (err) {
 				log.error(`transform dispose failed: ${errorMessage(err)}`);
 			}
-		}
+		},
+		...stages.some((stage) => stage.knownOriginals !== void 0) ? { knownOriginals: () => unionKnownOriginals(stages, log) } : {}
 	};
 }
+/** The originals of every stage, deduped by kind and value; a stage that throws is logged and skipped. */
+function unionKnownOriginals(stages, log) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const stage of stages) {
+		if (stage.knownOriginals === void 0) continue;
+		try {
+			for (const { kind, value } of stage.knownOriginals()) {
+				const key = JSON.stringify([kind, value]);
+				if (seen.has(key)) continue;
+				seen.add(key);
+				out.push({
+					kind,
+					value
+				});
+			}
+		} catch (err) {
+			log.error(`transform knownOriginals failed: ${errorMessage(err)}`);
+		}
+	}
+	return out;
+}
 /**
 * Streams stage by stage. `streams` is in pipeline order (stage 1 first).
 * push feeds stage n first and passes each result down to stage 1.
@@ -102,6 +125,74 @@ function createSessionFacts() {
 		}
 	};
 }
+// src/leaks.ts
+/** Shorter values match by chance too often to be worth a warning. */
+const MIN_LEAK_LENGTH = 3;
+const PLAIN_KEY = /^[A-Za-z_$][\w$]*$/;
+/**
+* The values the leak check compares against: the session's facts, each with its publisher as source, plus what the
+* pipeline instance reports via `knownOriginals()` as source `pipeline`. If that throws, only the facts are returned.
+*/
+function knownOriginals(facts, instance) {
+	const out = facts.list().map(({ kind, source, value }) => ({
+		kind,
+		source,
+		value
+	}));
+	if (instance?.knownOriginals === void 0) return out;
+	try {
+		const fromPipeline = [];
+		for (const { kind, value } of instance.knownOriginals()) fromPipeline.push({
+			kind,
+			source: "pipeline",
+			value
+		});
+		out.push(...fromPipeline);
+	} catch {}
+	return out;
+}
+/**
+* Every place in `body` (the rewritten request) where a string value contains a known original, case-sensitively.
+* Only string values are scanned, not object keys. The result holds kind, source and JSON path, never the value.
+*/
+function findLeaks(body, originals) {
+	const candidates = [];
+	for (const original of originals) if (original.value.length >= MIN_LEAK_LENGTH) candidates.push(original);
+	if (candidates.length === 0) return [];
+	const leaks = [];
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (node, path) => {
+		if (typeof node === "string") {
+			for (const { kind, source, value } of candidates) {
+				if (!node.includes(value)) continue;
+				const key = JSON.stringify([
+					kind,
+					source,
+					path
+				]);
+				if (seen.has(key)) continue;
+				seen.add(key);
+				leaks.push({
+					kind,
+					source,
+					at: path
+				});
+			}
+			return;
+		}
+		if (Array.isArray(node)) {
+			node.forEach((item, i) => visit(item, `${path}[${i}]`));
+			return;
+		}
+		if (node !== null && typeof node === "object") for (const [key, value] of Object.entries(node)) visit(value, joinKey(path, key));
+	};
+	visit(body, "");
+	return leaks;
+}
+function joinKey(path, key) {
+	if (!PLAIN_KEY.test(key)) return `${path}[${JSON.stringify(key)}]`;
+	return path === "" ? key : `${path}.${key}`;
+}
 // src/modules.ts
 /** Loads and opens every configured transform once. Any failure rejects with the transform id. */
 async function openTransforms(specs, baseDir, log) {
@@ -497,8 +588,81 @@ function tailDelta(kind, tail) {
 		partial_json: tail
 	};
 }
+/**
+* Rebuilds the Anthropic message from the raw upstream events (before restore) for `ctx.observe`.
+* Errors are swallowed: recording the reply must never disturb the stream.
+*/
+function createStreamObserver(observe) {
+	let message;
+	const content = [];
+	const toolJson = /* @__PURE__ */ new Map();
+	const settleTool = (index) => {
+		const json = toolJson.get(index);
+		const block = content[index];
+		if (json === void 0 || block === void 0) return;
+		toolJson.delete(index);
+		if (json === "") return;
+		try {
+			block.input = JSON.parse(json);
+		} catch {
+			block.input = json;
+		}
+	};
+	return {
+		event(payload) {
+			try {
+				const index = typeof payload.index === "number" ? payload.index : void 0;
+				switch (payload.type) {
+					case "message_start":
+						if (isObj$2(payload.message)) message = { ...payload.message };
+						return;
+					case "content_block_start":
+						if (index === void 0 || !isObj$2(payload.content_block)) return;
+						content[index] = { ...payload.content_block };
+						if (payload.content_block.type === "tool_use") toolJson.set(index, "");
+						return;
+					case "content_block_delta": {
+						const block = index === void 0 ? void 0 : content[index];
+						const delta = payload.delta;
+						if (block === void 0 || index === void 0 || !isObj$2(delta)) return;
+						if (delta.type === "text_delta" && typeof delta.text === "string") block.text = String(block.text ?? "") + delta.text;
+						else if (delta.type === "thinking_delta" && typeof delta.thinking === "string") block.thinking = String(block.thinking ?? "") + delta.thinking;
+						else if (delta.type === "signature_delta" && typeof delta.signature === "string") block.signature = String(block.signature ?? "") + delta.signature;
+						else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") toolJson.set(index, (toolJson.get(index) ?? "") + delta.partial_json);
+						return;
+					}
+					case "content_block_stop":
+						if (index !== void 0) settleTool(index);
+						return;
+					case "message_delta":
+						if (message === void 0) return;
+						if (isObj$2(payload.delta)) {
+							if ("stop_reason" in payload.delta) message.stop_reason = payload.delta.stop_reason;
+							if ("stop_sequence" in payload.delta) message.stop_sequence = payload.delta.stop_sequence;
+						}
+						if (isObj$2(payload.usage)) message.usage = {
+							...isObj$2(message.usage) ? message.usage : {},
+							...payload.usage
+						};
+						return;
+				}
+			} catch {}
+		},
+		finish() {
+			try {
+				for (const index of [...toolJson.keys()]) settleTool(index);
+				if (message !== void 0) observe({
+					...message,
+					content: content.filter((block) => block !== void 0)
+				});
+			} catch {}
+			message = void 0;
+		}
+	};
+}
 function createStreamTransformer$2(ctx) {
 	const blocks = /* @__PURE__ */ new Map();
+	const observer = ctx.observe === void 0 ? void 0 : createStreamObserver(ctx.observe);
 	const handle = (block) => {
 		let payload;
 		try {
@@ -507,6 +671,7 @@ function createStreamTransformer$2(ctx) {
 			return block.raw;
 		}
 		if (!isObj$2(payload)) return block.raw;
+		observer?.event(payload);
 		const index = typeof payload.index === "number" ? payload.index : void 0;
 		switch (payload.type) {
 			case "content_block_start": {
@@ -568,6 +733,7 @@ function createStreamTransformer$2(ctx) {
 		}
 	};
 	const finish = () => {
+		observer?.finish();
 		let out = "";
 		for (const [index, state] of blocks) {
 			const tail = state.restore.flush();
@@ -807,10 +973,93 @@ function flushChoice(state) {
 	state.tools.clear();
 	return Object.keys(delta).length === 0 ? void 0 : delta;
 }
+/** Rebuilds the non-streamed `chat.completion` from raw (pre-restore) chunks for `ctx.observe`. */
+function createChatAssembler() {
+	let seen = false;
+	let envelope = {};
+	let usage;
+	const choices = /* @__PURE__ */ new Map();
+	return {
+		add(chunk) {
+			seen = true;
+			envelope = chunk;
+			if (chunk.usage !== void 0 && chunk.usage !== null) usage = chunk.usage;
+			for (const choice of chunk.choices) {
+				if (!isObj$1(choice)) continue;
+				const index = typeof choice.index === "number" ? choice.index : 0;
+				let state = choices.get(index);
+				if (state === void 0) {
+					state = {
+						content: null,
+						tools: /* @__PURE__ */ new Map(),
+						finish: null
+					};
+					choices.set(index, state);
+				}
+				if (choice.finish_reason !== null && choice.finish_reason !== void 0) state.finish = choice.finish_reason;
+				const delta = choice.delta;
+				if (!isObj$1(delta)) continue;
+				if (typeof delta.content === "string") state.content = (state.content ?? "") + delta.content;
+				if (typeof delta.reasoning_content === "string") state.reasoning = (state.reasoning ?? "") + delta.reasoning_content;
+				if (!Array.isArray(delta.tool_calls)) continue;
+				for (const call of delta.tool_calls) {
+					if (!isObj$1(call)) continue;
+					const callIndex = typeof call.index === "number" ? call.index : 0;
+					let tool = state.tools.get(callIndex);
+					if (tool === void 0) {
+						tool = {
+							name: "",
+							arguments: ""
+						};
+						state.tools.set(callIndex, tool);
+					}
+					if (call.id !== void 0 && call.id !== null) tool.id = call.id;
+					const fn = call.function;
+					if (isObj$1(fn)) {
+						if (typeof fn.name === "string") tool.name += fn.name;
+						if (typeof fn.arguments === "string") tool.arguments += fn.arguments;
+					}
+				}
+			}
+		},
+		take() {
+			if (!seen) return void 0;
+			seen = false;
+			const out = {
+				id: envelope.id,
+				object: "chat.completion",
+				model: envelope.model,
+				choices: [...choices].sort(([a], [b]) => a - b).map(([index, state]) => {
+					const message = {
+						role: "assistant",
+						content: state.content
+					};
+					if (state.reasoning !== void 0) message.reasoning_content = state.reasoning;
+					if (state.tools.size > 0) message.tool_calls = [...state.tools].sort(([a], [b]) => a - b).map(([, t]) => ({
+						id: t.id,
+						type: "function",
+						function: {
+							name: t.name,
+							arguments: t.arguments
+						}
+					}));
+					return {
+						index,
+						message,
+						finish_reason: state.finish
+					};
+				})
+			};
+			if (usage !== void 0) out.usage = usage;
+			return out;
+		}
+	};
+}
 function createStreamTransformer$1(ctx) {
 	const choices = /* @__PURE__ */ new Map();
 	/** The latest chunk's envelope (id, model, ...), reused for tail chunks. */
 	let envelope = { object: "chat.completion.chunk" };
+	const assembler = ctx.observe === void 0 ? void 0 : createChatAssembler();
 	const choiceState = (index) => {
 		let state = choices.get(index);
 		if (state === void 0) {
@@ -889,6 +1138,7 @@ function createStreamTransformer$1(ctx) {
 			return block.raw;
 		}
 		if (!isObj$1(payload) || !Array.isArray(payload.choices)) return block.raw;
+		assembler?.add(payload);
 		const { choices: _choices, ...rest } = payload;
 		envelope = rest;
 		let changed = false;
@@ -920,7 +1170,20 @@ function createStreamTransformer$1(ctx) {
 			choices: rewritten
 		}) : block.raw);
 	};
-	return createSseFramer(handle, () => flushAll(void 0));
+	const framer = createSseFramer(handle, () => flushAll(void 0));
+	if (assembler === void 0) return framer;
+	const observe = ctx.observe;
+	return {
+		push: (chunk) => framer.push(chunk),
+		flush() {
+			const out = framer.flush();
+			const message = assembler.take();
+			if (message !== void 0) try {
+				observe(message);
+			} catch {}
+			return out;
+		}
+	};
 }
 const openaiChatWalker = {
 	async request(body, ctx) {
@@ -1165,6 +1428,8 @@ function restoreResponse(body, ctx) {
 }
 function createStreamTransformer(ctx) {
 	const streams = /* @__PURE__ */ new Map();
+	/** Raw (pre-restore) terminal `response` object, kept only for `ctx.observe`. */
+	let final;
 	const open = (key, factory) => {
 		let state = streams.get(key);
 		if (state === void 0) {
@@ -1256,10 +1521,16 @@ function createStreamTransformer(ctx) {
 				item: restoreItem(payload.item, ctx)
 			}) : block.raw;
 			case "response.completed":
-			case "response.incomplete": return isObj(payload.response) ? formatSseEvent(block.event, {
-				...payload,
-				response: restoreResponse(payload.response, ctx)
-			}) : block.raw;
+			case "response.incomplete":
+				if (!isObj(payload.response)) return block.raw;
+				if (ctx.observe !== void 0) final = payload.response;
+				return formatSseEvent(block.event, {
+					...payload,
+					response: restoreResponse(payload.response, ctx)
+				});
+			case "response.failed":
+				if (ctx.observe !== void 0 && isObj(payload.response)) final = payload.response;
+				return block.raw;
 			default: return block.raw;
 		}
 	};
@@ -1279,7 +1550,21 @@ function createStreamTransformer(ctx) {
 		streams.clear();
 		return out;
 	};
-	return createSseFramer(handle, finish);
+	const framer = createSseFramer(handle, finish);
+	const observe = ctx.observe;
+	if (observe === void 0) return framer;
+	return {
+		push: (chunk) => framer.push(chunk),
+		flush() {
+			const out = framer.flush();
+			const response = final;
+			final = void 0;
+			if (response !== void 0) try {
+				observe(response);
+			} catch {}
+			return out;
+		}
+	};
 }
 const openaiResponsesWalker = {
 	async request(body, ctx) {
@@ -1315,21 +1600,25 @@ const openaiResponsesWalker = {
 */
 const WIRE_ROUTES = [
 	{
+		name: "anthropic.count_tokens",
 		suffix: "/messages/count_tokens",
 		wire: anthropicWalker,
 		rewriteResponse: false
 	},
 	{
+		name: "anthropic.messages",
 		suffix: "/messages",
 		wire: anthropicWalker,
 		rewriteResponse: true
 	},
 	{
+		name: "openai.chat",
 		suffix: "/chat/completions",
 		wire: openaiChatWalker,
 		rewriteResponse: true
 	},
 	{
+		name: "openai.responses",
 		suffix: "/responses",
 		wire: openaiResponsesWalker,
 		rewriteResponse: true
@@ -1350,7 +1639,8 @@ function createSessionState() {
 	return {
 		facts: createSessionFacts(),
 		signatures: /* @__PURE__ */ new Map(),
-		instances: /* @__PURE__ */ new Map()
+		instances: /* @__PURE__ */ new Map(),
+		traced: /* @__PURE__ */ new Set()
 	};
 }
 /**
@@ -1380,6 +1670,65 @@ async function disposeInstances(state, log) {
 		}
 	}
 }
+// src/trace.ts
+const DEFAULT_TRACE_MAX_CHARS = 262144;
+const SAFE_SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
+/** Top-level body keys whose array elements are traced one by one: the conversation history the harness resends each round. */
+const PER_ELEMENT_KEYS = {
+	messages: true,
+	input: true
+};
+/**
+* One JSON line (no trailing newline). When the JSON of `content` is longer than `maxChars`,
+* `content` becomes that JSON text cut to `maxChars` and `truncated` is set.
+*/
+function serializeTraceEvent(event, maxChars = DEFAULT_TRACE_MAX_CHARS) {
+	const content = JSON.stringify(event.content);
+	if (content === void 0 || content.length <= maxChars) return JSON.stringify(event);
+	return JSON.stringify({
+		...event,
+		content: content.slice(0, maxChars),
+		truncated: true
+	});
+}
+/** Appends each event to `<dir>/<session>.jsonl`. The files hold whatever leaked, so they are owner-only. */
+function createFileTraceSink(options) {
+	const maxChars = options.maxChars ?? 262144;
+	let created = false;
+	return { record(event) {
+		if (!created) {
+			mkdirSync(options.dir, {
+				recursive: true,
+				mode: 448
+			});
+			created = true;
+		}
+		const file = join(options.dir, `${safeSessionId(event.sessionId)}.jsonl`);
+		appendFileSync(file, `${serializeTraceEvent(event, maxChars)}\n`, { mode: 384 });
+	} };
+}
+/** The id itself when it is a safe file name, otherwise a stable hash of it. */
+function safeSessionId(id) {
+	if (SAFE_SESSION_ID.test(id)) return id;
+	return `sha256-${createHash("sha256").update(id).digest("hex").slice(0, 32)}`;
+}
+/**
+* The request entries not yet traced in this session, keyed by JSON path; adds their hashes to `traced`.
+* `messages`/`input` arrays count per element, every other top-level key as a whole.
+*/
+function requestDelta(body, traced) {
+	const delta = {};
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return delta;
+	const add = (key, path, value) => {
+		const hash = createHash("sha256").update(`${key}\u0000${JSON.stringify(value)}`).digest("hex");
+		if (traced.has(hash)) return;
+		traced.add(hash);
+		delta[path] = value;
+	};
+	for (const [key, value] of Object.entries(body)) if (Object.hasOwn(PER_ELEMENT_KEYS, key) && Array.isArray(value)) value.forEach((element, i) => add(key, `${key}[${i}]`, element));
+	else add(key, key, value);
+	return delta;
+}
 // src/server.ts
 const UPSTREAM_HEADER = "x-skaile-transform-upstream";
 const SESSION_HEADER = "x-skaile-transform-session";
@@ -1415,6 +1764,8 @@ const RESPONSE_SKIP = {
 	"content-encoding": true,
 	"set-cookie": true
 };
+/** Upstream error bodies in the trace are cut to this many characters. */
+const ERROR_TRACE_CHARS = 4096;
 async function createTransformProxy(options) {
 	const log = options.log ?? silentLogger;
 	const host = options.host ?? "127.0.0.1";
@@ -1424,6 +1775,8 @@ async function createTransformProxy(options) {
 	const factories = await openTransforms(options.transforms, options.baseDir, log);
 	const pipelines = options.pipelines;
 	const sessions = /* @__PURE__ */ new Map();
+	/** Composed instance -> its stages with their transform ids, for `inspect`. */
+	const stagesOf = /* @__PURE__ */ new WeakMap();
 	function stateFor(id) {
 		const existing = sessions.get(id);
 		if (existing) return existing;
@@ -1431,6 +1784,28 @@ async function createTransformProxy(options) {
 		sessions.set(id, created);
 		return created;
 	}
+	/** A throwing sink is logged and otherwise ignored: the trace must never change what the client gets. */
+	function recordTrace(event) {
+		if (options.trace === void 0) return;
+		try {
+			options.trace.record(event);
+		} catch (err) {
+			log.error(`transform proxy: trace sink failed: ${errorMessage(err)}`);
+		}
+	}
+	/** Records this request's single response or error line; a no-op without a trace. */
+	function recordReply(trace, phase, status, content) {
+		if (trace === void 0) return;
+		recordTrace({
+			...trace.base,
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			phase,
+			status,
+			durationMs: Date.now() - trace.startedAt,
+			content,
+			leaks: []
+		});
+	}
 	async function buildInstance(state, sessionId, pipelineId) {
 		const stages = [];
 		const ids = pipelines[pipelineId] ?? [];
@@ -1456,7 +1831,12 @@ async function createTransformProxy(options) {
 			}
 			throw err;
 		}
-		return composeTransforms(stages, log);
+		const composed = composeTransforms(stages, log);
+		stagesOf.set(composed, ids.map((id, i) => ({
+			id,
+			transform: stages[i]
+		})));
+		return composed;
 	}
 	async function handle(req, res) {
 		const url = new URL(req.url ?? "/", "http://proxy.invalid");
@@ -1474,7 +1854,8 @@ async function createTransformProxy(options) {
 		const method = req.method ?? "GET";
 		const classified = classify(method, url.pathname);
 		if (classified === void 0) return sendError(res, 404, "unsupported_route", `${method} ${url.pathname} is not proxied`);
-		const forwardTo = `${upstream.origin}${upstream.pathname.replace(/\/+$/, "")}${url.pathname}${url.search}`;
+		const forwardPath = `${upstream.origin}${upstream.pathname.replace(/\/+$/, "")}${url.pathname}`;
+		const forwardTo = `${forwardPath}${url.search}`;
 		const headers = forwardRequestHeaders(req.headers);
 		if (classified.kind === "passthrough") return relayUpstream(res, await fetchUpstream(res, forwardTo, method, headers, void 0), void 0);
 		const { route } = classified;
@@ -1505,12 +1886,36 @@ async function createTransformProxy(options) {
 			if (err instanceof UnsupportedContentError) return sendError(res, 400, "unsupported_content", err.message);
 			return sendError(res, 502, "transform_failed", errorMessage(err));
 		}
-		return relayUpstream(res, await fetchUpstream(res, forwardTo, method, headers, JSON.stringify(rewritten)), route.rewriteResponse ? {
+		const leaks = findLeaks(rewritten, knownOriginals(state.facts.facts, instance));
+		if (leaks.length > 0) log.warn("transform proxy: known original sent upstream", {
+			sessionId,
+			route: route.name,
+			leaks
+		});
+		const trace = options.trace === void 0 ? void 0 : {
+			startedAt: Date.now(),
+			base: {
+				requestId: randomUUID(),
+				sessionId,
+				pipeline: pipelineId,
+				route: route.name,
+				upstream: forwardPath,
+				...modelOf(rewritten)
+			}
+		};
+		if (trace !== void 0) recordTrace({
+			...trace.base,
+			at: new Date(trace.startedAt).toISOString(),
+			phase: "request",
+			content: requestDelta(rewritten, state.traced),
+			leaks
+		});
+		return relayUpstream(res, await fetchUpstream(res, forwardTo, method, headers, JSON.stringify(rewritten), trace), route.rewriteResponse ? {
 			wire: route.wire,
 			ctx
-		} : void 0);
+		} : void 0, trace);
 	}
-	async function fetchUpstream(res, target, method, headers, body) {
+	async function fetchUpstream(res, target, method, headers, body, trace) {
 		try {
 			return await fetch(target, {
 				method,
@@ -1519,21 +1924,61 @@ async function createTransformProxy(options) {
 				redirect: "manual"
 			});
 		} catch (err) {
+			recordReply(trace, "error", 502, errorMessage(err));
 			sendError(res, 502, "upstream_unreachable", errorMessage(err));
 			return;
 		}
 	}
-	/** Relays an upstream response. With `rewrite`, a 2xx JSON or SSE body is restored on the way back. */
-	async function relayUpstream(res, upstreamRes, rewrite) {
+	/**
+	* Relays an upstream response. With `rewrite`, a 2xx JSON or SSE body is restored on the way back. With `trace`
+	* (wire routes only), the reply before restore is recorded as exactly one response or error line.
+	*/
+	async function relayUpstream(res, upstreamRes, rewrite, trace) {
 		if (upstreamRes === void 0) return;
 		const contentType = (upstreamRes.headers.get("content-type") ?? "").toLowerCase();
 		const headers = relayHeaders(upstreamRes.headers);
-		if (rewrite !== void 0 && upstreamRes.ok && contentType.startsWith("text/event-stream")) return pipeStream(res, upstreamRes, headers, rewrite.wire.stream(rewrite.ctx), log);
-		if (rewrite !== void 0 && upstreamRes.ok && contentType.includes("application/json")) {
-			const text = await upstreamRes.text();
+		if (trace !== void 0 && !upstreamRes.ok) {
+			const bytes = Buffer.from(await upstreamRes.arrayBuffer());
+			recordReply(trace, "error", upstreamRes.status, bytes.toString("utf8").slice(0, ERROR_TRACE_CHARS));
+			res.writeHead(upstreamRes.status, headers);
+			res.end(bytes);
+			return;
+		}
+		if (rewrite !== void 0 && upstreamRes.ok && contentType.startsWith("text/event-stream")) {
+			if (trace === void 0) return pipeStream(res, upstreamRes, headers, rewrite.wire.stream(rewrite.ctx), log);
+			let observed = false;
+			const observe = (message) => {
+				observed = true;
+				recordReply(trace, "response", upstreamRes.status, message);
+			};
+			await pipeStream(res, upstreamRes, headers, rewrite.wire.stream({
+				...rewrite.ctx,
+				observe
+			}), log);
+			if (!observed) recordReply(trace, "response", upstreamRes.status, void 0);
+			return;
+		}
+		if (upstreamRes.ok && contentType.includes("application/json") && (rewrite !== void 0 || trace !== void 0)) {
+			const bytes = Buffer.from(await upstreamRes.arrayBuffer());
+			let body;
+			try {
+				body = JSON.parse(new TextDecoder().decode(bytes));
+			} catch (err) {
+				recordReply(trace, "error", 502, errorMessage(err));
+				if (rewrite !== void 0) return sendError(res, 502, "transform_failed", errorMessage(err));
+				res.writeHead(upstreamRes.status, headers);
+				res.end(bytes);
+				return;
+			}
+			recordReply(trace, "response", upstreamRes.status, body);
+			if (rewrite === void 0) {
+				res.writeHead(upstreamRes.status, headers);
+				res.end(bytes);
+				return;
+			}
 			let restored;
 			try {
-				restored = JSON.stringify(rewrite.wire.response(JSON.parse(text), rewrite.ctx));
+				restored = JSON.stringify(rewrite.wire.response(body, rewrite.ctx));
 			} catch (err) {
 				return sendError(res, 502, "transform_failed", errorMessage(err));
 			}
@@ -1541,8 +1986,10 @@ async function createTransformProxy(options) {
 			res.end(restored);
 			return;
 		}
+		const bytes = Buffer.from(await upstreamRes.arrayBuffer());
+		recordReply(trace, "response", upstreamRes.status, void 0);
 		res.writeHead(upstreamRes.status, headers);
-		res.end(Buffer.from(await upstreamRes.arrayBuffer()));
+		res.end(bytes);
 	}
 	const server = createServer((req, res) => {
 		handle(req, res).catch((err) => {
@@ -1573,6 +2020,22 @@ async function createTransformProxy(options) {
 			sessions.delete(id);
 			await disposeInstances(state, log);
 		},
+		async inspect(sessionId, pipelineId) {
+			const state = sessions.get(sessionId);
+			const pipeline = pipelineId ?? options.defaultPipeline;
+			if (state === void 0 || pipeline === void 0) return {};
+			const pending = state.instances.get(pipeline);
+			if (pending === void 0) return {};
+			let instance;
+			try {
+				instance = await pending;
+			} catch {
+				return {};
+			}
+			const result = {};
+			for (const stage of stagesOf.get(instance) ?? []) if (typeof stage.transform.inspect === "function") result[stage.id] = stage.transform.inspect();
+			return result;
+		},
 		async close() {
 			const closed = Promise.withResolvers();
 			server.close((err) => err ? closed.reject(err) : closed.resolve());
@@ -1590,6 +2053,12 @@ function validatePipelines(options) {
 	for (const [pipelineId, ids] of Object.entries(options.pipelines)) for (const id of ids) if (!Object.hasOwn(options.transforms, id)) throw new Error(`pipeline "${pipelineId}" names unknown transform "${id}"`);
 	if (options.defaultPipeline !== void 0 && !Object.hasOwn(options.pipelines, options.defaultPipeline)) throw new Error(`defaultPipeline "${options.defaultPipeline}" is not a configured pipeline`);
 }
+/** `{ model }` when the request body names its model as a string, otherwise `{}`. */
+function modelOf(body) {
+	if (typeof body !== "object" || body === null) return {};
+	const model = body.model;
+	return typeof model === "string" ? { model } : {};
+}
 function originOf(value) {
 	const url = parseHttpUrl(value);
 	if (url === void 0) throw new Error(`allowUpstreams entry "${value}" is not an http(s) URL`);
@@ -1725,7 +2194,12 @@ const TOP_LEVEL_KEYS = {
 	transforms: true,
 	pipelines: true,
 	defaultPipeline: true,
-	allowUpstreams: true
+	allowUpstreams: true,
+	trace: true
+};
+const TRACE_KEYS = {
+	dir: true,
+	maxChars: true
 };
 /** Reads and validates a YAML config file. Unknown keys are rejected so that typos fail loudly. */
 function loadProxyConfig(path) {
@@ -1745,7 +2219,8 @@ function parseProxyConfig(source, baseDir) {
 		transforms: parseTransforms(source.transforms),
 		pipelines: parsePipelines(source.pipelines),
 		...source.defaultPipeline === void 0 ? {} : { defaultPipeline: requireString(source.defaultPipeline, "defaultPipeline") },
-		...source.allowUpstreams === void 0 ? {} : { allowUpstreams: requireStringList(source.allowUpstreams, "allowUpstreams") }
+		...source.allowUpstreams === void 0 ? {} : { allowUpstreams: requireStringList(source.allowUpstreams, "allowUpstreams") },
+		...source.trace === void 0 ? {} : { trace: parseTrace(source.trace, baseDir) }
 	};
 }
 function parseTransforms(value) {
@@ -1769,6 +2244,17 @@ function parsePipelines(value) {
 	for (const [id, stages] of Object.entries(value)) out[id] = requireStringList(stages, `pipelines.${id}`);
 	return out;
 }
+function parseTrace(value, baseDir) {
+	if (!isRecord(value)) throw new Error("trace must be a mapping with a dir");
+	for (const key of Object.keys(value)) if (!Object.hasOwn(TRACE_KEYS, key)) throw new Error(`unknown key "trace.${key}"`);
+	const dir = resolve(baseDir, requireString(value.dir, "trace.dir"));
+	if (value.maxChars === void 0) return { dir };
+	if (typeof value.maxChars !== "number" || !Number.isInteger(value.maxChars) || value.maxChars <= 0) throw new Error("trace.maxChars must be a positive integer");
+	return {
+		dir,
+		maxChars: value.maxChars
+	};
+}
 function requireString(value, field) {
 	if (typeof value !== "string" || value === "") throw new Error(`${field} must be a non-empty string`);
 	return value;
@@ -1780,4 +2266,4 @@ function requireStringList(value, field) {
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-export { composeTransforms as _, parseProxyConfig as a, SESSION_HEADER as c, createTransformProxy as d, openaiResponsesWalker as f, createSessionFacts as g, UnsupportedContentError as h, loadProxyConfig as i, TOKEN_HEADER as l, anthropicWalker as m, configCandidates as n, resolveProxyConfig as o, openaiChatWalker as p, findProxyConfig as r, PIPELINE_HEADER as s, CONFIG_FILE_NAME as t, UPSTREAM_HEADER as u, errorMessage as v, silentLogger as y };
+export { silentLogger as S, anthropicWalker as _, parseProxyConfig as a, composeTransforms as b, SESSION_HEADER as c, createTransformProxy as d, DEFAULT_TRACE_MAX_CHARS as f, openaiChatWalker as g, openaiResponsesWalker as h, loadProxyConfig as i, TOKEN_HEADER as l, serializeTraceEvent as m, configCandidates as n, resolveProxyConfig as o, createFileTraceSink as p, findProxyConfig as r, PIPELINE_HEADER as s, CONFIG_FILE_NAME as t, UPSTREAM_HEADER as u, UnsupportedContentError as v, errorMessage as x, createSessionFacts as y };