@skaile/transform-proxy 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.5.1
+
+### Patch Changes
+
+- 21bab3c: The bin installs its SIGINT, SIGTERM and `--exit-with-stdin` handlers before it prints `listening`. A parent that stopped the proxy right after that line could kill it with the default signal action (exit 143) instead of a clean shutdown (exit 0). `runCli` takes an optional `onStart` callback, called after the proxy listens and before the `listening` line.
+
+## 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,7 @@ 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.
+- omp writes the request of every HTTP 400 answer to `~/.omp/logs/http-400-requests/<id>.json` (mode `0644`). That copy is what omp sent to the proxy, before anonymization, so it holds the personal data in clear text. It stays on the machine; delete it when anon is in use.

package/dist/cli.d.mts

@@ -1,12 +1,19 @@
-import { i as TransformProxy } from "./server-CicvlQ7q.mjs";
+import { i as TransformProxy } from "./server-gwJGHF82.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;
   readonly env: Readonly<Record<string, string | undefined>>;
   readonly stdout: (line: string) => void;
   readonly stderr: (line: string) => void;
+  /**
+   * Called once the proxy listens, before the `listening` line: a parent reacts to that line (with SIGTERM, or by
+   * closing stdin), so the caller's shutdown handlers must be in place by then.
+   */
+  readonly onStart?: (run: Required<CliRun>) => void;
 }
 /** `proxy` is set only when the server started; the caller owns its shutdown. */
 export interface CliRun {

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 { a as createTransformProxy, s as createFileTraceSink, x as errorMessage, y as resolveProxyConfig } from "./server-BR1dDA8S.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,14 +70,21 @@ 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
+			}) }
 		});
-		io.stdout(`listening ${proxy.url}`);
-		return {
+		if (traceDir !== void 0) io.stderr(format("info", `trace: ${traceDir}`, []));
+		const run = {
 			code: 0,
 			proxy,
 			exitWithStdin: values["exit-with-stdin"] === true
 		};
+		io.onStart?.(run);
+		io.stdout(`listening ${proxy.url}`);
+		return run;
 	} catch (err) {
 		io.stderr(errorMessage(err));
 		return { code: 1 };
@@ -82,7 +96,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() {
@@ -100,27 +114,26 @@ if (isEntryPoint()) {
 		home: homedir(),
 		env: process.env,
 		stdout: (line) => console.log(line),
-		stderr: (line) => console.error(line)
+		stderr: (line) => console.error(line),
+		onStart: ({ proxy, exitWithStdin }) => {
+			let stopping = false;
+			const stop = () => {
+				if (stopping) return;
+				stopping = true;
+				proxy.close().then(() => process.exit(0), (err) => {
+					console.error(errorMessage(err));
+					process.exit(1);
+				});
+			};
+			process.once("SIGINT", stop);
+			process.once("SIGTERM", stop);
+			if (exitWithStdin) {
+				process.stdin.once("end", stop);
+				process.stdin.once("close", stop);
+				process.stdin.resume();
+			}
+		}
 	});
 	if (run.proxy === void 0) process.exitCode = run.code;
-	else {
-		const proxy = run.proxy;
-		let stopping = false;
-		const stop = () => {
-			if (stopping) return;
-			stopping = true;
-			proxy.close().then(() => process.exit(0), (err) => {
-				console.error(errorMessage(err));
-				process.exit(1);
-			});
-		};
-		process.once("SIGINT", stop);
-		process.once("SIGTERM", stop);
-		if (run.exitWithStdin === true) {
-			process.stdin.once("end", stop);
-			process.stdin.once("close", stop);
-			process.stdin.resume();
-		}
-	}
 }
-export { TOKEN_ENV, runCli };
+export { TOKEN_ENV, TRACE_DIR_ENV, runCli };

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-gwJGHF82.mjs";
 /** One stage's streamed inbound transformer, as returned by `Transform.inboundStream()`. */
 interface InboundStream {
   push(chunk: string): string;
@@ -10,14 +10,6 @@ interface InboundStream {
  * The empty list is the identity.
  */
 export declare function composeTransforms(stages: readonly Transform[], log?: Logger): Transform;
-/** Default logger: drops everything. Hosts pass their own `Logger`. */
-export declare const silentLogger: Logger;
-/** One session's facts: the read side for transforms and the per-source publishers for connectors. */
-interface SessionFactStore {
-  readonly facts: SessionFacts;
-  publisher(source: string): SessionFactPublisher;
-}
-export declare function createSessionFacts(): SessionFactStore;
 export declare const CONFIG_FILE_NAME = "transform-proxy.yaml";
 /** The YAML-backed subset of the proxy options. `baseDir` is the config file's directory. */
 interface ProxyConfig {
@@ -26,6 +18,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 +47,26 @@ 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;
+/** One session's facts: the read side for transforms and the per-source publishers for connectors. */
+interface SessionFactStore {
+  readonly facts: SessionFacts;
+  publisher(source: string): SessionFactPublisher;
+}
+export declare function createSessionFacts(): SessionFactStore;
+/** Default logger: drops everything. Hosts pass their own `Logger`. */
+export declare const silentLogger: Logger;
+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 { m as CONFIG_FILE_NAME, o as DEFAULT_TRACE_MAX_CHARS, t as PIPELINE_HEADER, n as SESSION_HEADER, r as TOKEN_HEADER, i as UPSTREAM_HEADER, f as UnsupportedContentError, d as anthropicWalker, b as composeTransforms, h as configCandidates, s as createFileTraceSink, p as createSessionFacts, a as createTransformProxy, g as findProxyConfig, _ as loadProxyConfig, u as openaiChatWalker, l as openaiResponsesWalker, v as parseProxyConfig, y as resolveProxyConfig, c as serializeTraceEvent, S as silentLogger } from "./server-BR1dDA8S.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 { randomBytes, randomUUID } from "node:crypto";
+import { _ as loadProxyConfig, g as findProxyConfig, h as configCandidates, i as UPSTREAM_HEADER, n as SESSION_HEADER, r as TOKEN_HEADER, x as errorMessage } from "../server-BR1dDA8S.mjs";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { randomBytes, randomUUID } from "node:crypto";
 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;