@skaile/transform-proxy 0.0.0-stage → 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,88 @@
+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-D5nBnO7T.mjs";
+/** One stage's streamed inbound transformer, as returned by `Transform.inboundStream()`. */
+interface InboundStream {
+  push(chunk: string): string;
+  flush(): string;
+}
+/**
+ * Composes the stages of one pipeline into a single transform.
+ * Outbound runs stage 1 to n, inbound and streamed inbound run stage n to 1.
+ * 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 {
+  readonly baseDir: string;
+  readonly transforms: Record<string, TransformSpec>;
+  readonly pipelines: Record<string, readonly string[]>;
+  readonly defaultPipeline?: string;
+  readonly allowUpstreams?: readonly string[];
+}
+interface ResolvedProxyConfig {
+  readonly path: string;
+  readonly options: ProxyConfig;
+}
+interface ConfigLookup {
+  /** The `--config` value, relative to `cwd`. When set, it is the only candidate. */
+  readonly explicit?: string;
+  readonly cwd: string;
+  readonly home: string;
+}
+/** The implicit lookup locations, in order: `./.skaile/` then `~/.config/skaile/`. */
+export declare function configCandidates(cwd: string, home: string): readonly string[];
+/**
+ * Finds the config file: the explicit path when given (it must exist), otherwise the first
+ * existing implicit candidate. Returns `undefined` when no implicit candidate exists.
+ */
+export declare function findProxyConfig(lookup: ConfigLookup): string | undefined;
+/** Finds and loads the config. Throws, naming the searched paths, when none is found. */
+export declare function resolveProxyConfig(lookup: ConfigLookup): ResolvedProxyConfig;
+/** Reads and validates a YAML config file. Unknown keys are rejected so that typos fail loudly. */
+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;
+interface WireContext {
+  /** The session's composed pipeline. */
+  readonly transform: Transform;
+  /**
+   * Session-scoped cache of signed reasoning: key -> text exactly as the model produced it.
+   * Walkers namespace their keys (`anthropic:<signature>`, `responses:<itemId>`).
+   */
+  readonly signatures: Map<string, string>;
+}
+/** Thrown by `request` for attachments (image, document, file parts); the server answers 400 `unsupported_content`. */
+export declare class UnsupportedContentError extends Error {
+  readonly code = "unsupported_content";
+  constructor(message: string);
+}
+/** A text transformer over raw SSE text; safe at any chunk boundary. */
+interface SseTransformer {
+  push(chunk: string): string;
+  flush(): string;
+}
+/** Pure functions over one wire protocol's parsed JSON. */
+interface WireWalker {
+  /**
+   * Returns the request body with every text leaf passed through `outbound` and the
+   * pipeline `instruction` added to the system prompt. Throws `UnsupportedContentError`
+   * for attachments; `outbound` errors propagate unchanged.
+   */
+  request(body: unknown, ctx: WireContext): Promise<unknown>;
+  /** Restores a non-streamed JSON response. */
+  response(body: unknown, ctx: WireContext): unknown;
+  /** SSE event transformer for a streamed response. */
+  stream(ctx: WireContext): SseTransformer;
+}
+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 };

package/dist/index.mjs

@@ -0,0 +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-DQPsbYLi.mjs";

package/dist/omp/index.d.mts

