@skaile/transform-proxy 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.3
+
+- omp extension: without `SKAILE_TRANSFORM_PROXY_URL`, `/anon on` starts the proxy as a child process under the system Node (`SKAILE_TRANSFORM_PROXY_NODE`, else `node` from `PATH`; Node ≥ 22) instead of inside omp. omp is a compiled Bun executable whose resolver cannot load transform modules with native or ML dependencies from `node_modules`: under omp 18.14.2, `/anon on` failed with `transform "anon": cannot load module @skaile/forge-anon/proxy: Cannot find package 'ibantools'`. The child runs this package's CLI with the found config, `--port 0 --host 127.0.0.1 --exit-with-stdin` and a random token, which every routed provider sends as `x-skaile-transform-token`. A child that exits before `listening <url>` or stays silent for 60 s fails `/anon on` with its last stderr lines (token redacted). The child exits with omp, does not keep omp's event loop alive, and is replaced on the next turn when it dies. A rotated-out proxy session is no longer dropped: the child keeps its state in memory until it exits, and no request carries that id again.
+- CLI: `--exit-with-stdin` stops the proxy when its stdin closes, so a parent that spawns it with a stdin pipe takes it down on exit, SIGKILL included.
+
 ## 0.2.2
 
 - Fail closed on malformed request bodies: the Anthropic, OpenAI chat and OpenAI responses walkers refuse a JSON body whose shape they cannot classify (a root that is not an object; a `system`, `messages`, `input`, `instructions`, message `content`, text, thinking, tool-call `arguments` or tool-result slot of an unexpected type) with 400 `unsupported_content` instead of forwarding it untransformed. Unknown part, block and item types still pass through.

package/README.md

@@ -60,12 +60,13 @@ Keys are exactly the option fields. An unknown top-level key is an error. Module
 ## CLI
 
 ```sh
-skaile-transform-proxy [--config <file>] [--port <n>] [--host <h>] [--token <t>]
+skaile-transform-proxy [--config <file>] [--port <n>] [--host <h>] [--token <t>] [--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.
 
 ## Library
 
@@ -92,15 +93,16 @@ The package ships an [omp](https://omp.sh) extension (subpath `@skaile/transform
 omp plugin install @skaile/transform-proxy
 ```
 
-It adds the command `/anon on|off|status` and the footer status `anon on`, `anon off` or `anon error`.
+It adds the command `/anon on|off|status` and the footer status `anon on`, `anon off` or `anon error`. Unless `SKAILE_TRANSFORM_PROXY_URL` names a running proxy, it needs Node ≥ 22 on `PATH` (or its path in `SKAILE_TRANSFORM_PROXY_NODE`).
 
 - `/anon on` routes every provider of omp's model registry through the proxy: the provider's `baseUrl` becomes the proxy URL, and the original base URL travels in `x-skaile-transform-upstream`, next to `x-skaile-transform-session` (the omp session id) and the token. The provider's own headers and auth stay in place and are relayed.
   - With `SKAILE_TRANSFORM_PROXY_URL` (and `SKAILE_TRANSFORM_PROXY_TOKEN`) set, it uses that running proxy, and the proxy applies its `defaultPipeline`.
-  - Otherwise it starts one proxy inside the omp process, from the config lookup of the CLI (`./.skaile/transform-proxy.yaml`, then `~/.config/skaile/transform-proxy.yaml`). That config must set `defaultPipeline`. Without a config, `/anon on` refuses and says where to put one.
+  - Otherwise it starts one proxy per omp process as a child process: the system Node (`SKAILE_TRANSFORM_PROXY_NODE`, else `node` from `PATH`) runs this package's CLI with the config lookup of the CLI (`./.skaile/transform-proxy.yaml`, then `~/.config/skaile/transform-proxy.yaml`), `--port 0 --host 127.0.0.1 --exit-with-stdin` and a random token in `SKAILE_TRANSFORM_PROXY_TOKEN`, which every routed provider sends. That config must set `defaultPipeline`. Without a config, `/anon on` refuses and says where to put one. A child that exits before printing `listening <url>`, or stays silent for 60 s, fails `/anon on` with its last stderr lines.
+  - omp is a compiled Bun executable, and its resolver cannot load transform modules with native or ML dependencies (`onnxruntime-node`, `@huggingface/transformers`, `ibantools`) from `node_modules`; Node can. The child exits with omp: its stdin pipe closes when omp exits (SIGKILL included), and omp kills it on a normal exit. It does not keep omp's event loop alive. A child that dies later is replaced on the next turn.
   - Providers on a wire the proxy does not rewrite (Bedrock, Vertex, Gemini, agent bridges, providers without a base URL) are routed too, so the proxy refuses their requests: the setup fails closed. `/anon status` lists them as refused.
   - The session's active model is rebound to the re-routed one, so the next request already uses the new base URL. A rebind that fails is an activation failure: `/anon on` rolls the routes back, saves nothing and stays off. When anon is required, or a later turn's rebind fails while anon is on, the footer shows `anon error`.
 - While anon is on or in error, a `before_provider_request` handler checks every model request: a request whose model does not target the proxy gets its payload replaced with an empty object, so no conversation text leaves, and an error notice names the model. omp has no hook that cancels a provider request, and a throwing handler is only logged, so this replacement is the block.
-- 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`, and the in-process proxy drops the old session. A `session_start` of a headless `print` session (how omp runs subagents) keeps the parent's id, so subagents share its pseudonyms.
+- 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, and the routed and refused providers.
 - The enabled flag is saved in `skaile-transform-proxy.json` in omp's agent dir (`~/.omp/agent`; `SKAILE_TRANSFORM_PROXY_OMP_STATE` overrides the path) and re-applied when a session starts.

