@rivus/gateway 0.18.1 → 0.19.0

package/dist/chunks/rivus-node-entrypoint.js

@@ -1,15 +1,18 @@
-import { S as deepFreeze, _ as loadMergedLocalEnvFile, b as validateRivusDeploymentManifest, c as parseRivusModelCliArguments, f as gatewayPackageManifestPath, g as loadRivusDaemonConfig, h as loadRivusDeploymentManifest, i as RIVUS_RELEASE_DESCRIPTOR, l as renderRivusModelCliArgumentError, m as gatewayTemplateDirectory, n as disposeRuntimeCacheEntries, r as invokeRuntimeControl, s as createRivusModelManagementWireRequest, t as createRuntimeCache, u as renderRivusModelCliHelp, v as resolveFeishuEndpointCredentials, x as validateRivusProjectSpaceDeployment, y as InvalidRivusProjectSpace } from "./runtime-cache.js";
+import { C as validateRivusDeploymentManifest, S as InvalidRivusProjectSpace, T as deepFreeze, _ as gatewayTemplateDirectory, a as invokeRuntimeControl, b as loadMergedLocalEnvFile, d as renderRivusModelCliArgumentError, f as renderRivusModelCliHelp, h as gatewayPackageManifestPath, i as disposeRuntimeCacheEntries, l as createRivusModelManagementWireRequest, n as withoutRivusHomeDeployment, o as RIVUS_RELEASE_DESCRIPTOR, p as gatewayAudioTranscriberAssetDirectory, r as createRuntimeCache, t as RIVUS_HOME_DEPLOYMENT_ENV, u as parseRivusModelCliArguments, v as loadRivusDeploymentManifest, w as validateRivusProjectSpaceDeployment, x as resolveFeishuEndpointCredentials, y as loadRivusDaemonConfig } from "./rivus-home-deployment-env.js";
 import { n as narrowBackgroundSessionDefinition, t as createBackgroundSessionToolContracts } from "./background-session-authority.js";
 import { createRequire } from "node:module";
 import { createSha256Digest, createStableId } from "@rivus/platform/identity";
 import { RIVUS_MEMORY_TOOL_PLUGIN_ID, RIVUS_RUNTIME_TOOL_IDS, createRivusMemoryToolContract, isRivusRuntimeToolId } from "@rivus/runtime";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { Cause, Deferred, Effect, Exit, Result, Semaphore } from "effect";
