@alienplatform/ai-gateway 3.3.0-dev.0d4f932037814a854d56a7e4e82a8a34cc2e35cb

package/dist/gateway.js

@@ -0,0 +1,748 @@
+import { createRequire } from "node:module";
+import { AlienError, BindingNotFoundError, InvalidBindingConfigError, InvalidBindingConfigError as InvalidBindingConfigError$1, defineError } from "@alienplatform/core";
+import * as z from "zod/v4";
+import { spawn } from "node:child_process";
+import { chmodSync, existsSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/binding.ts
+/**
+* Parsing for the `ALIEN_<NAME>_BINDING` env var an `ai` resource projects. The client only
+* routes on the binding: a BYO-key (`external`) binding is validated strictly here because the
+* client itself uses its fields, while every other service tag — the ambient variants, including
+* ones added to the platform after this SDK shipped — is passed through for the Rust gateway to
+* validate and serve. Mirrors the Rust `AiBinding` (serde tag "service", lowercase, camelCase
+* fields).
+*/
+const externalAiBindingSchema = z.object({
+	service: z.literal("external"),
+	provider: z.string(),
+	apiKey: z.string()
+}).strict();
+/** Narrow an `AiBinding` to the BYO-key variant the client handles itself. */
+function isExternalAiBinding(binding) {
+	return binding.service === "external";
+}
+/** The env var an `ai` binding is projected into: `ALIEN_<NAME>_BINDING` (uppercased, `-`→`_`). */
+function aiBindingEnvVarName(name) {
+	return `ALIEN_${name.toUpperCase().replace(/-/g, "_")}_BINDING`;
+}
+/** Parse `ALIEN_<NAME>_BINDING`, or `undefined` if it is not set. Throws on malformed content. */
+async function parseAiBinding(name) {
+	const raw = process.env[aiBindingEnvVarName(name)];
+	if (!raw) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		throw (await AlienError.from(cause)).withContext(InvalidBindingConfigError.create({ message: `AI binding '${name}' is not valid JSON` }));
+	}
+	const service = parsed !== null && typeof parsed === "object" ? parsed.service : void 0;
+	if (typeof service !== "string") throw new AlienError(InvalidBindingConfigError.create({ message: `AI binding '${name}' has no 'service' tag` }));
+	if (service !== "external") return parsed;
+	const result = externalAiBindingSchema.safeParse(parsed);
+	if (!result.success) throw (await AlienError.from(result.error)).withContext(InvalidBindingConfigError.create({ message: `AI binding '${name}' has an unexpected shape` }));
+	return result.data;
+}
+//#endregion
+//#region src/errors.ts
+/**
+* Typed errors for the AI client surface (`ai()` / `getAiConnection`).
+*
+* Defined here rather than in `@alienplatform/bindings` because the AI binding
+* resolves through this package's gateway process, not the bindings native addon.
+*/
+/**
+* Error thrown when an upstream LLM endpoint returns a non-2xx response.
+*
+* Marked internal because the response body and upstream URL may contain
+* provider-specific infra detail not intended for external clients.
+* Retryability is derived per-call from the HTTP status code.
+*/
+const AiUpstreamError = defineError({
+	code: "AI_UPSTREAM_ERROR",
+	context: z.object({
+		url: z.string(),
+		status: z.number(),
+		message: z.string()
+	}),
+	message: ({ url, status, message }) => `AI upstream request to '${url}' failed with status ${status}: ${message}`,
+	retryable: false,
+	internal: true,
+	httpStatusCode: 502
+});
+/**
+* Error thrown when a network-level failure occurs before or after an
+* upstream LLM request (fetch threw, or the success body was not parseable JSON).
+* These are always transient and safe to retry.
+*/
+const AiTransportError = defineError({
+	code: "AI_TRANSPORT_ERROR",
+	context: z.object({
+		url: z.string(),
+		reason: z.string()
+	}),
+	message: ({ url, reason }) => `AI request to '${url}' failed due to a transport error: ${reason}`,
+	retryable: true,
+	internal: true,
+	httpStatusCode: 503
+});
+/**
+* Error thrown when a BYO-key binding names a provider the client has no base URL for.
+* External (the developer set a bad `provider` tag) and not retryable — failing closed
+* here stops the projected BYO key from being shipped to the wrong provider's endpoint.
+*/
+const UnsupportedProviderError = defineError({
+	code: "AI_UNSUPPORTED_PROVIDER",
+	context: z.object({
+		provider: z.string(),
+		supported: z.array(z.string())
+	}),
+	message: ({ provider, supported }) => `Unknown AI provider '${provider}'. Supported providers are ${supported.join(", ")}. For any other OpenAI-compatible provider, set ALIEN_AI_LOCAL_BASE_URL to its base URL.`,
+	retryable: false,
+	internal: false,
+	httpStatusCode: 400
+});
+/**
+* Error thrown when a binding's upstream serves chat/completions but not the OpenAI Responses
+* API. Anthropic's OpenAI-compatible host is the case in point: `/v1/chat/completions` works,
+* `/v1/responses` 404s. External (a caller usage error), not retryable.
+*/
+const ResponsesApiUnsupportedError = defineError({
+	code: "AI_RESPONSES_API_UNSUPPORTED",
+	context: z.object({ provider: z.string() }),
+	message: ({ provider }) => `The '${provider}' provider serves chat/completions but not the OpenAI Responses API (/v1/responses). Use chat.completions.create, or set ALIEN_AI_LOCAL_BASE_URL to a Responses-capable endpoint.`,
+	retryable: false,
+	internal: false,
+	httpStatusCode: 400
+});
+/**
+* Error thrown when this platform/architecture has no prebuilt gateway binary.
+*/
+const UnsupportedPlatformError = defineError({
+	code: "AI_GATEWAY_UNSUPPORTED_PLATFORM",
+	context: z.object({
+		platform: z.string(),
+		arch: z.string(),
+		reason: z.string().optional()
+	}),
+	message: ({ platform, arch, reason }) => `@alienplatform/ai-gateway has no prebuilt binary for platform '${platform}' arch '${arch}'${reason ? `: ${reason}` : ""}.`,
+	retryable: false,
+	internal: false,
+	httpStatusCode: 400
+});
+/**
+* Error thrown when the `alien-ai-gateway` executable cannot be located (or, for a
+* compiled Worker, extracted) for this platform. Internal because the context
+* carries filesystem paths.
+*/
+const GatewayBinaryUnavailableError = defineError({
+	code: "AI_GATEWAY_BINARY_UNAVAILABLE",
+	context: z.object({
+		triple: z.string(),
+		reason: z.string(),
+		path: z.string().optional()
+	}),
+	message: ({ triple, reason }) => `Cannot locate the alien-ai-gateway binary for '${triple}': ${reason}`,
+	retryable: false,
+	internal: true,
+	httpStatusCode: 400
+});
+/**
+* Error thrown when the spawned `alien-ai-gateway` process failed to report a
+* ready URL: it exited early or errored on startup. Retryable because the common
+* cause (an ambient cloud credential not yet resolvable) is transient.
+*/
+const GatewayStartFailedError = defineError({
+	code: "AI_GATEWAY_START_FAILED",
+	context: z.object({ reason: z.string() }),
+	message: ({ reason }) => `The alien-ai-gateway process failed to start: ${reason}`,
+	retryable: true,
+	internal: true,
+	httpStatusCode: 503
+});
+//#endregion
+//#region src/client.ts
+/**
+* AI binding — a thin OpenAI-compatible client to the workload's AI gateway.
+*
+* For an ambient-cloud binding the gateway process is started on the first call; for a
+* BYO-key (External) binding the client talks to the provider directly. Either way the client
+* only forwards OpenAI-shaped requests and streams responses back — it holds no ambient
+* credentials and rewrites nothing (the gateway rewrites the model id and injects the
+* credential).
+*/
+const KNOWN_PROVIDER_BASE_URLS = {
+	openai: "https://api.openai.com",
+	anthropic: "https://api.anthropic.com"
+};
+function providerBaseUrl(provider) {
+	const override = process.env.ALIEN_AI_LOCAL_BASE_URL;
+	if (override) return override.replace(/\/$/, "");
+	const base = KNOWN_PROVIDER_BASE_URLS[provider];
+	if (!base) throw new AlienError(UnsupportedProviderError.create({
+		provider,
+		supported: Object.keys(KNOWN_PROVIDER_BASE_URLS)
+	}));
+	return base;
+}
+function defaultModels(provider) {
+	return provider === "anthropic" ? [
+		"claude-opus-4-8",
+		"claude-sonnet-5",
+		"claude-haiku-4-5"
+	] : ["gpt-4o-mini", "gpt-4o"];
+}
+/**
+* Resolve `ALIEN_<NAME>_BINDING` to a connection target. External -> the provider directly with
+* the projected key. Any other service tag (the ambient variants, including ones this SDK
+* predates) -> the in-process Rust gateway, started here on demand, which validates the binding
+* and injects the ambient cloud credential. Backs both `ai()` and `getAiConnection()`.
+*
+* The returned `baseUrl` is the root without `/v1` — the gateway serves
+* `/<segment>/v1/...`, and the client appends the versioned paths itself.
+*/
+async function resolveAiBinding(gateway, name) {
+	const binding = await parseAiBinding(name);
+	if (!binding) throw new AlienError(BindingNotFoundError.create({
+		bindingName: name,
+		bindingType: "Ai"
+	}));
+	if (isExternalAiBinding(binding)) return {
+		baseUrl: providerBaseUrl(binding.provider),
+		apiKey: binding.apiKey,
+		staticModels: defaultModels(binding.provider).map((id) => ({
+			id,
+			provider: binding.provider,
+			displayName: id
+		}))
+	};
+	const handle = await gateway.startAiGateway();
+	const segment = name.toLowerCase().replace(/_/g, "-");
+	return { baseUrl: `${handle.url}/${segment}` };
+}
+const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+	429,
+	502,
+	503,
+	504
+]);
+function createUpstreamError(url, status, message) {
+	return new AlienError({
+		...AiUpstreamError.create({
+			url,
+			status,
+			message
+		}).toOptions(),
+		retryable: RETRYABLE_STATUSES.has(status),
+		httpStatusCode: status >= 400 ? status : 502
+	});
+}
+async function* parseSse(url, body) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	const emit = function* (line) {
+		const trimmed = line.trimEnd();
+		if (!trimmed.startsWith("data:")) return;
+		const payload = trimmed.slice(5).trim();
+		if (payload === "[DONE]") return;
+		let chunk;
+		try {
+			chunk = JSON.parse(payload);
+		} catch (cause) {
+			throw new AlienError({
+				...AiTransportError.create({
+					url,
+					reason: `Malformed SSE chunk: ${cause instanceof Error ? cause.message : String(cause)}`
+				}).toOptions(),
+				source: {
+					code: "GENERIC_ERROR",
+					message: cause instanceof Error ? cause.stack ?? cause.message : String(cause),
+					retryable: false,
+					internal: true
+				}
+			});
+		}
+		yield chunk;
+	};
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines.pop() ?? "";
+			for (const line of lines) {
+				if (line.trimEnd() === "data: [DONE]") return;
+				yield* emit(line);
+			}
+		}
+		buffer += decoder.decode();
+		for (const line of buffer.split("\n")) {
+			if (line.trimEnd() === "data: [DONE]") return;
+			yield* emit(line);
+		}
+	} finally {
+		await reader.cancel().catch(() => {});
+	}
+}
+/**
+* Constructed by the `ai(name)` factory; resolves the binding (and starts the
+* gateway, for ambient) once on first use.
+*
+* @example
+* ```typescript
+* import { ai } from "@alienplatform/sdk"
+*
+* const llm = ai("my-llm")
+* const response = await llm.chat.completions.create({
+*   model: "claude-opus-4.8",
+*   messages: [{ role: "user", content: "Hello!" }],
+* })
+* ```
+*/
+var Ai = class {
+	resolve;
+	connectionPromise = null;
+	/** OpenAI-compatible chat namespace. */
+	chat;
+	/** OpenAI-compatible Responses API namespace (the surface Codex speaks). */
+	responses;
+	constructor(resolve) {
+		this.resolve = resolve;
+		this.chat = { completions: { create: ((params) => this._chatCompletionsCreate(params)) } };
+		this.responses = { create: ((params) => this._responsesCreate(params)) };
+	}
+	connection() {
+		this.connectionPromise ??= this.resolve().catch((error) => {
+			this.connectionPromise = null;
+			throw error;
+		});
+		return this.connectionPromise;
+	}
+	/** List the models the gateway exposes for this binding's cloud. */
+	async getAvailableModels() {
+		const { baseUrl, staticModels } = await this.connection();
+		if (staticModels) return staticModels;
+		const url = `${baseUrl}/v1/models`;
+		const response = await this._fetch(url, { method: "GET" });
+		if (!response.ok) throw createUpstreamError(url, response.status, await extractErrorMessage(response));
+		let body;
+		try {
+			body = await response.json();
+		} catch (jsonError) {
+			throw (await AlienError.from(jsonError)).withContext(AiTransportError.create({
+				url,
+				reason: `Response body is not valid JSON: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`
+			}));
+		}
+		if (!Array.isArray(body.data)) throw createUpstreamError(url, response.status, "models response had no data array");
+		for (const model of body.data) if (typeof model?.id !== "string" || typeof model?.provider !== "string" || typeof model?.displayName !== "string") throw createUpstreamError(url, response.status, `models response entry is missing id/provider/displayName: ${JSON.stringify(model)}`);
+		return body.data;
+	}
+	_chatCompletionsCreate(params) {
+		return this._postSurface("/v1/chat/completions", params);
+	}
+	async _responsesCreate(params) {
+		const { baseUrl } = await this.connection();
+		if (baseUrl === KNOWN_PROVIDER_BASE_URLS.anthropic) throw new AlienError(ResponsesApiUnsupportedError.create({ provider: "anthropic" }));
+		return this._postSurface("/v1/responses", params);
+	}
+	async _postSurface(path, params) {
+		const { baseUrl, apiKey } = await this.connection();
+		const url = `${baseUrl}${path}`;
+		const response = await this._fetch(url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+			},
+			body: JSON.stringify(params)
+		});
+		if (!response.ok) throw createUpstreamError(url, response.status, await extractErrorMessage(response));
+		if (params.stream === true) {
+			if (!response.body) throw createUpstreamError(url, response.status, "Streaming response body is null");
+			return parseSse(url, response.body);
+		}
+		try {
+			return await response.json();
+		} catch (jsonError) {
+			throw (await AlienError.from(jsonError)).withContext(AiTransportError.create({
+				url,
+				reason: `Response body is not valid JSON: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`
+			}));
+		}
+	}
+	async _fetch(url, init) {
+		try {
+			return await fetch(url, init);
+		} catch (fetchError) {
+			throw (await AlienError.from(fetchError)).withContext(AiTransportError.create({
+				url,
+				reason: fetchError instanceof Error ? fetchError.message : String(fetchError)
+			}));
+		}
+	}
+};
+/**
+* Build the `ai()` / `getAiConnection()` pair over a gateway. Mirrors `createGateway`:
+* each entry wires its own addon acquisition and shares this implementation.
+*/
+function createAiClient(gateway) {
+	return {
+		/** An OpenAI-compatible client for the named AI binding. */
+		ai(name) {
+			return new Ai(() => resolveAiBinding(gateway, name));
+		},
+		/**
+		* Resolve an AI binding to `{ baseURL, apiKey? }` for a plain OpenAI-compatible client
+		* (e.g. the Vercel AI SDK's `createOpenAICompatible`). The binding decides the target,
+		* so app code is identical whether AI is a BYO-key provider (local) or an ambient-cloud
+		* model behind the gateway.
+		*
+		* Awaits gateway startup for an ambient binding, so the returned `baseURL` is live
+		* before the caller's client uses it.
+		*/
+		async getAiConnection(name) {
+			const resolved = await resolveAiBinding(gateway, name);
+			return {
+				baseURL: `${resolved.baseUrl}/v1`,
+				apiKey: resolved.apiKey
+			};
+		}
+	};
+}
+async function extractErrorMessage(response) {
+	try {
+		const errBody = await response.json();
+		const errObj = errBody.error;
+		if (errObj && typeof errObj === "object" && "message" in errObj) return String(errObj.message);
+		return errBody.message ? String(errBody.message) : response.statusText;
+	} catch {
+		return response.statusText || "Unknown upstream error";
+	}
+}
+//#endregion
+//#region src/loader.ts
+/**
+* Locate (and, for a compiled Worker, extract) the `alien-ai-gateway` executable
+* that the gateway wrapper spawns.
+*
+* Resolution order (deferred to first spawn, so importing the package does no I/O):
+*
+*   1. An embedded binary registered by the `./native` entry. A `bun build
+*      --compile` Worker embeds the executable and hands us its (virtual) path;
+*      we copy it to a real, executable temp file once.
+*   2. `ALIEN_AI_GATEWAY_BINARY_PATH`: an explicit path (dev/test escape hatch;
+*      never set in published installs).
+*   3. `./alien-ai-gateway` in the working directory: the versioned Worker base
+*      stages it there for bundled Workers, which have no node_modules.
+*   4. The per-platform prebuild package `@alienplatform/ai-gateway-<triple>`,
+*      which ships the executable (installed via `optionalDependencies`).
+*   5. Dev fallback: the locally-built binary under `target/{release,debug}`,
+*      found by walking up from this module.
+*/
+const require = createRequire(import.meta.url);
+/** The launcher binary's file name across all platforms. */
+const BINARY_NAME = "alien-ai-gateway";
+/** Detect glibc vs musl, the same way napi-rs's generated loader does. */
+function detectLinuxLibc() {
+	const report = typeof process.report?.getReport === "function" ? process.report.getReport() : void 0;
+	if (report?.header) return report.header.glibcVersionRuntime ? "gnu" : "musl";
+	return existsSync("/etc/alpine-release") ? "musl" : "gnu";
+}
+/**
+* Map `process.platform`/`arch` to the prebuild triple. The binary is built for
+* musl as well as glibc, so Alpine/musl images resolve a prebuild rather than
+* being rejected for their libc.
+*/
+function platformTriple(platform = process.platform, arch = process.arch, libc = platform === "linux" ? detectLinuxLibc() : "gnu") {
+	if (platform === "darwin" && arch === "arm64") return "darwin-arm64";
+	if (platform === "darwin" && arch === "x64") return "darwin-x64";
+	if (platform === "linux") {
+		if (arch === "x64") return `linux-x64-${libc}`;
+		if (arch === "arm64") return `linux-arm64-${libc}`;
+	}
+	throw new AlienError(UnsupportedPlatformError.create({
+		platform,
+		arch
+	}));
+}
+/** Walk up from `startDir` to find the locally-built binary, or `undefined`. */
+function findLocalBinary(startDir = dirname(fileURLToPath(import.meta.url))) {
+	let dir = startDir;
+	for (;;) {
+		for (const profile of ["release", "debug"]) {
+			const candidate = join(dir, "target", profile, BINARY_NAME);
+			if (existsSync(candidate)) return candidate;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+}
+let cached;
+let embeddedBinaryPath;
+/**
+* Register the bun-embedded binary path, so plain `@alienplatform/ai-gateway`
+* imports (which resolve through {@link resolveGatewayBinary}) find it inside a
+* `bun build --compile` binary, where the filesystem/prebuild resolution below
+* cannot. In a normal install this is never called. The `/native` entry calls it.
+*/
+function registerEmbeddedBinary(path) {
+	embeddedBinaryPath = path;
+}
+/** Resolve (and memoize) a runnable path to the launcher binary, or throw. */
+async function resolveGatewayBinary() {
+	if (cached) return cached;
+	if (embeddedBinaryPath) {
+		cached = await extractEmbedded(embeddedBinaryPath);
+		return cached;
+	}
+	const override = process.env.ALIEN_AI_GATEWAY_BINARY_PATH;
+	if (override) {
+		cached = ensureExecutable(resolve(override));
+		return cached;
+	}
+	const staged = resolve(BINARY_NAME);
+	if (existsSync(staged) && statSync(staged).size > 0) {
+		cached = ensureExecutable(staged);
+		return cached;
+	}
+	const triple = platformTriple();
+	const prebuild = await resolvePrebuild(triple);
+	if (prebuild) {
+		cached = ensureExecutable(prebuild);
+		return cached;
+	}
+	const local = findLocalBinary();
+	if (local) {
+		cached = ensureExecutable(local);
+		return cached;
+	}
+	throw new AlienError(GatewayBinaryUnavailableError.create({
+		triple,
+		reason: `no embedded binary, no ALIEN_AI_GATEWAY_BINARY_PATH, no ./${BINARY_NAME} staged by the worker base, no '@alienplatform/ai-gateway-${triple}' prebuild, and no locally-built target/{release,debug}/${BINARY_NAME}; build it with \`cargo build --bin ${BINARY_NAME} -p alien-ai-gateway\``
+	}));
+}
+/**
+* Copy a bun-embedded binary to a real, executable temp file. Only reached inside
+* a `bun build --compile` binary, where `Bun` is present and the embedded file
+* must live on disk with the execute bit set before it can be spawned.
+*/
+async function extractEmbedded(virtualPath) {
+	const bun = globalThis.Bun;
+	if (!bun) throw new AlienError(GatewayBinaryUnavailableError.create({
+		triple: platformTriple(),
+		path: virtualPath,
+		reason: "an embedded gateway binary can only be extracted under the Bun runtime"
+	}));
+	try {
+		const bytes = await bun.file(virtualPath).arrayBuffer();
+		const exe = join(mkdtempSync(join(tmpdir(), "alien-ai-gateway-")), BINARY_NAME);
+		writeFileSync(exe, Buffer.from(bytes));
+		chmodSync(exe, 493);
+		return exe;
+	} catch (error) {
+		throw (await AlienError.from(error)).withContext(GatewayBinaryUnavailableError.create({
+			triple: platformTriple(),
+			path: virtualPath,
+			reason: "failed to extract the embedded gateway binary"
+		}));
+	}
+}
+/** Best-effort execute bit; a prebuild may already be executable or read-only. */
+function ensureExecutable(path) {
+	try {
+		chmodSync(path, 493);
+	} catch {}
+	return path;
+}
+/** Resolve the binary shipped by the per-platform prebuild package, or `undefined`. */
+async function resolvePrebuild(triple) {
+	const pkg = `@alienplatform/ai-gateway-${triple}`;
+	let pkgJson;
+	try {
+		pkgJson = require.resolve(`${pkg}/package.json`);
+	} catch (error) {
+		if (error.code === "MODULE_NOT_FOUND") return void 0;
+		throw (await AlienError.from(error)).withContext(GatewayBinaryUnavailableError.create({
+			triple,
+			reason: `the '${pkg}' prebuild is installed but could not be resolved`
+		}));
+	}
+	const candidate = join(dirname(pkgJson), BINARY_NAME);
+	return existsSync(candidate) ? candidate : void 0;
+}
+//#endregion
+//#region src/gateway.ts
+/**
+* The gateway surface: obtain the loopback URL of the Alien AI gateway.
+*
+* Two paths, unified behind {@link Gateway.startAiGateway}:
+*   - A container launcher already started the gateway out of band and exec'd the
+*     app with `ALIEN_AI_GATEWAY_URL` set, so we use that URL directly.
+*   - Otherwise (an SDK Worker) we spawn the `alien-ai-gateway` binary ourselves,
+*     read the URL it prints, and keep the child alive for the process lifetime.
+*
+* Parameterized over how the binary is resolved so the lazy entry (`index.ts`) and
+* the compiled-embed entry (`native.ts`) share one implementation.
+*/
+/** The env var a container launcher sets after starting the gateway out of band. */
+const URL_ENV = "ALIEN_AI_GATEWAY_URL";
+/** The launcher serve mode; binds an ephemeral port and prints its URL. */
+const SERVE_FLAG = "--gateway-serve";
+function createGateway(resolveBinary) {
+	let started = null;
+	const forget = () => {
+		started = null;
+	};
+	async function startAiGateway() {
+		started ??= startOnce(resolveBinary, forget).catch((error) => {
+			forget();
+			throw error;
+		});
+		return started;
+	}
+	return { startAiGateway };
+}
+async function startOnce(resolveBinary, onGatewayLost) {
+	const preset = process.env[URL_ENV];
+	if (preset) return { url: preset };
+	const binary = await resolveBinary();
+	const child = spawn(binary, [SERVE_FLAG], { stdio: [
+		"ignore",
+		"pipe",
+		"pipe"
+	] });
+	trackChild(child);
+	const url = await readReadyUrl(child, binary);
+	keepChildAlive(child, onGatewayLost);
+	return { url };
+}
+/**
+* Read the gateway's `{"aiGatewayUrl":"..."}` line from stdout. Rejects (with the
+* child's stderr as the reason) if the process exits or errors before printing it.
+*/
+function readReadyUrl(child, binary) {
+	return new Promise((resolveUrl, rejectUrl) => {
+		let stdout = "";
+		let stderr = "";
+		const cleanup = () => {
+			child.stdout?.off("data", onStdout);
+			child.stderr?.off("data", onStderr);
+			child.off("exit", onExit);
+			child.off("error", onError);
+		};
+		const onStdout = (chunk) => {
+			stdout += chunk.toString();
+			const url = parseReadyUrl(stdout);
+			if (url) {
+				cleanup();
+				resolveUrl(url);
+			}
+		};
+		const onStderr = (chunk) => {
+			stderr += chunk.toString();
+		};
+		const onExit = (code, signal) => {
+			cleanup();
+			rejectUrl(new AlienError(GatewayStartFailedError.create({ reason: stderr.trim() || `process exited (${signal ?? `code ${code ?? "null"}`}) before reporting a URL` })));
+		};
+		const onError = async (error) => {
+			cleanup();
+			let triple;
+			try {
+				triple = platformTriple();
+			} catch {
+				triple = `${process.platform}-${process.arch}`;
+			}
+			rejectUrl((await AlienError.from(error)).withContext(GatewayBinaryUnavailableError.create({
+				triple,
+				path: binary,
+				reason: "could not execute the gateway binary"
+			})));
+		};
+		child.stdout?.on("data", onStdout);
+		child.stderr?.on("data", onStderr);
+		child.on("exit", onExit);
+		child.on("error", onError);
+	});
+}
+/** Extract the URL from the launcher's machine-readable stdout line, if present. */
+function parseReadyUrl(buffered) {
+	for (const line of buffered.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("{")) continue;
+		try {
+			const parsed = JSON.parse(trimmed);
+			if (typeof parsed.aiGatewayUrl === "string") return parsed.aiGatewayUrl;
+		} catch {}
+	}
+}
+let liveChild;
+let reaperInstalled = false;
+/** Reap whatever child is live when this process is torn down. Installed once. */
+function installReaper() {
+	if (reaperInstalled) return;
+	reaperInstalled = true;
+	const killLive = () => {
+		try {
+			liveChild?.kill("SIGTERM");
+		} catch {}
+	};
+	process.once("exit", killLive);
+	for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => {
+		killLive();
+		process.kill(process.pid, signal);
+	});
+}
+/**
+* Track a freshly spawned child as the live gateway and guard it synchronously, at
+* spawn time (before the ready-await). A live child stream with no 'error' listener
+* throws on any I/O fault and crashes the host, so attach permanent no-op stream
+* guards now (`readReadyUrl` only adds 'data' listeners; the child itself always has
+* an 'error' listener, `readReadyUrl`'s during startup then `keepChildAlive`'s after).
+*/
+function trackChild(child) {
+	liveChild = child;
+	installReaper();
+	child.stdout?.on("error", () => {});
+	child.stderr?.on("error", () => {});
+}
+/**
+* Unref a child stdio stream's underlying handle. `stdout`/`stderr` are typed `Readable` but are
+* `net.Socket` at runtime and carry `.unref()`; the guard makes a non-socket or absent stream a
+* no-op instead of a crash.
+*/
+function unrefStream(stream) {
+	const s = stream;
+	if (s && typeof s.unref === "function") s.unref();
+}
+/**
+* Once the child is serving, hold it for the app's lifetime: drain its stdio so the
+* pipes never fill and block it, then unref both the stdio sockets and the child so it
+* never keeps the event loop alive on its own. `resume()` keeps the pipe sockets
+* referenced, so unref-ing the child alone leaves a one-shot host (a CLI/batch/test
+* process that calls `ai()` once) unable to exit — the sockets must be unref'd too. On a
+* later exit/error, forget the memoized handle so the next call respawns rather than
+* reusing a dead URL (`trackChild` already installed the reaper and stream guards at
+* spawn time).
+*/
+function keepChildAlive(child, onGatewayLost) {
+	const onGone = () => {
+		if (liveChild === child) liveChild = void 0;
+		onGatewayLost();
+	};
+	child.on("error", onGone);
+	child.on("exit", onGone);
+	child.stdout?.resume();
+	child.stderr?.resume();
+	unrefStream(child.stdout);
+	unrefStream(child.stderr);
+	child.unref();
+}
+//#endregion
+export { createAiClient as a, BindingNotFoundError as c, isExternalAiBinding as d, parseAiBinding as f, Ai as i, InvalidBindingConfigError$1 as l, registerEmbeddedBinary as n, AiTransportError as o, resolveGatewayBinary as r, AiUpstreamError as s, createGateway as t, aiBindingEnvVarName as u };