package/dist/cli.d.mts

@@ -12,6 +12,8 @@ export interface CliEnvironment {
 export interface CliRun {
   readonly code: number;
   readonly proxy?: TransformProxy;
+  /** `--exit-with-stdin`: the caller stops the proxy when its stdin closes (the parent process is gone). */
+  readonly exitWithStdin?: boolean;
 }
 /** Parses the arguments, loads the config and starts the proxy. Never installs signal handlers. */
 export declare function runCli(argv: readonly string[], io: CliEnvironment): Promise<CliRun>;

package/dist/cli.mjs

@@ -7,7 +7,7 @@ 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>]";
+const USAGE = "usage: skaile-transform-proxy [--config <file>] [--port <n>] [--host <h>] [--token <t>] [--exit-with-stdin]";
 /** Parses the arguments, loads the config and starts the proxy. Never installs signal handlers. */
 async function runCli(argv, io) {
 	let values;
@@ -23,7 +23,8 @@ async function runCli(argv, io) {
 				help: {
 					type: "boolean",
 					short: "h"
-				}
+				},
+				"exit-with-stdin": { type: "boolean" }
 			}
 		}));
 	} catch (err) {
@@ -67,7 +68,8 @@ async function runCli(argv, io) {
 		io.stdout(`listening ${proxy.url}`);
 		return {
 			code: 0,
-			proxy
+			proxy,
+			exitWithStdin: values["exit-with-stdin"] === true
 		};
 	} catch (err) {
 		io.stderr(errorMessage(err));
@@ -103,7 +105,10 @@ if (isEntryPoint()) {
 	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);
@@ -111,6 +116,11 @@ if (isEntryPoint()) {
 		};
 		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 };

package/dist/omp/index.d.mts

@@ -1,4 +1,4 @@
-import { a as TransformProxyOptions, i as TransformProxy } from "../server-C_eKyCTV.mjs";
+import { Readable, Writable } from "node:stream";
 interface OmpModel {
   readonly provider: string;
   readonly id: string;
@@ -67,13 +67,34 @@ interface OmpExtensionApi extends OmpSessionActions {
   /** For `before_provider_request`, a non-undefined result replaces the request payload. */
   on(event: OmpEventName, handler: (event: unknown, ctx: OmpContext) => unknown): void;
 }
+/** How the extension spawns its proxy child. */
+interface ProxySpawnOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly stdio: readonly ['pipe', 'pipe', 'pipe'];
+}
+/** The slice of a `node:child_process` `ChildProcess` the extension uses. */
+interface ProxyChildProcess {
+  readonly pid?: number | undefined;
+  readonly stdin: Writable | null;
+  readonly stdout: Readable | null;
+  readonly stderr: Readable | null;
+  kill(signal?: NodeJS.Signals): boolean;
+  unref(): void;
+  on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+  on(event: 'error', listener: (err: Error) => void): unknown;
+}
 interface AnonControllerDeps {
   readonly env: Readonly<Record<string, string | undefined>>;
   readonly home: string;
   /** Default: `$SKAILE_TRANSFORM_PROXY_OMP_STATE`, else `<omp agent dir>/skaile-transform-proxy.json`. */
   readonly statePath?: string;
-  /** Default: `createTransformProxy`. */
-  readonly startProxy?: (options: TransformProxyOptions) => Promise<TransformProxy>;
+  /** Spawns the proxy child. Default: `node:child_process` `spawn`. */
+  readonly spawnChild?: (command: string, args: readonly string[], options: ProxySpawnOptions) => ProxyChildProcess;
+  /** The CLI the child runs. Default: this package's `dist/cli.mjs`, next to the built extension's `dist/omp/`. */
+  readonly cliPath?: string;
+  /** How long the child may take to print `listening <url>`. Default: 60 s (transform modules may load ML models). */
+  readonly listenTimeoutMs?: number;
 }
 interface AnonController {
   readonly required: boolean;
@@ -112,4 +133,4 @@ export declare function defaultStatePath(env: Readonly<Record<string, string | u
 /** Registers the `/anon` command and the event handlers on one session's extension API. */
 export declare function registerAnonExtension(pi: OmpExtensionApi, controller: AnonController): void;
 export default function anonExtension(pi: OmpExtensionApi): void;
-export type { AnonController, AnonControllerDeps, OmpAutocompleteItem, OmpContext, OmpEventName, OmpExtensionApi, OmpModel, OmpModelRegistry, OmpNotifyType, OmpProviderOverride, OmpSessionActions, OmpUi };
+export type { AnonController, AnonControllerDeps, OmpAutocompleteItem, OmpContext, OmpEventName, OmpExtensionApi, OmpModel, OmpModelRegistry, OmpNotifyType, OmpProviderOverride, OmpSessionActions, OmpUi, ProxyChildProcess, ProxySpawnOptions };

package/dist/omp/index.mjs

@@ -1,13 +1,17 @@
-import { c as SESSION_HEADER, d as createTransformProxy, i as loadProxyConfig, l as TOKEN_HEADER, n as configCandidates, r as findProxyConfig, u as UPSTREAM_HEADER, v as errorMessage, y as silentLogger } from "../config-PKHxejC8.mjs";
-import { randomUUID } from "node:crypto";
+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-PKHxejC8.mjs";
+import { randomBytes, randomUUID } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+import { spawn } from "node:child_process";
 // src/omp/anon.ts
 /** A running proxy the extension routes to. */
 const URL_ENV = "SKAILE_TRANSFORM_PROXY_URL";
-/** The client token of that proxy. */
+/** The client token of that proxy; also how the extension hands its own proxy child a random token. */
 const TOKEN_ENV = "SKAILE_TRANSFORM_PROXY_TOKEN";
+/** The Node binary that runs the proxy child; default: `node` from `PATH`. */
+const NODE_ENV = "SKAILE_TRANSFORM_PROXY_NODE";
 /** `required` (set by a skaile session in required mode): routing is forced on and `/anon off` is refused. */
 const MODE_ENV = "SKAILE_TRANSFORM_PROXY_MODE";
 /** Overrides the path of the persisted enabled flag. */
@@ -53,7 +57,8 @@ function createAnonController(deps) {
 	const env = deps.env;
 	const required = env[MODE_ENV] === "required";
 	const statePath = deps.statePath ?? defaultStatePath(env, deps.home);
-	const startProxy = deps.startProxy ?? createTransformProxy;
+	const spawnChild = deps.spawnChild ?? spawnNode;
+	const listenTimeoutMs = deps.listenTimeoutMs ?? 6e4;
 	const registries = /* @__PURE__ */ new WeakMap();
 	let wanted = required;
 	let enabled = false;
@@ -72,7 +77,7 @@ function createAnonController(deps) {
 		return state;
 	}
 	async function resolveEndpoint(ctx) {
-		if (endpoint !== void 0) return endpoint;
+		if (endpoint !== void 0 && endpoint.child?.exited !== true) return endpoint;
 		const url = env[URL_ENV];
 		if (url !== void 0 && url !== "") {
 			const token = env[TOKEN_ENV];
@@ -83,13 +88,17 @@ function createAnonController(deps) {
 			};
 			return endpoint;
 		}
-		starting ??= startInProcess(ctx.cwd).finally(() => {
+		starting ??= startChild(ctx.cwd).finally(() => {
 			starting = void 0;
 		});
 		endpoint = await starting;
 		return endpoint;
 	}
-	async function startInProcess(cwd) {
+	/**
+	* Runs the proxy CLI under the system Node: omp is a compiled Bun executable whose resolver
+	* cannot load transform modules with native or ML dependencies from `node_modules`.
+	*/
+	async function startChild(cwd) {
 		const path = findProxyConfig({
 			cwd,
 			home: deps.home
@@ -100,15 +109,45 @@ function createAnonController(deps) {
 		}
 		const options = loadProxyConfig(path);
 		if (options.defaultPipeline === void 0) throw new Error(`${path} sets no defaultPipeline: the omp extension sends no pipeline header`);
-		const proxy = await startProxy({
-			...options,
-			log: silentLogger
+		const token = randomBytes(32).toString("base64url");
+		const node = env["SKAILE_TRANSFORM_PROXY_NODE"] || "node";
+		const cli = deps.cliPath ?? fileURLToPath(new URL("../cli.mjs", import.meta.url));
+		const child = spawnChild(node, [
+			cli,
+			"--config",
+			path,
+			"--port",
+			"0",
+			"--host",
+			"127.0.0.1",
+			"--exit-with-stdin"
+		], {
+			cwd,
+			env: {
+				...env,
+				[TOKEN_ENV]: token
+			},
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		const state = { exited: false };
+		child.on("exit", () => {
+			state.exited = true;
+			if (endpoint?.child === state) endpoint = void 0;
 		});
 		return {
-			url: proxy.url,
+			url: await waitForListening(child, {
+				node,
+				token,
+				timeoutMs: listenTimeoutMs
+			}),
+			token,
 			pipeline: options.defaultPipeline,
-			source: `in-process, config ${path}`,
-			proxy
+			source: `child process ${child.pid}, config ${path}`,
+			child: state
 		};
 	}
 	function currentSessionId(ctx) {
@@ -116,27 +155,13 @@ function createAnonController(deps) {
 		return sessionId;
 	}
 	/**
-	* Adopts the session id of a root session and returns the id it replaced, if any. The first
-	* session of the process is the root; later `session_start`s are subagents (headless, `print`
-	* mode) unless the session has a UI or runs in another mode.
+	* Adopts the session id of a root session. The first session of the process is the root;
+	* later `session_start`s are subagents (headless, `print` mode) unless the session has a UI
+	* or runs in another mode.
 	*/
 	function enterSession(ctx, root) {
-		const previous = sessionId;
-		if (previous === void 0) {
-			currentSessionId(ctx);
-			return;
-		}
-		if (root) sessionId = readSessionId(ctx) ?? previous;
-		return sessionId === previous ? void 0 : previous;
-	}
-	async function dropProxySession(ctx, id) {
-		const proxy = endpoint?.proxy;
-		if (proxy === void 0) return;
-		try {
-			await proxy.dropSession(id);
-		} catch (err) {
-			ctx.ui.notify(`anon: could not drop proxy session ${id}: ${errorMessage(err)}`, "warning");
-		}
+		if (sessionId === void 0) currentSessionId(ctx);
+		else if (root) sessionId = readSessionId(ctx) ?? sessionId;
 	}
 	function route(ctx, target) {
 		const registry = ctx.modelRegistry;
@@ -264,9 +289,13 @@ function createAnonController(deps) {
 		if (preRouted.length > 0) lines.push(`routed by their own config (${preRouted.length}): ${preRouted.sort().join(", ")}`);
 		return lines.join("\n");
 	}
-	/** Session entry: rotate the proxy session for a new root, then (re-)apply routing when wanted. */
+	/**
+	* 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
+	* until it exits, and no request carries that id again.
+	*/
 	async function start(ctx, session, root) {
-		const previous = enterSession(ctx, root);
+		enterSession(ctx, root);
 		if (!wanted && readEnabled(statePath)) wanted = true;
 		if (wanted) {
 			const failure = await activate(ctx, session);
@@ -275,7 +304,6 @@ function createAnonController(deps) {
 				ctx.ui.notify(refusalHint(), "error");
 			}
 		}
-		if (previous !== void 0) await dropProxySession(ctx, previous);
 		showStatus(ctx);
 	}
 	return {
@@ -370,6 +398,101 @@ function readEnabled(path) {
 		return false;
 	}
 }
+function spawnNode(command, args, options) {
+	return spawn(command, [...args], {
+		cwd: options.cwd,
+		env: options.env,
+		stdio: [...options.stdio]
+	});
+}
+/** The stderr lines a startup failure quotes. */
+const STDERR_TAIL = 10;
+/**
+* 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.
+*/
+function waitForListening(child, how) {
+	const killOnExit = () => {
+		child.kill("SIGTERM");
+	};
+	process.on("exit", killOnExit);
+	const forgetExitHook = () => {
+		process.off("exit", killOnExit);
+	};
+	child.on("exit", forgetExitHook);
+	for (const stream of [
+		child.stdin,
+		child.stdout,
+		child.stderr
+	]) stream?.on("error", () => {});
+	const listening = Promise.withResolvers();
+	const label = `the transform proxy child process (${how.node}, pid ${child.pid})`;
+	const tail = [];
+	let stderrPartial = "";
+	let stdout = "";
+	let settled = false;
+	function stderrTail() {
+		const lines = [...tail, stderrPartial].filter((line) => line.trim() !== "").slice(-10);
+		return lines.length === 0 ? "(none)" : lines.map((line) => line.split(how.token).join("[token]")).join("\n");
+	}
+	function fail(message) {
+		if (settled) return;
+		settled = true;
+		clearTimeout(timer);
+		listening.reject(new Error(message));
+	}
+	const timer = setTimeout(() => {
+		fail(`${label} did not print "listening" within ${duration(how.timeoutMs)} and was killed; last stderr lines:\n${stderrTail()}`);
+		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));
+	});
+	child.stdout?.on("data", (chunk) => {
+		if (settled) return;
+		const lines = (stdout + String(chunk)).split("\n");
+		stdout = lines.pop() ?? "";
+		for (const line of lines) {
+			const match = /^listening (\S+)$/.exec(line.trim());
+			if (match === null) continue;
+			settled = true;
+			clearTimeout(timer);
+			stdout = "";
+			child.unref();
+			for (const stream of [
+				child.stdin,
+				child.stdout,
+				child.stderr
+			]) stream?.unref?.();
+			listening.resolve(match[1]);
+			return;
+		}
+	});
+	child.on("exit", (code, signal) => {
+		if (settled) return;
+		const report = () => fail(`${label} exited with ${code === null ? `signal ${signal}` : `code ${code}`} before it was listening; last stderr lines:\n${stderrTail()}`);
+		const stderr = child.stderr;
+		if (stderr === null || stderr.readableEnded || stderr.destroyed) report();
+		else {
+			stderr.once("end", report);
+			stderr.once("close", report);
+		}
+	});
+	child.on("error", (err) => {
+		forgetExitHook();
+		fail(`could not start the transform proxy with "${how.node}": ${err.message}; it runs under Node >= 22: put node on PATH or set ${NODE_ENV}`);
+	});
+	return listening.promise;
+}
+function duration(ms) {
+	return ms % 1e3 === 0 ? `${ms / 1e3} s` : `${ms} ms`;
+}
 /** Every provider of the registry with the wire APIs of its models. */
 function providerApis(registry) {
 	const out = /* @__PURE__ */ new Map();
@@ -416,7 +539,7 @@ function originOf(url) {
 	}
 }
 // src/omp/index.ts
-/** omp re-imports the extension per session; the controller (proxy, recorded originals) is process-wide. */
+/** omp re-imports the extension per session; the controller (proxy child, recorded originals) is process-wide. */
 const CONTROLLER_KEY = Symbol.for("@skaile/transform-proxy/omp");
 /** Registers the `/anon` command and the event handlers on one session's extension API. */
 function registerAnonExtension(pi, controller) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/transform-proxy",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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",