-import { lstat, mkdir, open, readFile, readdir, realpath, rmdir, stat, unlink, writeFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
+import { Cause, Deferred, Effect, Exit, Option, Result, Schema, Semaphore } from "effect";
+import { cp, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
 import { assertPathWithin, isPathWithin } from "@rivus/platform/filesystem";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { readPersistenceFile, writeAtomicTextFile } from "@rivus/platform/persistence";
+import { spawn } from "node:child_process";
 import { createConnection } from "node:net";
 import { constants as constants$1 } from "node:fs";
 import { unwrapExit } from "@rivus/platform/effect";
@@ -952,6 +955,561 @@ function createNodeRivusHome(options) {
 		setup: initializeRivusHome
 	};
 }
+const RIVUS_AUDIO_CLI_USAGE = `Usage:
+  rivus audio install [--force] [--json]
+  rivus audio status
+  rivus audio transcribe <path>
+
+Commands:
+  install     Install or upgrade the managed audio transcriber in the current Home's state directory
+  status      Print the installed and shipped transcriber releases as JSON
+  transcribe  Print the transcript of one audio file; exits 2 when no speech is detected
+              and ${String(3)} when the transcriber is not installed
+`;
+function parseRivusAudioCliArguments(argv) {
+	if (argv.includes("--help") || argv.includes("-h")) return { help: true };
+	const [operation, ...rest] = argv;
+	if (operation === "install") {
+		const flags = new Set(rest);
+		const unknown = rest.find((argument) => argument !== "--force" && argument !== "--json");
+		if (unknown !== void 0) return { error: `Unknown audio install option: ${unknown}` };
+		if (flags.size !== rest.length) return { error: "audio install options may only be provided once" };
+		return {
+			force: flags.has("--force"),
+			json: flags.has("--json"),
+			operation
+		};
+	}
+	if (operation === "status") return rest.length === 0 ? { operation } : { error: "audio status accepts no arguments" };
+	if (operation === "transcribe") {
+		const path = rest[0];
+		if (rest.length !== 1 || !path || path.startsWith("-")) return { error: "audio transcribe requires exactly one audio path" };
+		return {
+			operation,
+			path
+		};
+	}
+	return { error: "audio requires one of install, status, transcribe" };
+}
+function renderRivusAudioCliArgumentError(error) {
+	return `${error}\n\n${RIVUS_AUDIO_CLI_USAGE}`;
+}
+function renderRivusAudioCliStatus(status) {
+	return `${JSON.stringify(status)}\n`;
+}
+function renderRivusAudioCliInstallResult(result, json) {
+	if (json) return `${JSON.stringify(result)}\n`;
+	return result.status === "installed" ? `Installed audio transcriber ${result.id} in ${result.release}\n` : `Audio transcriber ${result.id} is already installed in ${result.release}\n`;
+}
+function renderRivusAudioCliNotInstalled() {
+	return "audio transcriber is not installed; run: rivus audio install\n";
+}
+//#endregion
+//#region src/adapters/cli/audio/rivus-audio-install-lock.ts
+var RivusAudioInstallInProgressError = class extends Error {
+	constructor() {
+		super("another audio transcriber installation is in progress");
+		this.name = "RivusAudioInstallInProgressError";
+	}
+};
+const lockOwnerSchema = Schema.fromJsonString(Schema.Struct({
+	pid: Schema.Int,
+	startedAt: Schema.Number,
+	token: Schema.NonEmptyString
+}));
+/**
+* Takes the installation lock at `path`: a directory holding one owner record named by the owner's token. The record
+* is written into a private draft directory that is then renamed onto `path`, which succeeds only while `path` is
+* absent or empty, so a reader never observes a partially written lock. A lock whose pid is dead, whose record is
+* unreadable, or which is older than `maxAgeMs` is reclaimed by removing that record by name and then `path` only
+* while it is empty, so a reclaim based on an outdated reading never removes another installer's live lock.
+*/
+async function acquireRivusAudioInstallLock(path, options) {
+	const now = options.now ?? Date.now;
+	const isProcessAlive = options.isProcessAlive ?? isLiveProcess;
+	const owner = {
+		pid: process.pid,
+		startedAt: now(),
+		token: randomUUID()
+	};
+	const draft = `${path}.${owner.token}.draft`;
+	await mkdir(draft, { mode: 448 });
+	try {
+		await writeFile(join(draft, owner.token), `${JSON.stringify(owner)}\n`, {
+			flag: "wx",
+			mode: 384
+		});
+		for (let attempt = 0; attempt < 3; attempt += 1) {
+			if (await tryPublish(draft, path)) return { release: () => removeRecords(path, [owner.token]) };
+			const records = await readLockRecords(path);
+			if (records.some(({ owner: held }) => held !== void 0 && held.pid !== process.pid && isProcessAlive(held.pid) && now() - held.startedAt < options.maxAgeMs)) throw new RivusAudioInstallInProgressError();
+			await removeRecords(path, records.map(({ name }) => name));
+		}
+	} finally {
+		await rm(draft, {
+			force: true,
+			recursive: true
+		}).catch(() => void 0);
+	}
+	throw new RivusAudioInstallInProgressError();
+}
+async function tryPublish(draft, path) {
+	try {
+		await rename(draft, path);
+		return true;
+	} catch (error) {
+		if (hasErrorCode(error, "EEXIST") || hasErrorCode(error, "ENOTEMPTY")) return false;
+		throw error;
+	}
+}
+async function readLockRecords(path) {
+	const names = await readdir(path).catch((error) => {
+		if (hasErrorCode(error, "ENOENT")) return [];
+		throw error;
+	});
+	return Promise.all(names.map(async (name) => {
+		const text = await readPersistenceFile(join(path, name));
+		return {
+			name,
+			owner: text === void 0 ? void 0 : Option.getOrUndefined(Schema.decodeUnknownOption(lockOwnerSchema)(text))
+		};
+	}));
+}
+/**
+* Removes the named owner records and then the lock directory only if nothing else is in it, so a record that another
+* installer published meanwhile keeps the lock held.
+*/
+async function removeRecords(path, names) {
+	await Promise.all(names.map((name) => unlink(join(path, name)).catch(ignoreErrorCodes("ENOENT"))));
+	await rmdir(path).catch(ignoreErrorCodes("ENOENT", "ENOTEMPTY", "EEXIST"));
+}
+function ignoreErrorCodes(...codes) {
+	return (error) => {
+		if (!codes.some((code) => hasErrorCode(error, code))) throw error;
+	};
+}
+function isLiveProcess(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return hasErrorCode(error, "EPERM");
+	}
+}
+function hasErrorCode(error, code) {
+	return error?.code === code;
+}
+//#endregion
+//#region src/adapters/cli/audio/rivus-audio-release.ts
+const RIVUS_AUDIO_MANIFEST_FILE = "manifest.json";
+const RIVUS_AUDIO_RELEASES_DIRECTORY = "releases";
+const manifestSchema = Schema.fromJsonString(Schema.Struct({
+	id: Schema.NonEmptyString,
+	smoke: Schema.Struct({
+		expect: Schema.NonEmptyString,
+		input: Schema.NonEmptyString
+	})
+}));
+const currentSchema = Schema.fromJsonString(Schema.Struct({
+	digest: Schema.optional(Schema.NonEmptyString),
+	id: Schema.NonEmptyString,
+	release: Schema.NonEmptyString
+}));
+function rivusAudioCurrentPath(installRoot) {
+	return join(installRoot, "current.json");
+}
+async function readRivusAudioReleaseManifest(directory) {
+	const path = join(directory, RIVUS_AUDIO_MANIFEST_FILE);
+	const manifest = Option.getOrUndefined(Schema.decodeUnknownOption(manifestSchema)(await readFile(path, "utf8")));
+	if (manifest === void 0 || !isStrictlyWithin(directory, resolve(directory, manifest.smoke.input))) throw new Error(`audio transcriber manifest is invalid: ${path}`);
+	return manifest;
+}
+/**
+* Whether an entry of the asset directory, at any depth, belongs in a release. Dependencies come from the shrinkwrap
+* and colocated tests stay out of the published package, so a release never contains either and a workspace checkout
+* produces the same release and digest as the published package.
+*/
+function isRivusAudioReleaseAsset(name) {
+	return name !== "node_modules" && !name.endsWith(".test.ts");
+}
+/**
+* Digests the asset files that an installation copies, so an asset change reinstalls the transcriber even when the
+* manifest id stays the same.
+*/
+async function readRivusAudioAssetDigest(directory) {
+	const hash = createHash("sha256");
+	for (const file of (await listAssetFiles(directory, "")).sort()) {
+		const content = await readFile(join(directory, file));
+		hash.update(`${file}\0${String(content.length)}\0`).update(content);
+	}
+	return hash.digest("hex");
+}
+/**
+* Reads the release that current.json selects. A missing or malformed record, a release outside `releases/`, or a
+* missing release directory all mean "not installed", which a reinstall repairs.
+*/
+async function readRivusAudioInstalledRelease(installRoot) {
+	const text = await readPersistenceFile(rivusAudioCurrentPath(installRoot));
+	const current = text === void 0 ? void 0 : Option.getOrUndefined(Schema.decodeUnknownOption(currentSchema)(text));
+	if (current === void 0) return;
+	const directory = resolve(installRoot, current.release);
+	if (!isStrictlyWithin(join(installRoot, "releases"), directory)) return;
+	return await stat(directory).then((info) => info.isDirectory(), () => false) ? {
+		...current.digest === void 0 ? {} : { digest: current.digest },
+		directory,
+		id: current.id,
+		release: current.release
+	} : void 0;
+}
+async function readRivusAudioStatus(installRoot, assetDirectory) {
+	const expected = await readRivusAudioReleaseManifest(assetDirectory);
+	const expectedDigest = await readRivusAudioAssetDigest(assetDirectory);
+	const installed = await readRivusAudioInstalledRelease(installRoot);
+	return installed === void 0 ? {
+		installed: false,
+		expectedId: expected.id,
+		expectedDigest,
+		upToDate: false
+	} : {
+		installed: true,
+		id: installed.id,
+		...installed.digest === void 0 ? {} : { digest: installed.digest },
+		release: installed.directory,
+		expectedId: expected.id,
+		expectedDigest,
+		upToDate: installed.id === expected.id && installed.digest === expectedDigest
+	};
+}
+/** Lists the release asset files by relative path with "/" separators. */
+async function listAssetFiles(root, prefix) {
+	const entries = await readdir(join(root, prefix), { withFileTypes: true });
+	return (await Promise.all(entries.filter((entry) => isRivusAudioReleaseAsset(entry.name)).map(async (entry) => {
+		const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+		return entry.isDirectory() ? listAssetFiles(root, path) : [path];
+	}))).flat();
+}
+function isStrictlyWithin(root, candidate) {
+	return candidate !== resolve(root) && isPathWithin(root, candidate);
+}
+//#endregion
+//#region src/adapters/cli/audio/rivus-audio-installer.ts
+const INSTALL_DEADLINE_MS = 15e5;
+const NPM_TIMEOUT_MS = 3e5;
+const FETCH_TIMEOUT_MS = 12e5;
+const SMOKE_TIMEOUT_MS = 3e5;
+const STALE_LOCK_MS = 2 * INSTALL_DEADLINE_MS;
+const LOCK_POLL_MS = 2e3;
+const STAGING_PREFIX = "staging-";
+var RivusAudioInstallStepError = class extends Error {
+	step;
+	constructor(step, reason, output = "") {
+		const detail = output.trim().slice(-4e3);
+		super(`audio transcriber installation failed at ${step}: ${reason}${detail ? `\n${detail}` : ""}`);
+		this.name = "RivusAudioInstallStepError";
+		this.step = step;
+	}
+};
+/**
+* Builds a release in a staging directory beside `releases/`, smoke-tests it, then publishes it by renaming the
+* directory and atomically replacing current.json. A failure before current.json changes leaves the previous release
+* selected and removes the staging directory. While another installer holds the lock, this one waits within its
+* deadline and then rechecks current.json, so it does not rebuild a release that installer just published.
+*/
+async function installRivusAudioTranscriber(options) {
+	const now = options.now ?? Date.now;
+	const deadlineMs = options.deadlineMs ?? INSTALL_DEADLINE_MS;
+	const deadline = {
+		at: now() + deadlineMs,
+		ms: deadlineMs,
+		now
+	};
+	const root = resolve(options.installRoot);
+	await mkdir(root, { recursive: true });
+	const lock = await acquireLockWhenFree(root, options, deadline);
+	try {
+		await removeInterruptedStaging(root);
+		const manifest = await readRivusAudioReleaseManifest(options.assetDirectory);
+		const digest = await readRivusAudioAssetDigest(options.assetDirectory);
+		const previous = await readRivusAudioInstalledRelease(root);
+		if (!options.force && previous?.id === manifest.id && previous.digest === digest) return {
+			status: "already-installed",
+			id: previous.id,
+			release: previous.directory
+		};
+		const release = await buildRelease(root, manifest, digest, options, deadline);
+		await pruneReleases(root, [release, previous?.directory]);
+		return {
+			status: "installed",
+			id: manifest.id,
+			release
+		};
+	} finally {
+		await lock.release().catch(() => void 0);
+	}
+}
+async function acquireLockWhenFree(root, options, deadline) {
+	const sleep = options.sleep ?? ((ms) => sleepUnlessAborted(ms, options.signal));
+	for (;;) {
+		try {
+			return await acquireRivusAudioInstallLock(join(root, "install.lock"), {
+				maxAgeMs: STALE_LOCK_MS,
+				...options.isProcessAlive ? { isProcessAlive: options.isProcessAlive } : {}
+			});
+		} catch (error) {
+			if (!(error instanceof RivusAudioInstallInProgressError)) throw error;
+		}
+		const remainingMs = deadline.at - deadline.now();
+		if (remainingMs <= 0) throw new Error("another audio transcriber installation did not finish in time");
+		await sleep(Math.min(LOCK_POLL_MS, remainingMs));
+		if (options.signal?.aborted) throw new Error("audio transcriber installation was interrupted while waiting for another installation");
+	}
+}
+function sleepUnlessAborted(ms, signal) {
+	return setTimeout$1(ms, void 0, signal ? { signal } : {}).catch(() => void 0);
+}
+async function buildRelease(root, manifest, digest, options, deadline) {
+	const staging = join(root, `${STAGING_PREFIX}${randomUUID()}`);
+	const release = join(root, RIVUS_AUDIO_RELEASES_DIRECTORY, `${manifest.id.replaceAll(/[^\w.-]/g, "_")}-${digest.slice(0, 12)}-${randomUUID().slice(0, 8)}`);
+	const env = withNodeOnPath(options.env, options.nodeExecutable);
+	let renamed = false;
+	try {
+		await cp(options.assetDirectory, staging, {
+			filter: (source) => isRivusAudioReleaseAsset(basename(source)),
+			recursive: true
+		}).catch((error) => {
+			throw new RivusAudioInstallStepError("copy assets", errorMessage(error));
+		});
+		await runStep(options, deadline, "npm ci", {
+			args: [
+				"ci",
+				"--ignore-scripts",
+				"--omit=dev",
+				"--no-audit",
+				"--no-fund"
+			],
+			command: "npm",
+			cwd: staging,
+			env,
+			timeoutMs: NPM_TIMEOUT_MS
+		});
+		await runStep(options, deadline, "model download", {
+			args: [
+				"fetch-model.mjs",
+				RIVUS_AUDIO_MANIFEST_FILE,
+				"model"
+			],
+			command: options.nodeExecutable,
+			cwd: staging,
+			env,
+			timeoutMs: FETCH_TIMEOUT_MS
+		});
+		const { RIVUS_AUDIO_LANGUAGE: _language, ...smokeEnv } = env;
+		const smoke = await runStep(options, deadline, "smoke test", {
+			args: ["transcribe.mjs", resolve(staging, manifest.smoke.input)],
+			command: options.nodeExecutable,
+			cwd: staging,
+			env: smokeEnv,
+			timeoutMs: SMOKE_TIMEOUT_MS
+		});
+		if (smoke.stderrTail !== "") throw new RivusAudioInstallStepError("smoke test", "the transcriber wrote to stderr", smoke.stderrTail);
+		if (!smoke.stdout.includes(manifest.smoke.expect)) throw new RivusAudioInstallStepError("smoke test", `the transcript does not contain ${JSON.stringify(manifest.smoke.expect)}`, smoke.stdout);
+		await mkdir(dirname(release), { recursive: true });
+		await rename(staging, release);
+		renamed = true;
+		await writeAtomicTextFile(rivusAudioCurrentPath(root), `${JSON.stringify({
+			id: manifest.id,
+			digest,
+			release: relative(root, release)
+		})}\n`, { durable: true });
+		return release;
+	} catch (error) {
+		if ((renamed ? await readRivusAudioInstalledRelease(root).then((installed) => installed?.directory, () => void 0) : void 0) !== release) await rm(renamed ? release : staging, {
+			force: true,
+			recursive: true
+		}).catch(() => void 0);
+		throw error instanceof RivusAudioInstallStepError ? error : new RivusAudioInstallStepError("publish", errorMessage(error));
+	}
+}
+async function runStep(options, deadline, step, request) {
+	if (options.signal?.aborted) throw new RivusAudioInstallStepError(step, "interrupted");
+	const deadlineReason = `the installation did not finish within ${seconds(deadline.ms)} s`;
+	const remainingMs = deadline.at - deadline.now();
+	if (remainingMs <= 0) throw new RivusAudioInstallStepError(step, deadlineReason);
+	const timeoutMs = Math.min(request.timeoutMs, remainingMs);
+	const result = await options.runProcess({
+		...request,
+		timeoutMs,
+		...options.signal ? { signal: options.signal } : {}
+	}).catch((error) => {
+		throw new RivusAudioInstallStepError(step, `could not start ${request.command}: ${errorMessage(error)}`);
+	});
+	if (result.outcome === "timed-out") throw new RivusAudioInstallStepError(step, timeoutMs < request.timeoutMs ? deadlineReason : `timed out after ${seconds(request.timeoutMs)} s`, result.stderrTail);
+	if (result.outcome === "interrupted") throw new RivusAudioInstallStepError(step, "interrupted", result.stderrTail);
+	if (result.exitCode !== 0) throw new RivusAudioInstallStepError(step, `exited with code ${String(result.exitCode)}`, result.stderrTail);
+	return result;
+}
+async function removeInterruptedStaging(root) {
+	const entries = await readdir(root);
+	await Promise.all(entries.filter((name) => name.startsWith(STAGING_PREFIX)).map((name) => join(root, name)).map((path) => rm(path, {
+		force: true,
+		maxRetries: 5,
+		recursive: true
+	}).catch((error) => {
+		throw new RivusAudioInstallStepError("staging cleanup", `could not remove the staging directory of an interrupted installation, ${path}: ${errorMessage(error)}`);
+	})));
+}
+/** Keeps the new and the previous release, so a transcription that started before the switch can still finish. */
+async function pruneReleases(root, keep) {
+	const directory = join(root, RIVUS_AUDIO_RELEASES_DIRECTORY);
+	const kept = new Set(keep.filter((path) => path !== void 0));
+	const entries = await readdir(directory).catch(() => []);
+	await Promise.all(entries.map((name) => join(directory, name)).filter((path) => !kept.has(path)).map((path) => rm(path, {
+		force: true,
+		recursive: true
+	}).catch(() => void 0)));
+}
+/** npm may be missing from a service PATH, but it is installed beside the running Node executable. */
+function withNodeOnPath(env, nodeExecutable) {
+	const nodeDirectory = dirname(nodeExecutable);
+	return {
+		...env,
+		PATH: env.PATH ? `${nodeDirectory}${delimiter}${env.PATH}` : nodeDirectory
+	};
+}
+function seconds(ms) {
+	return String(ms / 1e3);
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/adapters/cli/audio/rivus-audio-process.ts
+const OUTPUT_LIMIT = 65536;
+const KILL_GRACE_MS = 2e3;
+/**
+* Runs one installation step. This CLI's own timeout or interruption signals only the step process, so a step must not
+* start processes of its own: npm ci runs with --ignore-scripts and the asset scripts are plain Node.
+*/
+function runRivusAudioProcess(request) {
+	return new Promise((resolve, reject) => {
+		let stdout = "";
+		let stderrTail = "";
+		const child = spawnInCallerGroup(request, (text) => {
+			stdout = stdout.length >= OUTPUT_LIMIT ? stdout : (stdout + text).slice(0, OUTPUT_LIMIT);
+		}, (text) => {
+			stderrTail = (stderrTail + text).slice(-65536);
+		});
+		let outcome = "exited";
+		let exitCode = null;
+		let exited = false;
+		let escalation;
+		const stop = (reason) => {
+			if (exited || outcome !== "exited") return;
+			outcome = reason;
+			child.kill("SIGTERM");
+			escalation = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
+		};
+		const onAbort = () => stop("interrupted");
+		const timeout = setTimeout(() => stop("timed-out"), request.timeoutMs);
+		const finish = () => {
+			clearTimeout(timeout);
+			clearTimeout(escalation);
+			request.signal?.removeEventListener("abort", onAbort);
+		};
+		request.signal?.addEventListener("abort", onAbort, { once: true });
+		if (request.signal?.aborted) onAbort();
+		child.once("exit", (code) => {
+			exited = true;
+			exitCode = code;
+		});
+		child.once("error", (error) => {
+			finish();
+			reject(error);
+		});
+		child.once("close", () => {
+			finish();
+			resolve({
+				exitCode,
+				outcome,
+				stderrTail,
+				stdout
+			});
+		});
+	});
+}
+/** Streams the transcriber's stdout and stderr to the caller and resolves with its exit code. */
+function runRivusAudioPassthroughProcess(request) {
+	return new Promise((resolve, reject) => {
+		const child = spawnInCallerGroup(request, (text) => request.stdout.write(text), (text) => request.stderr.write(text));
+		const onAbort = () => {
+			child.kill("SIGTERM");
+		};
+		request.signal?.addEventListener("abort", onAbort, { once: true });
+		child.once("error", (error) => {
+			request.signal?.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+		child.once("close", (code) => {
+			request.signal?.removeEventListener("abort", onAbort);
+			resolve(code);
+		});
+	});
+}
+/**
+* Starts a child in the caller's process group, because Pi stops a timed-out or aborted bash command by killing that
+* group and the child must stop with it.
+*/
+function spawnInCallerGroup(request, onStdout, onStderr) {
+	const child = spawn(request.command, [...request.args], {
+		cwd: request.cwd,
+		env: { ...request.env },
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	child.stdout.setEncoding("utf8").on("data", onStdout);
+	child.stderr.setEncoding("utf8").on("data", onStderr);
+	return child;
+}
+//#endregion
+//#region src/adapters/cli/audio/rivus-audio-cli.ts
+/** Runs one parsed `rivus audio` command and returns its exit code; installation failures are thrown. */
+async function runRivusAudioCliCommand(command, context) {
+	if (command.operation === "install") {
+		const result = await installRivusAudioTranscriber({
+			assetDirectory: context.assetDirectory,
+			env: context.env,
+			force: command.force,
+			installRoot: context.installRoot,
+			nodeExecutable: context.nodeExecutable,
+			runProcess: context.runProcess,
+			...context.signal ? { signal: context.signal } : {}
+		});
+		context.stdout.write(renderRivusAudioCliInstallResult(result, command.json));
+		return 0;
+	}
+	if (command.operation === "status") {
+		context.stdout.write(renderRivusAudioCliStatus(await readRivusAudioStatus(context.installRoot, context.assetDirectory)));
+		return 0;
+	}
+	const release = await readRivusAudioInstalledRelease(context.installRoot);
+	if (release === void 0) {
+		context.stderr.write(renderRivusAudioCliNotInstalled());
+		return 3;
+	}
+	const exitCode = await runRivusAudioPassthroughProcess({
+		args: [join(release.directory, "transcribe.mjs"), resolve(context.cwd, command.path)],
+		command: context.nodeExecutable,
+		cwd: release.directory,
+		env: context.env,
+		...context.signal ? { signal: context.signal } : {},
+		stderr: context.stderr,
+		stdout: context.stdout
+	});
+	return exitCode === 0 || exitCode === 1 || exitCode === 2 ? exitCode : 1;
+}
 //#endregion
 //#region src/adapters/cli/command/rivus-cli-protocol.ts
 const RIVUS_CLI_USAGE = `Usage:
@@ -962,6 +1520,7 @@ const RIVUS_CLI_USAGE = `Usage:
   rivus init [directory]
   rivus doctor [directory] [--env-file <path>]
   rivus model <status|set|rollback> ...
+  rivus audio <install|status|transcribe> ...
   rivus --bootstrap <module> [--manifest <rivus.config.json>] [options]
 
 Commands:
@@ -973,6 +1532,7 @@ Commands:
   init      Create a standalone local Rivus project without overwriting files
   doctor    Check Rivus Home by default, or an explicit standalone project directory
   model     Query or change the managed default model through the current Home
+  audio     Install, inspect, or run the managed audio transcriber of the current Home
 
 Run rivus --help for the complete daemon option list.
 `;
@@ -1945,6 +2505,7 @@ Project commands:
   rivus init [directory]
   rivus doctor [directory] [--env-file <path>]
   rivus model <status|set|rollback> ...
+  rivus audio <install|status|transcribe> ...
 
 Options:
   --bootstrap <module>  Module exporting createRivusDaemonProcess(context)
@@ -3948,7 +4509,10 @@ function runRivusDaemonCli(options) {
 			return 0;
 		}
 		const env = yield* Effect.tryPromise({
-			try: () => loadCliEnv(parsed.envFilePath, options.env),
+			try: async () => {
+				const loaded = await loadCliEnv(parsed.envFilePath, options.env);
+				return options.env["RIVUS_HOME_DEPLOYMENT_DIR"] === void 0 ? withoutRivusHomeDeployment(loaded) : loaded;
+			},
 			catch: (error) => error
 		});
 		const bootstrapSpecifier = parsed.bootstrap ?? env.RIVUS_BOOTSTRAP_MODULE?.trim();
@@ -4159,11 +4723,15 @@ function runRivusCli(options) {
 	if (command === "init") return runInitCommand(options);
 	if (command === "doctor") return runDoctorCommand(options);
 	if (command === "model") return runModelCommand(options);
+	if (command === "audio") return runAudioCommand(options);
 	if (command && !command.startsWith("-")) return Effect.sync(() => {
 		options.stderr.write(renderRivusCliUnknownCommand(command));
 		return 1;
 	});
-	return runRivusDaemonCli(options);
+	return runRivusDaemonCli({
+		...options,
+		env: withoutRivusHomeDeployment(options.env)
+	});
 }
 function runModelCommand(options) {
 	const parsed = parseRivusModelCliArguments(options.argv.slice(1));
@@ -4223,6 +4791,38 @@ function modelTransportFailure(error) {
 		status: "failed"
 	};
 }
+function runAudioCommand(options) {
+	const parsed = parseRivusAudioCliArguments(options.argv.slice(1));
+	if ("help" in parsed) return Effect.sync(() => {
+		options.stdout.write(RIVUS_AUDIO_CLI_USAGE);
+		return 0;
+	});
+	if ("error" in parsed) return Effect.sync(() => {
+		options.stderr.write(renderRivusAudioCliArgumentError(parsed.error));
+		return 1;
+	});
+	return resolveHomeDirectoryEffect(options).pipe(Effect.flatMap((directory) => options.homeApi.load(directory)), Effect.flatMap((home) => Effect.tryPromise({
+		try: () => runRivusAudioCliCommand(parsed, {
+			assetDirectory: gatewayAudioTranscriberAssetDirectory,
+			cwd: options.cwd,
+			env: options.env,
+			installRoot: join(home.stateDirectory, "audio-transcriber"),
+			nodeExecutable: options.nodeExecutable,
+			runProcess: runRivusAudioProcess,
+			signal: abortOnInterruption(options.signalSource),
+			stderr: options.stderr,
+			stdout: options.stdout
+		}),
+		catch: (error) => error
+	})), Effect.catch((error) => writeError(options, error)));
+}
+/** Lets an interrupted install stop its child processes and remove its staging directory before the CLI exits. */
+function abortOnInterruption(signalSource) {
+	const controller = new AbortController();
+	signalSource.on("SIGINT", () => controller.abort());
+	signalSource.on("SIGTERM", () => controller.abort());
+	return controller.signal;
+}
 function runSetupCommand(options) {
 	return withOptionalDirectoryArgument(options, "setup", (argument) => resolveHomeDirectoryEffect(options, argument).pipe(Effect.flatMap((directory) => options.homeApi.setup(directory).pipe(Effect.tap(() => Effect.sync(() => options.stdout.write(renderRivusSetupSuccess(directory)))), Effect.as(0))), Effect.catch((error) => writeError(options, error))));
 }
@@ -4245,7 +4845,8 @@ function runHomeDaemonCommand(options, command, daemonArgs) {
 		env: {
 			...options.env,
 			RIVUS_DEPLOYMENT_STATE_DIR: home.stateDirectory,
-			RIVUS_HOME: home.directory
+			RIVUS_HOME: home.directory,
+			[RIVUS_HOME_DEPLOYMENT_ENV]: home.directory
 		},
 		pluginPackageManifestPath: options.pluginPackageManifestPath ?? gatewayPackageManifestPath
 	})), Effect.catch((error) => writeError(options, error)));