@skaile/transform-proxy 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.5.0
+
+- Library: the anon trace records what the proxy sends to the provider **after** the pipeline and what the model answers **before** restore, so a reviewer can check that no clear-text personal data reached the provider. `TransformProxyOptions.trace?: TraceSink` (synchronous `record(event: TraceEvent)`) gets one `request` line per proxied request on the wire routes and exactly one `response` or `error` line for it, linked by `requestId`. Without `trace`, nothing is recorded or hashed. A sink that throws is logged (`transform proxy: trace sink failed: <msg>`) and never reaches the client.
+- Library: a `request` line holds only the delta: the entries of the rewritten body not yet traced in this session, keyed by JSON path (`messages[i]` / `input[i]` per element, every other top-level key such as `system`, `tools`, `instructions` as a whole; `{}` when nothing is new). The harness resends the whole history each round, so a full body per line would repeat the conversation. `dropSession` forgets what was traced.
+- Library: a `response` line holds the reply before restore: the parsed JSON body, or for SSE the message the walker assembles in the protocol's non-streamed shape (Anthropic text, thinking, redacted thinking and `tool_use` blocks with parsed `input`; OpenAI chat `chat.completion` with content, reasoning and tool calls; OpenAI responses the final `response` object). The SSE bytes to the client are the same with or without a trace. A stream that ends before a complete reply still gets its line, with no `content`. A non-2xx reply gives an `error` line with the status and the body cut to 4096 characters; an unreachable upstream gives `status: 502` and the fetch error.
+- Library: `createFileTraceSink({ dir, maxChars? })` appends one JSON line per event to `<dir>/<sessionId>.jsonl` (an id outside `[A-Za-z0-9_-]{1,128}` becomes `sha256-<32 hex>`). The directory is created with mode 0700, files with 0600: they hold exactly the leaks the trace is meant to find. `serializeTraceEvent(event, maxChars?)` is the line format; `content` whose JSON is longer than `maxChars` (default `DEFAULT_TRACE_MAX_CHARS`, 262144) becomes that JSON text cut to `maxChars`, with `truncated: true`.
+- Library: trace lines name the route: `anthropic.messages`, `anthropic.count_tokens`, `openai.chat` or `openai.responses`.
+- Library: an always-on leak check scans every string value of the rewritten body, including fields no transform sees (`tools`, metadata, unknown fields), for known originals: the session's facts (source = publisher id) and the originals the pipeline has already replaced (`Transform.knownOriginals`, source `pipeline`). A value that one place replaced but another sends in clear text (a name in a tool description, or one the detector missed in a new context) is otherwise invisible. Matching is case-sensitive; values shorter than 3 characters are skipped (chance hits). A finding logs `log.warn('transform proxy: known original sent upstream', { sessionId, route, leaks })` with kind, source and JSON path of each finding, never the value, and goes into the `request` line's `leaks`. The request is still sent: the check warns, it does not block.
+- Library: `Transform.knownOriginals?()` returns the originals an instance has already replaced in this session, each with its kind (forge-anon: its mapping). Without connectors (omp) there are no facts, so the leak check needs these to compare against. `composeTransforms` returns the union of all stages; a stage whose `knownOriginals()` throws is logged and skipped. The values are used only by the leak check and never sent or logged.
+- Config: top-level key `trace: { dir, maxChars? }` in `transform-proxy.yaml`; `dir` resolves against the config file's directory, `maxChars` must be a positive integer.
+- CLI: `--trace-dir <dir>` (relative to the cwd) turns the file trace on; `SKAILE_TRANSFORM_PROXY_TRACE_DIR` (relative to the cwd) overrides the flag and the config's `trace.dir`. With a trace, the CLI prints `[transform-proxy info] trace: <dir>` on stderr at start.
+- CLI, **behaviour change**: log lines print non-string arguments as JSON (`JSON.stringify`) instead of `String(arg)`, so the leak warning reads `[transform-proxy warn] transform proxy: known original sent upstream {"sessionId":"…","route":"…","leaks":[…]}` instead of `[object Object]`. Anything that parses the proxy's stderr sees JSON where it saw `[object Object]` before.
+- omp extension: `/anon status` shows `trace: <dir>` or `trace: off`. The own proxy child inherits `SKAILE_TRANSFORM_PROXY_TRACE_DIR`; without it, the status shows the config's `trace.dir`. With an external proxy (`SKAILE_TRANSFORM_PROXY_URL`) only the env var is known.
+- omp extension: the extension keeps reading its proxy child's stderr after `listening <url>` (before, it dropped it) and turns each leak warning into a warning notice, once per session and kind for the child's life: `anon: a known <kind> value was sent to the provider in clear text (at <path>, route <route>). Value not shown.` Before, the warning was lost, and repeating it every round would flood the UI.
+
 ## 0.4.0
 
 - Library: `TransformProxy.inspect(sessionId, pipelineId?)` returns host-only transform state, `{ <transformId>: state }` for each stage of the session's pipeline instance (default `defaultPipeline`) that implements the new optional `Transform.inspect?()`. A host such as anon-ai reads forge-anon's mapping through it to show what was anonymized. It is in-process only (no HTTP route, never sent), returns `{}` for an unknown session, an unbuilt pipeline or a failed build, and never builds an instance or creates session state.

package/README.md