@@ -0,0 +1,89 @@
+import { a as TransformProxyOptions, i as TransformProxy } from "../server-D5nBnO7T.mjs";
+interface OmpModel {
+  readonly provider: string;
+  readonly id: string;
+  readonly api: string;
+  readonly baseUrl?: string;
+}
+/** A runtime provider override: omp merges `headers` into the provider's existing headers. */
+interface OmpProviderOverride {
+  baseUrl?: string;
+  headers?: Record<string, string>;
+}
+interface OmpModelRegistry {
+  getAll(): readonly OmpModel[];
+  find(provider: string, modelId: string): OmpModel | undefined;
+  getProviderBaseUrl(provider: string): string | undefined;
+  getProviderHeaders(provider: string): Record<string, string> | undefined;
+  registerProvider(name: string, config: OmpProviderOverride, sourceId?: string): void;
+  /**
+   * Clears the runtime overrides of every provider registered under `sourceId` and reloads the
+   * static (built-in / models.yml) config once. `unregisterProvider` reloads once per provider:
+   * about half a second each, with ~80 built-in providers.
+   */
+  clearSourceRegistrations(sourceId: string): void;
+}
+type OmpNotifyType = 'info' | 'warning' | 'error';
+interface OmpUi {
+  notify(message: string, type?: OmpNotifyType): void;
+  setStatus(key: string, text: string | undefined): void;
+}
+interface OmpContext {
+  readonly ui: OmpUi;
+  readonly cwd: string;
+  readonly modelRegistry: OmpModelRegistry;
+  readonly sessionManager: {
+    getSessionId(): string;
+  };
+  /** The session's active model: a snapshot that a provider override does not update. */
+  readonly model: OmpModel | undefined;
+}
+interface OmpAutocompleteItem {
+  value: string;
+  label: string;
+  description?: string;
+}
+type OmpEventName = 'session_start' | 'before_agent_start' | 'turn_start';
+/** Per-session actions of the extension API. */
+interface OmpSessionActions {
+  /** Rebinds the session's active model (without persisting it as the default). */
+  setModel(model: OmpModel): Promise<boolean>;
+}
+interface OmpExtensionApi extends OmpSessionActions {
+  registerCommand(name: string, options: {
+    description?: string;
+    getArgumentCompletions?: (argumentPrefix: string) => OmpAutocompleteItem[] | null;
+    handler: (args: string, ctx: OmpContext) => Promise<void>;
+  }): void;
+  on(event: OmpEventName, handler: (event: unknown, ctx: OmpContext) => void | Promise<void>): void;
+}
+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>;
+}
+interface AnonController {
+  readonly required: boolean;
+  readonly statePath: string;
+  /** Handles `/anon <args>`. `session` rebinds the session's active model after a switch. */
+  command(args: string, ctx: OmpContext, session: OmpSessionActions): Promise<void>;
+  completions(prefix: string): OmpAutocompleteItem[] | null;
+  /** Applies the persisted flag (or required mode) and refreshes the status bar. */
+  sessionStart(ctx: OmpContext, session: OmpSessionActions): Promise<void>;
+  /** While on: routes providers that appeared, or were reset, since the last pass. */
+  reapply(ctx: OmpContext, session: OmpSessionActions): Promise<void>;
+}
+/**
+ * The process-wide `/anon` state machine. omp builds one extension instance per session
+ * (subagents included) while they share one model registry, so one controller serves them all.
+ */
+export declare function createAnonController(deps: AnonControllerDeps): AnonController;
+/** `$SKAILE_TRANSFORM_PROXY_OMP_STATE`, else `skaile-transform-proxy.json` in omp's agent dir (`$PI_CODING_AGENT_DIR` or `~/.omp/agent`). */
+export declare function defaultStatePath(env: Readonly<Record<string, string | undefined>>, home: string): string;
+/** 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 };

package/dist/omp/index.mjs

@@ -0,0 +1,345 @@
+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-DQPsbYLi.mjs";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+// src/omp/anon.ts
+/** A running proxy the extension routes to. */
+const URL_ENV = "SKAILE_TRANSFORM_PROXY_URL";
+/** The client token of that proxy. */
+const TOKEN_ENV = "SKAILE_TRANSFORM_PROXY_TOKEN";
+/** `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. */
+const STATE_ENV = "SKAILE_TRANSFORM_PROXY_OMP_STATE";
+/** 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. */
+const SOURCE_ID = "skaile-transform-proxy";
+/** The wire APIs the proxy rewrites. Providers on any other API are routed too, and the proxy refuses their requests. */
+const SERVED_APIS = {
+	"anthropic-messages": true,
+	"openai-completions": true,
+	"openai-responses": true
+};
+const USAGE = "usage: /anon on|off|status";
+const VERBS = [
+	{
+		value: "on",
+		label: "on",
+		description: "route every provider through the transform proxy"
+	},
+	{
+		value: "off",
+		label: "off",
+		description: "restore the original provider base URLs"
+	},
+	{
+		value: "status",
+		label: "status",
+		description: "show the proxy, pipeline and routed providers"
+	}
+];
+/**
+* The process-wide `/anon` state machine. omp builds one extension instance per session
+* (subagents included) while they share one model registry, so one controller serves them all.
+*/
+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 registries = /* @__PURE__ */ new WeakMap();
+	let enabled = false;
+	let endpoint;
+	let starting;
+	let sessionId;
+	function stateOf(registry) {
+		let state = registries.get(registry);
+		if (state === void 0) {
+			state = {
+				originals: /* @__PURE__ */ new Map(),
+				routed: /* @__PURE__ */ new Set()
+			};
+			registries.set(registry, state);
+		}
+		return state;
+	}
+	async function resolveEndpoint(ctx) {
+		if (endpoint !== void 0) return endpoint;
+		const url = env[URL_ENV];
+		if (url !== void 0 && url !== "") {
+			const token = env[TOKEN_ENV];
+			endpoint = {
+				url,
+				...token ? { token } : {},
+				source: URL_ENV
+			};
+			return endpoint;
+		}
+		starting ??= startInProcess(ctx.cwd).finally(() => {
+			starting = void 0;
+		});
+		endpoint = await starting;
+		return endpoint;
+	}
+	async function startInProcess(cwd) {
+		const path = findProxyConfig({
+			cwd,
+			home: deps.home
+		});
+		if (path === void 0) {
+			const searched = configCandidates(cwd, deps.home).join(" or ");
+			throw new Error(`no transform proxy config found: create ${searched}, or set ${URL_ENV} to a running proxy`);
+		}
+		const options = loadProxyConfig(path);
+		if (options.defaultPipeline === void 0) throw new Error(`${path} sets no defaultPipeline: the omp extension sends no pipeline header`);
+		return {
+			url: (await startProxy({
+				...options,
+				log: silentLogger
+			})).url,
+			pipeline: options.defaultPipeline,
+			source: `in-process, config ${path}`
+		};
+	}
+	function currentSessionId(ctx) {
+		if (sessionId === void 0) {
+			let id;
+			try {
+				id = ctx.sessionManager.getSessionId();
+			} catch {
+				id = void 0;
+			}
+			sessionId = typeof id === "string" && id !== "" ? id : randomUUID();
+		}
+		return sessionId;
+	}
+	function route(ctx, target) {
+		const registry = ctx.modelRegistry;
+		const state = stateOf(registry);
+		const session = currentSessionId(ctx);
+		for (const provider of providerApis(registry).keys()) {
+			let original = state.originals.get(provider);
+			if (original === void 0) {
+				original = snapshot(registry, provider);
+				state.originals.set(provider, original);
+			}
+			if (original.preRouted) continue;
+			if (state.routed.has(provider) && registry.getProviderBaseUrl(provider) === target.url) continue;
+			const headers = { [SESSION_HEADER]: session };
+			if (original.baseUrl !== void 0) headers[UPSTREAM_HEADER] = original.baseUrl;
+			if (target.token !== void 0) headers[TOKEN_HEADER] = target.token;
+			registry.registerProvider(provider, {
+				baseUrl: target.url,
+				headers
+			}, SOURCE_ID);
+			state.routed.add(provider);
+		}
+	}
+	/** Clears the proxy overrides; re-applies the recorded original where another override was layered underneath. */
+	function unroute(ctx) {
+		const registry = ctx.modelRegistry;
+		const state = stateOf(registry);
+		registry.clearSourceRegistrations(SOURCE_ID);
+		const lost = [];
+		for (const provider of state.routed) {
+			const original = state.originals.get(provider);
+			const restored = registry.getProviderBaseUrl(provider);
+			if (original === void 0 || restored === original.baseUrl) continue;
+			if (restored === void 0) {
+				lost.push(provider);
+				continue;
+			}
+			if (original.baseUrl !== void 0) registry.registerProvider(provider, {
+				baseUrl: original.baseUrl,
+				...original.headers === void 0 ? {} : { headers: original.headers }
+			});
+		}
+		state.routed.clear();
+		return lost;
+	}
+	async function turnOn(ctx, session) {
+		let target;
+		try {
+			target = await resolveEndpoint(ctx);
+		} catch (err) {
+			ctx.ui.notify(`anon: ${errorMessage(err)}`, "error");
+			return false;
+		}
+		route(ctx, target);
+		enabled = true;
+		await rebind(ctx, session);
+		return true;
+	}
+	/** The session holds its active model as a snapshot: swap in the registry's re-projected one. */
+	async function rebind(ctx, session) {
+		const active = ctx.model;
+		if (active === void 0) return;
+		const live = ctx.modelRegistry.find(active.provider, active.id);
+		if (live === void 0 || live.baseUrl === active.baseUrl) return;
+		if (!await session.setModel(live)) ctx.ui.notify(`anon: could not rebind the active model ${active.provider}/${active.id}; select it again`, "warning");
+	}
+	function persist(ctx, value) {
+		try {
+			mkdirSync(dirname(statePath), { recursive: true });
+			writeFileSync(statePath, `${JSON.stringify({ enabled: value }, null, 2)}\n`);
+		} catch (err) {
+			ctx.ui.notify(`anon: could not save ${statePath}: ${errorMessage(err)}`, "warning");
+		}
+	}
+	function showStatus(ctx) {
+		ctx.ui.setStatus(STATUS_KEY, enabled ? "anon on" : "anon off");
+	}
+	function statusText(ctx) {
+		const registry = ctx.modelRegistry;
+		const state = stateOf(registry);
+		const apis = providerApis(registry);
+		const lines = [`anon ${enabled ? "on" : "off"}${required ? " (required)" : ""}`];
+		if (endpoint !== void 0) {
+			lines.push(`proxy: ${endpoint.url} (${endpoint.source})`);
+			lines.push(`pipeline: ${endpoint.pipeline ?? "the proxy default"}`);
+		}
+		if (sessionId !== void 0) lines.push(`session: ${sessionId}`);
+		const routed = [...state.routed].sort();
+		const refused = routed.flatMap((provider) => {
+			const reason = refusalReason(apis.get(provider), state.originals.get(provider));
+			return reason === void 0 ? [] : [`${provider} (${reason})`];
+		});
+		const preRouted = [...state.originals].filter(([, original]) => original.preRouted).map(([provider]) => provider);
+		lines.push(`routed (${routed.length}): ${routed.length === 0 ? "none" : routed.join(", ")}`);
+		if (refused.length > 0) lines.push(`refused by the proxy (${refused.length}): ${refused.join(", ")}`);
+		if (preRouted.length > 0) lines.push(`routed by their own config (${preRouted.length}): ${preRouted.sort().join(", ")}`);
+		return lines.join("\n");
+	}
+	return {
+		required,
+		statePath,
+		async command(args, ctx, session) {
+			switch (args.trim().toLowerCase()) {
+				case "on":
+					if (await turnOn(ctx, session)) {
+						persist(ctx, true);
+						const count = stateOf(ctx.modelRegistry).routed.size;
+						ctx.ui.notify(`anon on: ${count} provider(s) routed through ${endpoint?.url}`, "info");
+					}
+					break;
+				case "off": {
+					if (required) {
+						ctx.ui.notify(`anon: off refused: this session requires the transform proxy (${MODE_ENV}=required)`, "warning");
+						break;
+					}
+					const lost = unroute(ctx);
+					enabled = false;
+					await rebind(ctx, session);
+					persist(ctx, false);
+					ctx.ui.notify("anon off: original provider base URLs restored", "info");
+					if (lost.length > 0) ctx.ui.notify(`anon: ${lost.join(", ")} lost their runtime registration (registered by another extension); restart omp to restore them`, "warning");
+					break;
+				}
+				case "":
+				case "status":
+					ctx.ui.notify(statusText(ctx), "info");
+					break;
+				default: ctx.ui.notify(USAGE, "error");
+			}
+			showStatus(ctx);
+		},
+		completions(prefix) {
+			const needle = prefix.trim().toLowerCase();
+			const items = VERBS.filter((item) => item.value.startsWith(needle));
+			return items.length > 0 ? items : null;
+		},
+		async sessionStart(ctx, session) {
+			currentSessionId(ctx);
+			if (enabled && endpoint !== void 0) {
+				route(ctx, endpoint);
+				await rebind(ctx, session);
+			} else if (required || readEnabled(statePath)) {
+				if (!await turnOn(ctx, session) && required) ctx.ui.notify("anon: required mode, but no provider is routed through the transform proxy", "error");
+			}
+			showStatus(ctx);
+		},
+		async reapply(ctx, session) {
+			if (!enabled || endpoint === void 0) return;
+			route(ctx, endpoint);
+			await rebind(ctx, session);
+		}
+	};
+}
+/** `$SKAILE_TRANSFORM_PROXY_OMP_STATE`, else `skaile-transform-proxy.json` in omp's agent dir (`$PI_CODING_AGENT_DIR` or `~/.omp/agent`). */
+function defaultStatePath(env, home) {
+	const explicit = env[STATE_ENV];
+	if (explicit !== void 0 && explicit !== "") return explicit;
+	const agentDir = env.PI_CODING_AGENT_DIR || join(home, ".omp", "agent");
+	return join(agentDir, "skaile-transform-proxy.json");
+}
+function readEnabled(path) {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		return typeof parsed === "object" && parsed !== null && "enabled" in parsed && parsed.enabled === true;
+	} catch {
+		return false;
+	}
+}
+/** Every provider of the registry with the wire APIs of its models. */
+function providerApis(registry) {
+	const out = /* @__PURE__ */ new Map();
+	for (const model of registry.getAll()) {
+		let apis = out.get(model.provider);
+		if (apis === void 0) {
+			apis = /* @__PURE__ */ new Set();
+			out.set(model.provider, apis);
+		}
+		apis.add(model.api);
+	}
+	return out;
+}
+function snapshot(registry, provider) {
+	const live = registry.getProviderHeaders(provider);
+	const headers = live === void 0 ? void 0 : { ...live };
+	const preRouted = headers !== void 0 && Object.keys(headers).some((name) => name.toLowerCase() === "x-skaile-transform-upstream");
+	const baseUrl = registry.getProviderBaseUrl(provider);
+	return {
+		...baseUrl === void 0 ? {} : { baseUrl },
+		...headers === void 0 || Object.keys(headers).length === 0 ? {} : { headers },
+		preRouted
+	};
+}
+function refusalReason(apis, original) {
+	if (original?.baseUrl === void 0) return "no base URL";
+	const unserved = [...apis ?? []].filter((api) => !Object.hasOwn(SERVED_APIS, api));
+	return unserved.length === 0 ? void 0 : unserved.join(", ");
+}
+// src/omp/index.ts
+/** omp re-imports the extension per session; the controller (proxy, 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) {
+	pi.registerCommand("anon", {
+		description: "Route model requests through the skaile transform proxy: on | off | status",
+		getArgumentCompletions: (prefix) => controller.completions(prefix),
+		handler: (args, ctx) => guarded(ctx, () => controller.command(args, ctx, pi))
+	});
+	on(pi, "session_start", (ctx) => controller.sessionStart(ctx, pi));
+	on(pi, "before_agent_start", (ctx) => controller.reapply(ctx, pi));
+	on(pi, "turn_start", (ctx) => controller.reapply(ctx, pi));
+}
+function anonExtension(pi) {
+	const scope = globalThis;
+	registerAnonExtension(pi, scope[CONTROLLER_KEY] ??= createAnonController({
+		env: process.env,
+		home: homedir()
+	}));
+}
+function on(pi, event, run) {
+	pi.on(event, (_event, ctx) => guarded(ctx, () => run(ctx)));
+}
+async function guarded(ctx, run) {
+	try {
+		await run();
+	} catch (err) {
+		ctx.ui.notify(`anon: ${errorMessage(err)}`, "error");
+	}
+}
+export { createAnonController, anonExtension as default, defaultStatePath, registerAnonExtension };

package/dist/server-D5nBnO7T.d.mts

@@ -0,0 +1,96 @@
+/** Minimal logger; structurally compatible with the workspaces `Logger`. */
+interface Logger {
+  debug(msg: string, ...args: unknown[]): void;
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+}
+type TextLeafKind = 'system' | 'user' | 'assistant' | 'thinking' | 'toolCall' | 'toolResult';
+interface TextLeaf {
+  readonly kind: TextLeafKind;
+  readonly toolName?: string;
+}
+/** One session's instance of one pipeline stage. */
+interface Transform {
+  /** Prepended to the system prompt; omit when the model needs no instruction. */
+  readonly instruction?: string;
+  /** Host -> model, one text leaf. A throw refuses the request (502 `transform_failed`); nothing is sent. */
+  outbound(text: string, leaf: TextLeaf): Promise<string>;
+  /** Model -> host, one complete text. */
+  inbound(text: string): string;
+  /** Model -> host, one streamed text block. Invariant: push(c1)+...+push(cn)+flush() === inbound(c1+...+cn). */
+  inboundStream(): {
+    push(chunk: string): string;
+    flush(): string;
+  };
+  /** Called once when the proxy drops the session. */
+  dispose?(): void | Promise<void>;
+}
+interface SessionFact {
+  readonly kind: string;
+  readonly value: string;
+  readonly source: string;
+}
+interface SessionFacts {
+  /** Bumped on every publish/clear; readers re-read `list()` only when it changed. */
+  readonly version: number;
+  list(kind?: string): readonly SessionFact[];
+}
+interface SessionFactPublisher {
+  /** Replaces this publisher's facts (source = publisher id). */
+  publish(facts: readonly Omit<SessionFact, 'source'>[]): void;
+  clear(): void;
+}
+interface TransformSessionContext {
+  readonly sessionId: string;
+  readonly facts: SessionFacts;
+  readonly log: Logger;
+}
+type TransformFactory = (ctx: TransformSessionContext) => Promise<Transform>;
+/** Default export of a transform module, e.g. `@skaile/forge-anon/proxy`. */
+interface TransformModule {
+  readonly id: string;
+  /** Once per proxy and config: validate config, build shared heavy state (detectors). Throws on a bad config. */
+  open(config: unknown, ctx: {
+    readonly baseDir: string;
+    readonly log: Logger;
+  }): Promise<TransformFactory>;
+}
+/** A configured transform: a module (object, npm specifier or relative path) and its config. */
+interface TransformSpec {
+  readonly module: string | TransformModule;
+  readonly config?: unknown;
+}
+interface TransformProxyOptions {
+  /** Default 127.0.0.1. A non-loopback host requires `token`. */
+  host?: string;
+  /** Default 0 (ephemeral). */
+  port?: number;
+  /** Required `x-skaile-transform-token` when set. */
+  token?: string;
+  /** Where transform module specifiers and configs resolve. */
+  baseDir: string;
+  transforms: Readonly<Record<string, TransformSpec>>;
+  pipelines: Readonly<Record<string, readonly string[]>>;
+  /** Used when the request names no pipeline. Absent = such requests are refused. */
+  defaultPipeline?: string;
+  /** Origins. Absent = any https origin plus loopback http. */
+  allowUpstreams?: readonly string[];
+  log?: Logger;
+}
+interface TransformProxy {
+  readonly url: string;
+  session(id: string): {
+    readonly facts: SessionFacts;
+    publisher(source: string): SessionFactPublisher;
+  };
+  /** Disposes the session's transform instances and forgets its facts and caches. */
+  dropSession(id: string): Promise<void>;
+  close(): Promise<void>;
+}
+declare const UPSTREAM_HEADER = "x-skaile-transform-upstream";
+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 };