@skaile/transform-proxy 0.3.1 → 0.5.0

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-C_eKyCTV.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-BZsthgP-.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-BZsthgP-.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-C_eKyCTV.d.mts → server-DdXMr4yF.d.mts}

@@ -25,6 +25,16 @@ interface Transform {
   };
   /** Called once when the proxy drops the session. */
   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;
@@ -56,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;
@@ -77,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;
@@ -86,6 +143,12 @@ interface TransformProxy {
   };
   /** Disposes the session's transform instances and forgets its facts and caches. */
   dropSession(id: string): Promise<void>;
+  /**
+   * Host-only, in-process: each stage's `inspect()` result of the session's pipeline instance, keyed by transform id.
+   * `{}` when the session or pipeline is unknown, the instance is not built, or its build failed.
+   * Never builds an instance or creates session state; there is no HTTP route for it.
+   */
+  inspect(sessionId: string, pipelineId?: string): Promise<Record<string, unknown>>;
   close(): Promise<void>;
 }
 declare const UPSTREAM_HEADER = "x-skaile-transform-upstream";
@@ -93,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.3.1",
+  "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",