@@ -53,20 +53,25 @@ pipelines:
 defaultPipeline: anon
 allowUpstreams:            # optional; default: any https origin, plus loopback http
   - https://api.anthropic.com
+trace:                    # optional; see "Trace"
+  dir: anon-traces        # relative to this file's directory
+  maxChars: 262144        # optional; positive integer, default 262144
 ```
 
-Keys are exactly the option fields. An unknown top-level key is an error. Module specifiers resolve against the config file's directory.
+Keys are exactly the option fields, except `trace`, which configures the CLI's file sink (see [Trace](#trace)). An unknown top-level key, or an unknown key under `trace`, is an error. Module specifiers resolve against the config file's directory.
 
 ## CLI
 
 ```sh
-skaile-transform-proxy [--config <file>] [--port <n>] [--host <h>] [--token <t>] [--exit-with-stdin]
+skaile-transform-proxy [--config <file>] [--port <n>] [--host <h>] [--token <t>] [--trace-dir <dir>] [--exit-with-stdin]
 ```
 
 - The token comes from `--token` or `SKAILE_TRANSFORM_PROXY_TOKEN`.
 - Without `--config`, the proxy reads `./.skaile/transform-proxy.yaml`, then `~/.config/skaile/transform-proxy.yaml`.
 - On start it prints `listening <url>`. It stops on SIGINT or SIGTERM.
 - `--exit-with-stdin` also stops it when its stdin closes. A parent process that spawns the proxy with a stdin pipe and never writes to it takes the proxy down when it exits, even on SIGKILL.
+- `--trace-dir <dir>` (relative to the cwd) writes the [trace](#trace) there; `SKAILE_TRANSFORM_PROXY_TRACE_DIR` overrides it. With a trace, the CLI prints `[transform-proxy info] trace: <dir>` on stderr at start.
+- Warnings and errors go to stderr as `[transform-proxy warn] <message>` / `[transform-proxy error] <message>`, followed by each argument: strings as they are, everything else as JSON.
 
 ## Library
 
@@ -87,6 +92,65 @@ await proxy.close()
 
 `await proxy.inspect('s1')` lets the host read what the session's transforms hold, e.g. forge-anon's mapping for highlights: `{ <transformId>: state }`, one entry per stage of the pipeline (`inspect('s1', 'anon')`; default `defaultPipeline`) whose `Transform` implements `inspect()`. It is in-process only: there is no HTTP route, and the result is never sent anywhere. An unknown session, a pipeline that has not been built for the session yet, or a failed build gives `{}`; `inspect` never builds an instance or creates session state.
 
+`trace: createFileTraceSink({ dir })` in the options turns on the [trace](#trace). Any object with a synchronous `record(event: TraceEvent)` is a `TraceSink`.
+
+## Trace
+
+The trace records what the proxy sends to the provider **after** the pipeline, and what the model answers **before** restore. It exists to check that no clear-text personal data reaches the provider.
+
+Turn it on in one of three places; the first that is set wins:
+
+1. `SKAILE_TRANSFORM_PROXY_TRACE_DIR=<dir>` (relative to the cwd; an empty value counts as unset)
+2. `--trace-dir <dir>` (relative to the cwd)
+3. `trace: { dir, maxChars? }` in `transform-proxy.yaml` (`dir` relative to the config file)
+
+`maxChars` comes from the config only. In the library, pass `trace: createFileTraceSink({ dir, maxChars? })`, or any `TraceSink`.
+
+`createFileTraceSink` writes one file per session, `<dir>/<sessionId>.jsonl`, and appends one JSON line per event. A session id outside `[A-Za-z0-9_-]{1,128}` becomes `sha256-` plus the first 32 hex characters of its sha256. The directory is created with mode 0700, the files with 0600. A sink that throws is logged (`transform proxy: trace sink failed: <msg>`) and does not change what the client gets.
+
+Each proxied request on a wire route (`…/messages`, `…/messages/count_tokens`, `…/chat/completions`, `…/responses`) gives one `request` line, then exactly one `response` or `error` line. `GET …/models` is not traced. A line (`TraceEvent`) has these fields:
+
+| Field | Content |
+|---|---|
+| `at` | ISO timestamp. |
+| `requestId` | Random UUID per proxied request; links its request and response/error lines. |
+| `sessionId` | The proxy session. |
+| `pipeline` | The pipeline id. |
+| `route` | `anthropic.messages`, `anthropic.count_tokens`, `openai.chat` or `openai.responses`. |
+| `upstream` | The forward target, origin + path, without the query string. |
+| `model` | The request body's `model`, when it is a string. |
+| `phase` | `request`, `response` or `error`. |
+| `status` | response/error: the HTTP status (502 when the upstream was unreachable). |
+| `durationMs` | response/error: milliseconds since the request line. |
+| `content` | See below. |
+| `truncated` | `true` when `content` was cut. |
+| `leaks` | request: the [leak check](#leak-check) findings (`[]` when none); response/error: `[]`. |
+
+`content` by phase:
+
+- `request`: only the delta, an object keyed by JSON path, e.g. `{ "messages[4]": {…}, "system": […], "tools": […] }`. Each element of `messages` and `input` is one entry (`messages[i]`, `input[i]`); every other top-level key of the rewritten body is one entry as a whole. An entry is written once per session: the proxy keeps a sha256 of each written entry, and a later request writes only the entries it has not seen, `{}` when nothing is new. Harnesses resend the whole history every round, so round two shows only the new turn. A harness that changes an earlier message (omp strips thinking blocks, for example) makes that message show up again. Placeholders are stable per session, so the hashes are too. `dropSession` forgets the hashes with the rest of the session.
+- `response`: the reply before restore. A JSON reply is the parsed body. An SSE reply is the message the walker assembles from the stream, in the protocol's non-streamed shape: an Anthropic `message` with its text, thinking and `tool_use` blocks (`input` parsed from the streamed JSON), an OpenAI `chat.completion` with content, `reasoning_content` and `tool_calls`, or the `response` object of the final OpenAI responses event. The SSE bytes the client gets are the same with or without a trace. A stream that ends before a complete reply has no `content`.
+- `error`: a non-2xx reply's body as text, cut to 4096 characters, or the fetch error when the upstream was unreachable.
+
+When the JSON of `content` is longer than `maxChars` (default 262144, `DEFAULT_TRACE_MAX_CHARS`), `content` becomes that JSON text cut to `maxChars`, and `truncated` is `true`. `serializeTraceEvent(event, maxChars?)` gives the line without the trailing newline.
+
+### Leak check
+
+The leak check runs on every request on a wire route, with or without a trace. After the pipeline has rewritten the request, it scans every string value of the whole body, fields no transform sees included (`tools`, metadata, unknown fields), for known originals:
+
+- the session's facts, with the publisher id as `source`;
+- the originals the pipeline has already replaced in this session (`Transform.knownOriginals()`, e.g. forge-anon's mapping), with `source` `pipeline`. Without connectors (omp) there are no facts, so these are what the check compares against: a name that the transform replaced in one place and that appears in clear text in another, in a tool description or in a context the detector missed.
+
+Matching is case-sensitive and by substring; values shorter than 3 characters are skipped, because they match by chance. Object keys are not scanned. Each finding has `kind`, `source` and `at` (the JSON path, e.g. `tools[0].description`), once per kind, source and path. A request with findings logs
+
+```text
+transform proxy: known original sent upstream { sessionId, route, leaks: [{ kind, source, at }] }
+```
+
+as a warning (the CLI prints `[transform-proxy warn] transform proxy: known original sent upstream {"sessionId":"…","route":"…","leaks":[…]}`), and the findings go into the request line's `leaks`. The warning never contains the value. The request is still sent: the check warns, it does not block.
+
+Trace files contain exactly the leaks they are meant to find, in clear text. Keep them local, never commit them, and delete them once reviewed.
+
 ## omp extension
 
 The package ships an [omp](https://omp.sh) extension (subpath `@skaile/transform-proxy/omp`, declared in the package manifest under `omp.extensions`):
@@ -117,7 +181,8 @@ statusLine:
 - While anon is on or in error, images are not sent: the extension sets omp's `images.blockImages` in omp's in-memory runtime settings layer, and omp replaces every image in the request, history included, with the note `Image reading is disabled.`. The proxy cannot anonymize images and refuses every request that carries one (400 `unsupported_content`), and omp resends the whole history each turn, so a single screenshot would otherwise block the session. `/anon off` drops the override, so your own `images.blockImages` setting applies again; the override is never written to `config.yml`. An omp without this settings API gets a warning instead, and the proxy keeps refusing images.
 - The proxy session follows the root omp session: on `/new`, `/resume`, `/fork` (`session_switch`) and on a root `session_start` with a new session id, every provider is re-routed with the new `x-skaile-transform-session`. The proxy keeps the old session's state in memory until it exits; no request carries that id again. A `session_start` of a headless `print` session (how omp runs subagents) keeps the parent's id, so subagents share its pseudonyms.
 - `/anon off` restores the original base URLs and headers.
-- `/anon status` shows the state, the proxy URL and its source, the pipeline, the session id, whether images are blocked, and the routed and refused providers.
+- `/anon status` shows the state, the proxy URL and its source, the pipeline, the session id, the trace target (`trace: <dir>` or `trace: off`), whether images are blocked, and the routed and refused providers. The own proxy child inherits `SKAILE_TRANSFORM_PROXY_TRACE_DIR` with the rest of omp's environment, so the [trace](#trace) is on when that variable is set (shown resolved against the cwd) or when the config sets `trace.dir`. With an external proxy (`SKAILE_TRANSFORM_PROXY_URL`) only the variable is known; the status shows `trace: off` without it, whatever that proxy does.
+- The extension keeps reading its proxy child's stderr after `listening <url>`. Each [leak warning](#leak-check) becomes a warning notice, once per session and kind while the child lives, so a leak in the history does not repeat every round: `anon: a known <kind> value was sent to the provider in clear text (at <path>, route <route>). Value not shown.` Leak warnings of an external proxy stay in that proxy's log.
 - `/anon on` and `/anon off` switch only the omp process they run in: that window, its subagents, and the sessions it opens with `/new`, `/resume` and `/fork`. Other omp windows are not touched, and the saved default does not change.
 - `/anon on --global` and `/anon off --global` also save the default for omp processes started later, in `skaile-transform-proxy.json` in omp's agent dir (`~/.omp/agent`; `SKAILE_TRANSFORM_PROXY_OMP_STATE` overrides the path). A session start applies a saved `on` until the first successful `/anon on|off` in that process; from then on the process follows its own choice. A failed `/anon on --global` saves nothing.
 - `SKAILE_TRANSFORM_PROXY_MODE=required` (set by a skaile session in required mode) turns routing on at session start and refuses `/anon off`.
@@ -130,7 +195,8 @@ A module default-exports a `TransformModule`:
 
 - `open(config, { baseDir, log })` runs once per proxy. It validates the config and builds shared state. Throwing rejects startup.
 - It returns a `TransformFactory`, which runs once per `(session, pipeline)`: `(ctx: { sessionId, facts, log }) => Transform`.
-- A `Transform` has `instruction?`, `outbound(text, leaf)`, `inbound(text)`, `inboundStream()`, `dispose?()` and `inspect?()` (host-only state, read through `proxy.inspect`; the walkers never call it).
+- A `Transform` has `instruction?`, `outbound(text, leaf)`, `inbound(text)`, `inboundStream()`, `dispose?()`, `inspect?()` (host-only state, read through `proxy.inspect`; the walkers never call it) and `knownOriginals?()`.
+- `knownOriginals?(): Iterable<{ kind, value }>` returns the originals the instance has already replaced in this session, each with its kind (forge-anon: its mapping). Only the [leak check](#leak-check) reads them, as source `pipeline`; the values are never sent or logged. `composeTransforms` returns the union of all stages that implement it; a stage that throws is logged and skipped.
 
 The Anthropic walker appends the pipeline `instruction` after the host's system prompt: a string `system` gets it after a blank line, a block array gets it as one more text block at the end, and an absent `system` becomes the instruction. The host's leading blocks stay first, because Claude Code gateways (TeamClaude) refuse Sonnet requests with 429 `rate_limit_error` when the system prompt does not start with the Claude Code blocks. The OpenAI walkers still put the instruction first: a leading `system` message in chat completions, a prefix of `instructions` in responses.
 
@@ -145,4 +211,6 @@ Connectors publish facts through `proxy.session(id).publisher(source)`. Facts ar
 - The default host is `127.0.0.1`. Set a token before binding elsewhere.
 - Use `allowUpstreams` to limit where requests can go.
 - Clear text never leaves the proxy in a transformed field. Auth headers are relayed, not logged.
-- Mappings, facts and the signature cache are kept in memory and are lost on restart.
+- Fields the walkers do not rewrite (`tools`, metadata, unknown fields) are forwarded as they are. The [leak check](#leak-check) warns when one of them carries a known original; it does not block the request.
+- Leak warnings carry kind, source and JSON path, never the value. Trace files and any other `TraceSink` get the clear text that leaked: keep them local, never commit them, delete them once reviewed.
+- Mappings, facts, the signature cache and the trace hashes are kept in memory and are lost on restart.

package/dist/cli.d.mts

@@ -1,6 +1,8 @@
-import { i as TransformProxy } from "./server-CicvlQ7q.mjs";
+import { i as TransformProxy } from "./server-DdXMr4yF.mjs";
 /** Environment variable that supplies the client token when `--token` is absent. */
 export declare const TOKEN_ENV = "SKAILE_TRANSFORM_PROXY_TOKEN";
+/** Environment variable with the trace directory (relative to cwd); overrides `--trace-dir` and the config's `trace.dir`. */
+export declare const TRACE_DIR_ENV = "SKAILE_TRANSFORM_PROXY_TRACE_DIR";
 export interface CliEnvironment {
   readonly cwd: string;
   readonly home: string;

package/dist/cli.mjs

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
-import { d as createTransformProxy, o as resolveProxyConfig, v as errorMessage } from "./config-Ceb5AF_a.mjs";
+import { d as createTransformProxy, o as resolveProxyConfig, p as createFileTraceSink, x as errorMessage } from "./config-DHxYF3Tv.mjs";
 import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { parseArgs } from "node:util";
 // src/cli.ts
 /** Environment variable that supplies the client token when `--token` is absent. */
 const TOKEN_ENV = "SKAILE_TRANSFORM_PROXY_TOKEN";
-const USAGE = "usage: skaile-transform-proxy [--config <file>] [--port <n>] [--host <h>] [--token <t>] [--exit-with-stdin]";
+/** Environment variable with the trace directory (relative to cwd); overrides `--trace-dir` and the config's `trace.dir`. */
+const TRACE_DIR_ENV = "SKAILE_TRANSFORM_PROXY_TRACE_DIR";
+const USAGE = "usage: skaile-transform-proxy [--config <file>] [--port <n>] [--host <h>] [--token <t>] [--trace-dir <dir>] [--exit-with-stdin]";
 /** Parses the arguments, loads the config and starts the proxy. Never installs signal handlers. */
 async function runCli(argv, io) {
 	let values;
@@ -20,6 +23,7 @@ async function runCli(argv, io) {
 				port: { type: "string" },
 				host: { type: "string" },
 				token: { type: "string" },
+				"trace-dir": { type: "string" },
 				help: {
 					type: "boolean",
 					short: "h"
@@ -52,9 +56,12 @@ async function runCli(argv, io) {
 		io.stderr(errorMessage(err));
 		return { code: 1 };
 	}
+	const { trace: traceConfig, ...proxyOptions } = config.options;
+	const envTraceDir = io.env[TRACE_DIR_ENV];
+	const traceDir = envTraceDir !== void 0 && envTraceDir !== "" ? resolve(io.cwd, envTraceDir) : values["trace-dir"] !== void 0 ? resolve(io.cwd, values["trace-dir"]) : traceConfig?.dir;
 	try {
 		const proxy = await createTransformProxy({
-			...config.options,
+			...proxyOptions,
 			host: values.host,
 			port,
 			token: values.token ?? io.env["SKAILE_TRANSFORM_PROXY_TOKEN"],
@@ -63,8 +70,13 @@ async function runCli(argv, io) {
 				info: () => {},
 				warn: (msg, ...args) => io.stderr(format("warn", msg, args)),
 				error: (msg, ...args) => io.stderr(format("error", msg, args))
-			}
+			},
+			...traceDir === void 0 ? {} : { trace: createFileTraceSink({
+				dir: traceDir,
+				maxChars: traceConfig?.maxChars
+			}) }
 		});
+		if (traceDir !== void 0) io.stderr(format("info", `trace: ${traceDir}`, []));
 		io.stdout(`listening ${proxy.url}`);
 		return {
 			code: 0,
@@ -82,7 +94,7 @@ function parsePort(value) {
 	return port <= 65535 ? port : void 0;
 }
 function format(level, msg, args) {
-	return [`[transform-proxy ${level}] ${msg}`, ...args.map(String)].join(" ");
+	return [`[transform-proxy ${level}] ${msg}`, ...args.map((arg) => typeof arg === "string" ? arg : JSON.stringify(arg))].join(" ");
 }
 /** True when this module is the executed entry point (the bin, or `bun src/cli.ts`). */
 function isEntryPoint() {
@@ -123,4 +135,4 @@ if (isEntryPoint()) {
 		}
 	}
 }
-export { TOKEN_ENV, runCli };
+export { TOKEN_ENV, TRACE_DIR_ENV, runCli };

package/dist/{config-Ceb5AF_a.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";
@@ -1433,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] ?? [];
@@ -1481,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;
@@ -1512,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,
@@ -1526,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));
 			}
@@ -1548,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) => {
@@ -1613,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`);
@@ -1748,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) {
@@ -1768,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) {
@@ -1792,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;
@@ -1803,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 };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { _ as TransformModule, a as TransformProxyOptions, c as TransformSpec, d as SessionFactPublisher, f as SessionFacts, g as TransformFactory, h as Transform, i as TransformProxy, l as Logger, m as TextLeafKind, n as SESSION_HEADER, o as UPSTREAM_HEADER, p as TextLeaf, r as TOKEN_HEADER, s as createTransformProxy, t as PIPELINE_HEADER, u as SessionFact, v as TransformSessionContext } from "./server-CicvlQ7q.mjs";
+import { _ as TraceSink, a as TransformProxyOptions, b as TransformModule, c as TransformSpec, d as SessionFactPublisher, f as SessionFacts, g as TraceLeak, h as TraceEvent, i as TransformProxy, l as Logger, m as TextLeafKind, n as SESSION_HEADER, o as UPSTREAM_HEADER, p as TextLeaf, r as TOKEN_HEADER, s as createTransformProxy, t as PIPELINE_HEADER, u as SessionFact, v as Transform, x as TransformSessionContext, y as TransformFactory } from "./server-DdXMr4yF.mjs";
 /** One stage's streamed inbound transformer, as returned by `Transform.inboundStream()`. */
 interface InboundStream {
   push(chunk: string): string;
@@ -26,6 +26,11 @@ interface ProxyConfig {
   readonly pipelines: Record<string, readonly string[]>;
   readonly defaultPipeline?: string;
   readonly allowUpstreams?: readonly string[];
+  /** Trace file sink; `dir` is absolute (resolved against `baseDir`). */
+  readonly trace?: {
+    readonly dir: string;
+    readonly maxChars?: number;
+  };
 }
 interface ResolvedProxyConfig {
   readonly path: string;
@@ -50,6 +55,18 @@ export declare function resolveProxyConfig(lookup: ConfigLookup): ResolvedProxyC
 export declare function loadProxyConfig(path: string): ProxyConfig;
 /** Validates an already-parsed config object. Exported for hosts that load YAML themselves. */
 export declare function parseProxyConfig(source: unknown, baseDir: string): ProxyConfig;
+export declare const DEFAULT_TRACE_MAX_CHARS = 262144;
+/**
+ * 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.
+ */
+export declare function serializeTraceEvent(event: TraceEvent, maxChars?: number): string;
+interface FileTraceSinkOptions {
+  readonly dir: string;
+  readonly maxChars?: number;
+}
+/** Appends each event to `<dir>/<session>.jsonl`. The files hold whatever leaked, so they are owner-only. */
+export declare function createFileTraceSink(options: FileTraceSinkOptions): TraceSink;
 interface WireContext {
   /** The session's composed pipeline. */
   readonly transform: Transform;
@@ -58,6 +75,13 @@ interface WireContext {
    * Walkers namespace their keys (`anthropic:<signature>`, `responses:<itemId>`).
    */
   readonly signatures: Map<string, string>;
+  /**
+   * Called by a stream transformer once, on `flush`, with the model's complete reply as it came
+   * from the provider (placeholders, before restore), in the shape of the protocol's non-streamed
+   * response. A throw is the caller's problem: transformers must catch it so the stream is never
+   * disturbed. Absent = nobody records the reply; walkers skip the assembly work.
+   */
+  readonly observe?: (message: unknown) => void;
 }
 /** Thrown by `request` for attachments (image, document, file parts); the server answers 400 `unsupported_content`. */
 export declare class UnsupportedContentError extends Error {
@@ -85,4 +109,4 @@ interface WireWalker {
 export declare const anthropicWalker: WireWalker;
 export declare const openaiChatWalker: WireWalker;
 export declare const openaiResponsesWalker: WireWalker;
-export { type ConfigLookup, type InboundStream, type Logger, PIPELINE_HEADER, type ProxyConfig, type ResolvedProxyConfig, SESSION_HEADER, type SessionFact, type SessionFactPublisher, type SessionFactStore, type SessionFacts, type SseTransformer, TOKEN_HEADER, type TextLeaf, type TextLeafKind, type Transform, type TransformFactory, type TransformModule, type TransformProxy, type TransformProxyOptions, type TransformSessionContext, type TransformSpec, UPSTREAM_HEADER, type WireContext, type WireWalker, createTransformProxy };
+export { type ConfigLookup, type FileTraceSinkOptions, type InboundStream, type Logger, PIPELINE_HEADER, type ProxyConfig, type ResolvedProxyConfig, SESSION_HEADER, type SessionFact, type SessionFactPublisher, type SessionFactStore, type SessionFacts, type SseTransformer, TOKEN_HEADER, type TextLeaf, type TextLeafKind, type TraceEvent, type TraceLeak, type TraceSink, type Transform, type TransformFactory, type TransformModule, type TransformProxy, type TransformProxyOptions, type TransformSessionContext, type TransformSpec, UPSTREAM_HEADER, type WireContext, type WireWalker, createTransformProxy };

package/dist/index.mjs

@@ -1 +1 @@
-export { t as CONFIG_FILE_NAME, s as PIPELINE_HEADER, c as SESSION_HEADER, l as TOKEN_HEADER, u as UPSTREAM_HEADER, h as UnsupportedContentError, m as anthropicWalker, _ as composeTransforms, n as configCandidates, g as createSessionFacts, d as createTransformProxy, r as findProxyConfig, i as loadProxyConfig, p as openaiChatWalker, f as openaiResponsesWalker, a as parseProxyConfig, o as resolveProxyConfig, y as silentLogger } from "./config-Ceb5AF_a.mjs";
+export { t as CONFIG_FILE_NAME, f as DEFAULT_TRACE_MAX_CHARS, s as PIPELINE_HEADER, c as SESSION_HEADER, l as TOKEN_HEADER, u as UPSTREAM_HEADER, v as UnsupportedContentError, _ as anthropicWalker, b as composeTransforms, n as configCandidates, p as createFileTraceSink, y as createSessionFacts, d as createTransformProxy, r as findProxyConfig, i as loadProxyConfig, g as openaiChatWalker, h as openaiResponsesWalker, a as parseProxyConfig, o as resolveProxyConfig, m as serializeTraceEvent, S as silentLogger } from "./config-DHxYF3Tv.mjs";

package/dist/omp/index.mjs

@@ -1,7 +1,7 @@
-import { c as SESSION_HEADER, i as loadProxyConfig, l as TOKEN_HEADER, n as configCandidates, r as findProxyConfig, u as UPSTREAM_HEADER, v as errorMessage } from "../config-Ceb5AF_a.mjs";
+import { c as SESSION_HEADER, i as loadProxyConfig, l as TOKEN_HEADER, n as configCandidates, r as findProxyConfig, u as UPSTREAM_HEADER, x as errorMessage } from "../config-DHxYF3Tv.mjs";
 import { randomBytes, randomUUID } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { spawn } from "node:child_process";
@@ -16,6 +16,8 @@ const NODE_ENV = "SKAILE_TRANSFORM_PROXY_NODE";
 const MODE_ENV = "SKAILE_TRANSFORM_PROXY_MODE";
 /** Overrides the path of the saved default (`/anon on|off --global`). */
 const STATE_ENV = "SKAILE_TRANSFORM_PROXY_OMP_STATE";
+/** The proxy's trace directory (relative to the cwd); the own proxy child inherits it with the rest of the environment. */
+const TRACE_DIR_ENV = "SKAILE_TRANSFORM_PROXY_TRACE_DIR";
 /** The footer status key. */
 const STATUS_KEY = "anon";
 /** The model-registry source the proxy overrides are registered under; `/anon off` clears it in one reload. */
@@ -100,6 +102,8 @@ function createAnonController(deps) {
 	let endpoint;
 	let starting;
 	let sessionId;
+	/** The context of the latest proxy-bound hook; leak notices of the proxy child go to its UI. */
+	let uiCtx;
 	function stateOf(registry) {
 		let state = registries.get(registry);
 		if (state === void 0) {
@@ -112,6 +116,7 @@ function createAnonController(deps) {
 		return state;
 	}
 	async function resolveEndpoint(ctx) {
+		uiCtx = ctx;
 		if (endpoint !== void 0 && endpoint.child?.exited !== true) return endpoint;
 		const url = env[URL_ENV];
 		if (url !== void 0 && url !== "") {
@@ -177,12 +182,28 @@ function createAnonController(deps) {
 			url: await waitForListening(child, {
 				node,
 				token,
-				timeoutMs: listenTimeoutMs
+				timeoutMs: listenTimeoutMs,
+				onLeak: leakNotifier()
 			}),
 			token,
 			pipeline: options.defaultPipeline,
 			source: `child process ${child.pid}, config ${path}`,
-			child: state
+			child: state,
+			...options.trace === void 0 ? {} : { traceDir: options.trace.dir }
+		};
+	}
+	/** One child's leak warnings as notices: once per session and kind for the child's life, never with the value. */
+	function leakNotifier() {
+		const noticed = /* @__PURE__ */ new Set();
+		return (report) => {
+			const firstAt = /* @__PURE__ */ new Map();
+			for (const leak of report.leaks) if (!firstAt.has(leak.kind)) firstAt.set(leak.kind, leak.at);
+			for (const [kind, at] of firstAt) {
+				const key = JSON.stringify([report.sessionId, kind]);
+				if (noticed.has(key)) continue;
+				noticed.add(key);
+				uiCtx?.ui.notify(`anon: a known ${kind} value was sent to the provider in clear text (at ${at}, route ${report.route}). Value not shown.`, "warning");
+			}
 		};
 	}
 	function currentSessionId(ctx) {
@@ -335,6 +356,7 @@ function createAnonController(deps) {
 			lines.push(`pipeline: ${endpoint.pipeline ?? "the proxy default"}`);
 		}
 		if (sessionId !== void 0) lines.push(`session: ${sessionId}`);
+		lines.push(`trace: ${traceTarget(ctx.cwd)}`);
 		if (imagesBlocked) lines.push("images: not sent (omp images.blockImages)");
 		const routed = [...state.routed.keys()].sort();
 		const refused = routed.flatMap((provider) => {
@@ -347,6 +369,12 @@ function createAnonController(deps) {
 		if (preRouted.length > 0) lines.push(`routed by their own config (${preRouted.length}): ${preRouted.sort().join(", ")}`);
 		return lines.join("\n");
 	}
+	/** The proxy's trace directory, or `off`. With an external proxy only the env var is known here. */
+	function traceTarget(cwd) {
+		const fromEnv = env[TRACE_DIR_ENV];
+		if (fromEnv !== void 0 && fromEnv !== "") return resolve(cwd, fromEnv);
+		return endpoint?.traceDir ?? "off";
+	}
 	/**
 	* Session entry: rotate the proxy session for a new root, then (re-)apply routing when wanted.
 	* Rotation only switches the session header: the proxy keeps the old session's state in memory
@@ -433,6 +461,7 @@ function createAnonController(deps) {
 			if (enabled !== was) showStatus(ctx);
 		},
 		providerRequest(ctx) {
+			uiCtx = ctx;
 			if (!wanted) return void 0;
 			let reason;
 			try {
@@ -470,11 +499,45 @@ function spawnNode(command, args, options) {
 }
 /** The stderr lines a startup failure quotes. */
 const STDERR_TAIL = 10;
+/** An unterminated stderr line longer than this is dropped, so a child that never prints a newline cannot grow omp's memory. */
+const STDERR_LINE_MAX = 65536;
+/** The proxy's leak warning (`log.warn` with `{ sessionId, route, leaks }`, printed as JSON after the message). */
+const LEAK_MARKER = "transform proxy: known original sent upstream";
+/** The leak report on one stderr line of the proxy child; `undefined` for any other or malformed line. */
+function parseLeakLine(line) {
+	const index = line.indexOf(LEAK_MARKER);
+	if (index === -1) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(line.slice(index + 45));
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const { sessionId, route, leaks } = parsed;
+	if (typeof sessionId !== "string" || typeof route !== "string" || !Array.isArray(leaks)) return void 0;
+	const out = [];
+	for (const leak of leaks) {
+		if (typeof leak !== "object" || leak === null) return void 0;
+		const { kind, at } = leak;
+		if (typeof kind !== "string" || typeof at !== "string") return void 0;
+		out.push({
+			kind,
+			at
+		});
+	}
+	return out.length === 0 ? void 0 : {
+		sessionId,
+		route,
+		leaks: out
+	};
+}
 /**
 * Resolves with the URL of the child's `listening <url>` line. A child that exits first, fails
 * to spawn or stays silent past `timeoutMs` (it is then killed) rejects, quoting its last stderr
 * lines with the token redacted. omp exiting kills the child; once listening, the child and its
 * pipes no longer hold omp's event loop, and stdin stays open so the child sees omp go away.
+* After startup every leak warning on stderr goes to `onLeak`.
 */
 function waitForListening(child, how) {
 	const killOnExit = () => {
@@ -511,11 +574,21 @@ function waitForListening(child, how) {
 		child.kill("SIGKILL");
 	}, how.timeoutMs);
 	child.stderr?.on("data", (chunk) => {
-		if (settled) return;
 		const lines = (stderrPartial + String(chunk)).split("\n");
 		stderrPartial = lines.pop() ?? "";
-		tail.push(...lines.map((line) => line.replace(/\r$/, "")));
-		tail.splice(0, Math.max(0, tail.length - STDERR_TAIL));
+		if (!settled) {
+			tail.push(...lines.map((line) => line.replace(/\r$/, "")));
+			tail.splice(0, Math.max(0, tail.length - STDERR_TAIL));
+			return;
+		}
+		if (stderrPartial.length > STDERR_LINE_MAX) stderrPartial = "";
+		for (const line of lines) {
+			const report = parseLeakLine(line);
+			if (report === void 0) continue;
+			try {
+				how.onLeak(report);
+			} catch {}
+		}
 	});
 	child.stdout?.on("data", (chunk) => {
 		if (settled) return;

package/dist/{server-CicvlQ7q.d.mts → server-DdXMr4yF.d.mts}

@@ -27,6 +27,14 @@ interface Transform {
   dispose?(): void | Promise<void>;
   /** Host-only state of this instance (e.g. the anon mapping), read through TransformProxy.inspect. Never called by the walkers, never sent anywhere. */
   inspect?(): unknown;
+  /**
+   * Originals this instance has already replaced in this session (forge-anon: its mapping), each with its kind.
+   * Used only by the proxy's leak check, which reports kind and JSON path, never the value; never sent anywhere.
+   */
+  knownOriginals?(): Iterable<{
+    readonly kind: string;
+    readonly value: string;
+  }>;
 }
 interface SessionFact {
   readonly kind: string;
@@ -58,6 +66,51 @@ interface TransformModule {
     readonly log: Logger;
   }): Promise<TransformFactory>;
 }
+/** One leak-check finding. Never carries the value itself. */
+interface TraceLeak {
+  /** Fact/original kind, e.g. 'person'. */
+  readonly kind: string;
+  /** Fact source (publisher id), or 'pipeline' for `Transform.knownOriginals`. */
+  readonly source: string;
+  /** JSON path in the rewritten request body, e.g. 'tools[0].description'. */
+  readonly at: string;
+}
+/** One line of the anon trace: what left for the provider (request) or what it answered before restore (response/error). */
+interface TraceEvent {
+  /** ISO timestamp. */
+  readonly at: string;
+  /** Per proxied request; links its request/response/error lines. */
+  readonly requestId: string;
+  readonly sessionId: string;
+  readonly pipeline: string;
+  /** `WireRoute.name`, e.g. 'anthropic.messages'. */
+  readonly route: string;
+  /** Forward target origin + path, no query string. */
+  readonly upstream: string;
+  /** Request body `model` when a string. */
+  readonly model?: string;
+  readonly phase: 'request' | 'response' | 'error';
+  /** response/error: HTTP status (502 when the upstream was unreachable). */
+  readonly status?: number;
+  /** response/error: ms since the request event. */
+  readonly durationMs?: number;
+  /**
+   * request: the delta, keyed by JSON path (`{ 'messages[4]': {...}, system: [...] }`), only entries not yet traced in
+   * this session; `{}` when nothing is new.
+   * response: the model reply before restore (streamed: assembled in the protocol's non-streamed shape; `undefined` when
+   * the stream ended before a complete reply).
+   * error: the upstream error body as text, cut to 4096 chars, or the fetch error message.
+   */
+  readonly content?: unknown;
+  /** Set only by `serializeTraceEvent`. */
+  readonly truncated?: boolean;
+  /** request: leak-check findings; response/error: []. */
+  readonly leaks: readonly TraceLeak[];
+}
+/** Synchronous. The proxy catches a throw, logs it, and never lets it reach the client. */
+interface TraceSink {
+  record(event: TraceEvent): void;
+}
 /** A configured transform: a module (object, npm specifier or relative path) and its config. */
 interface TransformSpec {
   readonly module: string | TransformModule;
@@ -79,6 +132,8 @@ interface TransformProxyOptions {
   /** Origins. Absent = any https origin plus loopback http. */
   allowUpstreams?: readonly string[];
   log?: Logger;
+  /** Records what goes upstream after the pipeline and what comes back before restore. Absent = no trace. */
+  trace?: TraceSink;
 }
 interface TransformProxy {
   readonly url: string;
@@ -101,4 +156,4 @@ declare const SESSION_HEADER = "x-skaile-transform-session";
 declare const PIPELINE_HEADER = "x-skaile-transform-pipeline";
 declare const TOKEN_HEADER = "x-skaile-transform-token";
 declare function createTransformProxy(options: TransformProxyOptions): Promise<TransformProxy>;
-export { TransformModule as _, TransformProxyOptions as a, TransformSpec as c, SessionFactPublisher as d, SessionFacts as f, TransformFactory as g, Transform as h, TransformProxy as i, Logger as l, TextLeafKind as m, SESSION_HEADER as n, UPSTREAM_HEADER as o, TextLeaf as p, TOKEN_HEADER as r, createTransformProxy as s, PIPELINE_HEADER as t, SessionFact as u, TransformSessionContext as v };
+export { TraceSink as _, TransformProxyOptions as a, TransformModule as b, TransformSpec as c, SessionFactPublisher as d, SessionFacts as f, TraceLeak as g, TraceEvent as h, TransformProxy as i, Logger as l, TextLeafKind as m, SESSION_HEADER as n, UPSTREAM_HEADER as o, TextLeaf as p, TOKEN_HEADER as r, createTransformProxy as s, PIPELINE_HEADER as t, SessionFact as u, Transform as v, TransformSessionContext as x, TransformFactory as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/transform-proxy",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Same-protocol passthrough proxy that runs model requests and replies through a chain of text transforms (Anthropic Messages, OpenAI chat, OpenAI responses)",
   "license": "MIT",