@xopcai/xopc 0.0.221 → 0.0.223

package/dist/src/tunnel/env.js

@@ -1,6 +1,13 @@
 //#region src/tunnel/env.ts
 const DEV_REGISTRATION_SECRET = "dev-registration-secret";
-const TUNNEL_MASKED_SECRET_SENTINELS = ["***", "••••••••••••"];
+const TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE = "TUNNEL_REGISTRATION_SECRET_REQUIRED";
+var TunnelRegistrationSecretError = class extends Error {
+	code = TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE;
+	constructor(brokerUrl) {
+		super(tunnelRegistrationSecretRequiredMessage(brokerUrl));
+		this.name = "TunnelRegistrationSecretError";
+	}
+};
 function brokerHostname(brokerUrl) {
 	try {
 		const normalized = brokerUrl.includes("://") ? brokerUrl : `https://${brokerUrl}`;
@@ -9,13 +16,12 @@ function brokerHostname(brokerUrl) {
 		return null;
 	}
 }
-/** True when the broker is the public frp.xopc.ai service (not local dev). */
-function isProductionTunnelBroker(brokerUrl) {
+/** True only for brokers that are safe to use with the built-in development secret. */
+function isLocalDevelopmentTunnelBroker(brokerUrl) {
 	const host = brokerHostname(brokerUrl);
-	if (!host) return true;
-	if (host === "localhost" || host === "127.0.0.1" || host === "::1") return false;
-	if (host.endsWith(".local")) return false;
-	return host === "frp.xopc.ai";
+	if (!host) return false;
+	if (host === "localhost" || host === "127.0.0.1" || host === "::1") return true;
+	return host.endsWith(".local");
 }
 function maskTunnelSecretForWeb(secret) {
 	const trimmed = secret.trim();
@@ -23,7 +29,6 @@ function maskTunnelSecretForWeb(secret) {
 	return "•".repeat(trimmed.length);
 }
 function isMaskedTunnelSecretPatchValue(value) {
-	if (TUNNEL_MASKED_SECRET_SENTINELS.includes(value)) return true;
 	return /^•+$/.test(value);
 }
 function effectiveBrokerUrl(brokerUrl, env) {
@@ -37,37 +42,40 @@ function readTunnelRegistrationSecretFromConfigOnly(config) {
 	return config?.tunnel?.registrationSecret?.trim() || null;
 }
 function getTunnelRegistrationSecretMeta(config, env = process.env, brokerUrl) {
-	if (env.XOPC_TUNNEL_REGISTRATION_SECRET?.trim()) return {
-		configured: true,
-		source: "env"
-	};
 	if (config?.tunnel?.registrationSecret?.trim()) return {
 		configured: true,
 		source: "config"
 	};
-	if (isProductionTunnelBroker(effectiveBrokerUrl(brokerUrl ?? config?.tunnel?.brokerUrl, env))) return {
-		configured: false,
-		source: "missing"
-	};
-	return {
+	if (isLocalDevelopmentTunnelBroker(effectiveBrokerUrl(brokerUrl ?? config?.tunnel?.brokerUrl, env))) return {
 		configured: true,
 		source: "dev_default"
 	};
+	return {
+		configured: false,
+		source: "missing"
+	};
+}
+function resolveOptionalTunnelRegistrationSecret(brokerUrl, configSecret) {
+	const fromConfig = configSecret?.trim();
+	if (fromConfig) return fromConfig;
+	return isLocalDevelopmentTunnelBroker(effectiveBrokerUrl(brokerUrl, process.env)) ? DEV_REGISTRATION_SECRET : void 0;
+}
+function tunnelRegistrationSecretRequiredMessage(brokerUrl) {
+	const effectiveUrl = effectiveBrokerUrl(brokerUrl, process.env);
+	const host = brokerHostname(effectiveUrl);
+	return `Tunnel registration secret is required for ${host === "frp.xopc.ai" ? "the XOPC public broker (frp.xopc.ai)" : `broker ${host ?? effectiveUrl}`}. Authorize XOPC from Remote access → Public internet, or create a Tunnel Registration Key at https://console.xopc.ai/access/client and save it there manually.`;
 }
 /**
 * Registration secret for Tunnel Broker register API.
-* Priority: env `XOPC_TUNNEL_REGISTRATION_SECRET` → `tunnel.registrationSecret` in config → dev default (non-production brokers only).
+* Resolve `tunnel.registrationSecret` from config, with a development default for local brokers.
 */
-function resolveTunnelRegistrationSecret(env = process.env, brokerUrl, configSecret) {
-	const fromEnv = env.XOPC_TUNNEL_REGISTRATION_SECRET?.trim();
-	if (fromEnv) return fromEnv;
-	const fromConfig = configSecret?.trim();
-	if (fromConfig) return fromConfig;
-	if (isProductionTunnelBroker(effectiveBrokerUrl(brokerUrl, env))) throw new Error("Tunnel registration secret is required for the production broker (frp.xopc.ai). Create a Tunnel Registration Key at https://console.xopc.ai/keys/tunnel and save it under Remote access → Public internet.");
-	return DEV_REGISTRATION_SECRET;
+function resolveTunnelRegistrationSecret(brokerUrl, configSecret) {
+	const secret = resolveOptionalTunnelRegistrationSecret(brokerUrl, configSecret);
+	if (secret) return secret;
+	throw new TunnelRegistrationSecretError(brokerUrl);
 }
 function resolveTunnelBrokerUrl(configBrokerUrl, env = process.env) {
 	return env.XOPC_TUNNEL_BROKER_URL ?? configBrokerUrl ?? "https://frp.xopc.ai/api";
 }
 //#endregion
-export { TUNNEL_MASKED_SECRET_SENTINELS, getTunnelRegistrationSecretMeta, isMaskedTunnelSecretPatchValue, isProductionTunnelBroker, maskTunnelSecretForWeb, readTunnelRegistrationSecretFromConfigOnly, resolveTunnelBrokerUrl, resolveTunnelRegistrationSecret };
+export { TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE, TunnelRegistrationSecretError, getTunnelRegistrationSecretMeta, isLocalDevelopmentTunnelBroker, isMaskedTunnelSecretPatchValue, maskTunnelSecretForWeb, readTunnelRegistrationSecretFromConfigOnly, resolveOptionalTunnelRegistrationSecret, resolveTunnelBrokerUrl, resolveTunnelRegistrationSecret, tunnelRegistrationSecretRequiredMessage };

package/dist/src/tunnel/gateway-lifecycle.js

@@ -2,7 +2,7 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { resolveGatewayEffectiveHost } from "../config/gateway-bind.js";
 import { hasValidTunnelConsent } from "./consent.js";
-import { resolveTunnelBrokerUrl, resolveTunnelRegistrationSecret } from "./env.js";
+import { resolveOptionalTunnelRegistrationSecret, resolveTunnelBrokerUrl } from "./env.js";
 import { getTunnelService } from "./tunnel-service.js";
 import { resolveFrpSubdomainHost } from "./frp-subdomain-host.js";
 import { fetchTunnelWellKnown } from "./well-known.js";
@@ -25,20 +25,9 @@ function wireTunnelEventsToGateway(service) {
 	tunnel.on("tunnel:progress", publish);
 }
 function applyTunnelServiceFromGatewayConfig(config, brokerUrl) {
-	let registrationSecret;
-	try {
-		registrationSecret = resolveTunnelRegistrationSecret(process.env, brokerUrl, config.tunnel?.registrationSecret);
-	} catch (err) {
-		const em = err instanceof Error ? err.message : String(err);
-		log.warn({
-			phase: "tunnel_configure",
-			errorMessage: em
-		}, em);
-		throw err;
-	}
 	getTunnelService().configure({
 		brokerUrl,
-		registrationSecret,
+		registrationSecret: resolveOptionalTunnelRegistrationSecret(brokerUrl, config.tunnel?.registrationSecret),
 		autoStart: config.tunnel?.autoStart ?? false,
 		gatewayHost: resolveGatewayEffectiveHost(config),
 		frpSubdomainHost: resolveFrpSubdomainHost(brokerUrl)

package/dist/src/tunnel/index.d.ts

@@ -6,7 +6,7 @@ export type { EnsureFrpcBinaryOptions, FrpcDownloadProgress } from './frpc-binar
 export { configureTunnelFromGatewayConfig, maybeAutoStartTunnelFromConfig, wireTunnelEventsToGateway, } from './gateway-lifecycle.js';
 export { fetchTunnelWellKnown, clearTunnelWellKnownCache } from './well-known.js';
 export type { TunnelWellKnownConfig, TunnelWellKnownTransport } from './well-known.js';
-export { getTunnelRegistrationSecretMeta, isProductionTunnelBroker, isMaskedTunnelSecretPatchValue, resolveTunnelBrokerUrl, resolveTunnelRegistrationSecret, } from './env.js';
+export { getTunnelRegistrationSecretMeta, isLocalDevelopmentTunnelBroker, isMaskedTunnelSecretPatchValue, resolveTunnelBrokerUrl, resolveOptionalTunnelRegistrationSecret, resolveTunnelRegistrationSecret, TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE, tunnelRegistrationSecretRequiredMessage, TunnelRegistrationSecretError, } from './env.js';
 export type { TunnelRegistrationSecretMeta, TunnelRegistrationSecretSource } from './env.js';
 export { logTunnelAudit } from './tunnel-audit.js';
 export type { TunnelAuditEvent } from './tunnel-audit.js';

package/dist/src/tunnel/index.js

@@ -1,7 +1,7 @@
 import { loadTunnelState, resolveTunnelStatePath, saveTunnelState } from "./tunnel-state.js";
 import { buildMobileConnectQrPayload, resolveLanGatewayUrl } from "./tunnel-qr.js";
 import { CURRENT_TUNNEL_CONSENT_VERSION, TUNNEL_CONSENT_REQUIRED_CODE, TUNNEL_RISK_SUMMARY_LINES, TunnelConsentError, assertTunnelMayStart, getTunnelConsentState, hasValidTunnelConsent } from "./consent.js";
-import { getTunnelRegistrationSecretMeta, isMaskedTunnelSecretPatchValue, isProductionTunnelBroker, resolveTunnelBrokerUrl, resolveTunnelRegistrationSecret } from "./env.js";
+import { TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE, TunnelRegistrationSecretError, getTunnelRegistrationSecretMeta, isLocalDevelopmentTunnelBroker, isMaskedTunnelSecretPatchValue, resolveOptionalTunnelRegistrationSecret, resolveTunnelBrokerUrl, resolveTunnelRegistrationSecret, tunnelRegistrationSecretRequiredMessage } from "./env.js";
 import { TunnelBrokerClient, resolveBrokerApiBase } from "./broker-client.js";
 import { FRPC_VERSION, clearFrpcPathForProcess, ensureFrpcBinary, publishFrpcPathForProcess } from "./frpc-binary.js";
 import { consumePairingSecret, createPairingSecret, resetPairingSessionsForTests } from "./pairing.js";
@@ -12,4 +12,4 @@ import { clearTunnelWellKnownCache, fetchTunnelWellKnown } from "./well-known.js
 import { configureTunnelFromGatewayConfig, maybeAutoStartTunnelFromConfig, wireTunnelEventsToGateway } from "./gateway-lifecycle.js";
 import { applyTunnelConsentToConfig, mergeTunnelConfigPatch, sanitizeTunnelConfig, setTunnelEnabledInConfig } from "./tunnel-config.js";
 import { consumeTunnelMutationLimit, resetTunnelMutationLimitsForTests } from "./tunnel-rate-limit.js";
-export { CURRENT_TUNNEL_CONSENT_VERSION, FRPC_VERSION, TUNNEL_CONSENT_REQUIRED_CODE, TUNNEL_RISK_SUMMARY_LINES, TunnelBrokerClient, TunnelConsentError, TunnelService, applyTunnelConsentToConfig, assertTunnelMayStart, buildMobileConnectQrPayload, clearFrpcPathForProcess, clearTunnelWellKnownCache, configureTunnelFromGatewayConfig, consumePairingSecret, consumeTunnelMutationLimit, createPairingSecret, ensureFrpcBinary, fetchTunnelWellKnown, getTunnelConsentState, getTunnelRegistrationSecretMeta, getTunnelService, hasValidTunnelConsent, hashGatewayToken, isMaskedTunnelSecretPatchValue, isProductionTunnelBroker, loadTunnelState, logTunnelAudit, maybeAutoStartTunnelFromConfig, mergeTunnelConfigPatch, publishFrpcPathForProcess, resetPairingSessionsForTests, resetTunnelMutationLimitsForTests, resolveBrokerApiBase, resolveFrpSubdomainHost, resolveLanGatewayUrl, resolveTunnelBrokerUrl, resolveTunnelRegistrationSecret, resolveTunnelStatePath, sanitizeTunnelConfig, saveTunnelState, setTunnelEnabledInConfig, wireTunnelEventsToGateway };
+export { CURRENT_TUNNEL_CONSENT_VERSION, FRPC_VERSION, TUNNEL_CONSENT_REQUIRED_CODE, TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE, TUNNEL_RISK_SUMMARY_LINES, TunnelBrokerClient, TunnelConsentError, TunnelRegistrationSecretError, TunnelService, applyTunnelConsentToConfig, assertTunnelMayStart, buildMobileConnectQrPayload, clearFrpcPathForProcess, clearTunnelWellKnownCache, configureTunnelFromGatewayConfig, consumePairingSecret, consumeTunnelMutationLimit, createPairingSecret, ensureFrpcBinary, fetchTunnelWellKnown, getTunnelConsentState, getTunnelRegistrationSecretMeta, getTunnelService, hasValidTunnelConsent, hashGatewayToken, isLocalDevelopmentTunnelBroker, isMaskedTunnelSecretPatchValue, loadTunnelState, logTunnelAudit, maybeAutoStartTunnelFromConfig, mergeTunnelConfigPatch, publishFrpcPathForProcess, resetPairingSessionsForTests, resetTunnelMutationLimitsForTests, resolveBrokerApiBase, resolveFrpSubdomainHost, resolveLanGatewayUrl, resolveOptionalTunnelRegistrationSecret, resolveTunnelBrokerUrl, resolveTunnelRegistrationSecret, resolveTunnelStatePath, sanitizeTunnelConfig, saveTunnelState, setTunnelEnabledInConfig, tunnelRegistrationSecretRequiredMessage, wireTunnelEventsToGateway };

package/dist/src/tunnel/tunnel-audit.d.ts

@@ -1,2 +1,2 @@
-export type TunnelAuditEvent = 'tunnel.consent' | 'tunnel.start' | 'tunnel.stop' | 'tunnel.release' | 'tunnel.start_denied' | 'tunnel.pair' | 'tunnel.exchange_token' | 'tunnel.enable_lan_pairing';
+export type TunnelAuditEvent = 'tunnel.consent' | 'tunnel.start' | 'tunnel.stop' | 'tunnel.release' | 'tunnel.start_denied' | 'tunnel.pair' | 'tunnel.exchange_token' | 'tunnel.registration_authorized' | 'tunnel.enable_lan_pairing';
 export declare function logTunnelAudit(event: TunnelAuditEvent, fields: Record<string, unknown>, message: string): void;

package/dist/src/tunnel/tunnel-config.d.ts

@@ -8,7 +8,7 @@ export declare function mergeTunnelConfigPatch(config: Config, patch: Record<str
 export declare function applyTunnelConsentToConfig(config: Config): void;
 export declare function setTunnelEnabledInConfig(config: Config, enabled: boolean): void;
 /**
- * Clear stale tunnel flags when consent is missing or outdated (Phase 2: config/runtime alignment).
+ * Clear stale tunnel flags when consent or broker credentials cannot support a start.
  * Returns true when `config.tunnel` was modified.
  */
 export declare function sanitizeTunnelConfig(config: Config): boolean;

package/dist/src/tunnel/tunnel-config.js

@@ -1,6 +1,6 @@
 import { TunnelConfigSchema, TunnelConsentSchema, init_schema } from "../config/schema.js";
 import { assertTunnelAutoStartAllowed, buildTunnelConsentRecord, hasValidTunnelConsent } from "./consent.js";
-import { isMaskedTunnelSecretPatchValue } from "./env.js";
+import { getTunnelRegistrationSecretMeta, isMaskedTunnelSecretPatchValue } from "./env.js";
 import { z } from "zod";
 //#region src/tunnel/tunnel-config.ts
 init_schema();
@@ -29,7 +29,11 @@ function mergeTunnelConfigPatch(config, patch) {
 		...config.tunnel ?? TunnelConfigSchema.parse({}),
 		...patchFields
 	};
-	if (parsed.data.registrationSecret === null) delete next.registrationSecret;
+	if (parsed.data.registrationSecret === null) {
+		delete next.registrationSecret;
+		next.enabled = false;
+		next.autoStart = false;
+	}
 	if (parsed.data.autoStart === true) {
 		const probeTunnel = TunnelConfigSchema.parse({
 			...next,
@@ -67,13 +71,14 @@ function setTunnelEnabledInConfig(config, enabled) {
 	config.tunnel.enabled = enabled;
 }
 /**
-* Clear stale tunnel flags when consent is missing or outdated (Phase 2: config/runtime alignment).
+* Clear stale tunnel flags when consent or broker credentials cannot support a start.
 * Returns true when `config.tunnel` was modified.
 */
 function sanitizeTunnelConfig(config) {
 	const tunnel = config.tunnel;
 	if (!tunnel) return false;
-	if (hasValidTunnelConsent(config)) return false;
+	const brokerReady = getTunnelRegistrationSecretMeta(config).configured;
+	if (hasValidTunnelConsent(config) && brokerReady) return false;
 	let changed = false;
 	if (tunnel.enabled) {
 		tunnel.enabled = false;

package/dist/src/tunnel/tunnel-service.d.ts

@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events';
 import type { TunnelQrPayload, TunnelStatus } from './tunnel-types.js';
 export type TunnelServiceConfig = {
     brokerUrl: string;
-    registrationSecret: string;
+    registrationSecret?: string;
     autoStart: boolean;
     gatewayHost: string;
     frpSubdomainHost: string;

package/dist/src/tunnel/tunnel-service.js

@@ -3,6 +3,7 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { clearTunnelState, loadTunnelState, saveTunnelState, updateTunnelState } from "./tunnel-state.js";
 import { buildMobileConnectQrPayload, resolveLanGatewayUrl } from "./tunnel-qr.js";
+import { TunnelRegistrationSecretError } from "./env.js";
 import { TunnelBrokerClient, resolveBrokerApiBase } from "./broker-client.js";
 import { clearFrpcPathForProcess, ensureFrpcBinary, publishFrpcPathForProcess } from "./frpc-binary.js";
 import { writeFrpcConfig } from "./frpc-config.js";
@@ -230,6 +231,7 @@ var TunnelService = class extends EventEmitter {
 				phase: "tunnel_resume"
 			}, "Persisted tunnel not resumable — registering again");
 		}
+		if (!cfg.registrationSecret) throw new TunnelRegistrationSecretError(cfg.brokerUrl);
 		return broker.register({
 			brokerUrl: resolveBrokerApiBase(cfg.brokerUrl),
 			registrationSecret: cfg.registrationSecret,
@@ -319,6 +321,7 @@ var TunnelService = class extends EventEmitter {
 				const cfg = this.serviceConfig;
 				if (!ctx || !cfg) return;
 				try {
+					if (!cfg.registrationSecret) throw new TunnelRegistrationSecretError(cfg.brokerUrl);
 					const registration = await broker.register({
 						brokerUrl: resolveBrokerApiBase(cfg.brokerUrl),
 						registrationSecret: cfg.registrationSecret,

package/dist/src/tunnel/well-known.d.ts

@@ -15,7 +15,7 @@ export type TunnelWellKnownConfig = {
 };
 /**
  * Fetch `/.well-known/tunnel-config` (broker URL, frp endpoints, frpc version).
- * Registration secret is never published here — use `XOPC_TUNNEL_REGISTRATION_SECRET`.
+ * Registration secrets are never published here.
  */
 export declare function fetchTunnelWellKnown(brokerUrl: string): Promise<TunnelWellKnownConfig>;
 export declare function pingTunnelBroker(brokerUrl: string): Promise<boolean>;

package/dist/src/tunnel/well-known.js

@@ -10,7 +10,7 @@ function brokerOrigin(brokerUrl) {
 }
 /**
 * Fetch `/.well-known/tunnel-config` (broker URL, frp endpoints, frpc version).
-* Registration secret is never published here — use `XOPC_TUNNEL_REGISTRATION_SECRET`.
+* Registration secrets are never published here.
 */
 async function fetchTunnelWellKnown(brokerUrl) {
 	const origin = brokerOrigin(brokerUrl);

package/dist/src/tunnel/xopc-cloud-registration.d.ts

@@ -0,0 +1,9 @@
+type ProvisionOptions = {
+    fetchImpl?: typeof fetch;
+    routerUrl?: string;
+    resolveAccessToken?: () => Promise<string | null>;
+    deviceName?: string;
+};
+/** Exchange a narrowly scoped XOPC OAuth grant for a tunnel registration key. */
+export declare function provisionTunnelRegistrationKey(options?: ProvisionOptions): Promise<string>;
+export {};

package/dist/src/tunnel/xopc-cloud-registration.js

@@ -0,0 +1,42 @@
+import { CredentialResolver, init_credentials } from "../auth/credentials.js";
+import { init_xopc_cloud_config, resolveXopcModelRouterUrl } from "../providers/xopc-cloud-config.js";
+import { hostname } from "node:os";
+import { z } from "zod";
+//#region src/tunnel/xopc-cloud-registration.ts
+init_credentials();
+init_xopc_cloud_config();
+const registrationResponseSchema = z.object({ key: z.string().min(1) });
+function responseError(body, status) {
+	if (body && typeof body === "object") {
+		const error = body.error;
+		if (error && typeof error === "object") {
+			const message = error.message;
+			if (typeof message === "string" && message.trim()) return message;
+		}
+	}
+	return `Tunnel registration failed (${status})`;
+}
+/** Exchange a narrowly scoped XOPC OAuth grant for a tunnel registration key. */
+async function provisionTunnelRegistrationKey(options = {}) {
+	const accessToken = await (options.resolveAccessToken ?? (() => new CredentialResolver().resolveApiKey("xopc-tunnel")))();
+	if (!accessToken) throw new Error("Authorize XOPC Public Tunnel before creating a registration key");
+	const routerUrl = resolveXopcModelRouterUrl(options.routerUrl);
+	const deviceName = options.deviceName?.trim() || hostname() || "XOPC gateway";
+	const response = await (options.fetchImpl ?? fetch)(`${routerUrl}/tunnel/registration-key`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${accessToken}`,
+			accept: "application/json",
+			"content-type": "application/json"
+		},
+		body: JSON.stringify({ name: deviceName.slice(0, 64) }),
+		signal: AbortSignal.timeout(3e4)
+	});
+	const body = await response.json().catch(() => null);
+	if (!response.ok) throw new Error(responseError(body, response.status));
+	const parsed = registrationResponseSchema.safeParse(body);
+	if (!parsed.success) throw new Error("Tunnel registration returned an invalid response");
+	return parsed.data.key;
+}
+//#endregion
+export { provisionTunnelRegistrationKey };

package/dist/src/voice/audio/normalize.d.ts

@@ -4,6 +4,13 @@ export declare class AudioNormalizationError extends Error {
     readonly code = "unsupported_audio_codec";
     constructor(message: string, options?: ErrorOptions);
 }
+export interface AudioDecoderStatus {
+    available: boolean;
+    command: string;
+    error?: string;
+}
+/** Reports whether compressed browser/mobile recordings can be decoded on this host. */
+export declare function getAudioDecoderStatus(): AudioDecoderStatus;
 export declare function detectAudioFormat(buffer: Buffer): AudioFormat;
 export declare function decodeAudioToMonoFloat32(input: {
     buffer: Buffer;

package/dist/src/voice/audio/normalize.js

@@ -1,7 +1,7 @@
 import { UnsupportedWavEncodingError, decodeWavToMonoFloat32 } from "../local/wav.js";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
 //#region src/voice/audio/normalize.ts
 const TARGET_SAMPLE_RATE = 16e3;
@@ -15,6 +15,31 @@ var AudioNormalizationError = class extends Error {
 		this.name = "AudioNormalizationError";
 	}
 };
+function ffmpegCommand() {
+	return process.env.XOPC_FFMPEG_PATH?.trim() || "ffmpeg";
+}
+/** Reports whether compressed browser/mobile recordings can be decoded on this host. */
+function getAudioDecoderStatus() {
+	const command = ffmpegCommand();
+	const result = spawnSync(command, ["-version"], {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		],
+		timeout: 5e3
+	});
+	if (!result.error && result.status === 0) return {
+		available: true,
+		command
+	};
+	return {
+		available: false,
+		command,
+		error: `Audio decoder is unavailable (${command}): ${result.error instanceof Error ? result.error.message : result.stderr?.trim() || `decoder exited with status ${String(result.status)}`}. Install ffmpeg or set XOPC_FFMPEG_PATH.`
+	};
+}
 function detectAudioFormat(buffer) {
 	if (buffer.length >= 12 && buffer.toString("ascii", 0, 4) === "RIFF" && buffer.toString("ascii", 8, 12) === "WAVE") return "wav";
 	if (buffer.length >= 4 && buffer.subarray(0, 4).equals(Buffer.from([
@@ -32,7 +57,8 @@ function detectAudioFormat(buffer) {
 function runFfmpeg(args, options = {}) {
 	options.signal?.throwIfAborted();
 	return new Promise((resolve, reject) => {
-		const child = spawn("ffmpeg", [
+		const command = ffmpegCommand();
+		const child = spawn(command, [
 			"-hide_banner",
 			"-loglevel",
 			"error",
@@ -75,7 +101,7 @@ function runFfmpeg(args, options = {}) {
 			errorBytes += bounded.length;
 		});
 		child.once("error", (error) => {
-			finish(new AudioNormalizationError(error.code === "ENOENT" ? "Audio decoder is unavailable; install ffmpeg to transcribe this format" : `Audio decoder failed to start: ${error.message}`, { cause: error }));
+			finish(new AudioNormalizationError(error.code === "ENOENT" ? `Audio decoder is unavailable (${command}); install ffmpeg or set XOPC_FFMPEG_PATH to transcribe this format` : `Audio decoder failed to start: ${error.message}`, { cause: error }));
 		});
 		child.once("close", (code) => {
 			if (settled) return;
@@ -172,4 +198,4 @@ async function forEachNormalizedAudioSegment(input, consume) {
 	}
 }
 //#endregion
-export { AudioNormalizationError, decodeAudioToMonoFloat32, detectAudioFormat, forEachNormalizedAudioSegment };
+export { AudioNormalizationError, decodeAudioToMonoFloat32, detectAudioFormat, forEachNormalizedAudioSegment, getAudioDecoderStatus };

package/dist/src/voice/local/runtime-worker.js

@@ -7,6 +7,18 @@ import { createInterface } from "node:readline";
 //#region src/voice/local/runtime-worker.ts
 const pipelines = /* @__PURE__ */ new Map();
 const sherpaRecognizers = /* @__PURE__ */ new Map();
+async function assertLocalVoiceEngineAvailable(modelId) {
+	const model = getLocalVoiceModel(modelId);
+	if (model.engine === "sherpa-onnx") {
+		const imported = await import("sherpa-onnx-node").catch((cause) => {
+			throw new Error("The sherpa-onnx local voice engine is not installed. Install sherpa-onnx-node@1.13.4 alongside @xopcai/xopc.", { cause });
+		});
+		if (typeof (imported.default ?? imported).OfflineRecognizer !== "function") throw new Error("The sherpa-onnx local voice engine did not expose OfflineRecognizer");
+	} else await import("@huggingface/transformers").catch((cause) => {
+		throw new Error("The Transformers.js local voice engine is not installed. Install @huggingface/transformers@3.8.1 alongside @xopcai/xopc.", { cause });
+	});
+	return model.engine;
+}
 const networkAgent = new RetryAgent(new EnvHttpProxyAgent(), {
 	maxRetries: 4,
 	minTimeout: 500,
@@ -161,12 +173,20 @@ async function transcribeWithSherpa(modelId, audio, language) {
 }
 async function handle(request) {
 	const params = request.params ?? {};
-	if (request.method === "health") return {
-		ok: true,
-		protocolVersion: 2,
-		engine: "transformers.js+sherpa-onnx",
-		engines: ["transformers.js", "sherpa-onnx"]
-	};
+	if (request.method === "health") {
+		const modelId = typeof params.modelId === "string" && params.modelId ? params.modelId : void 0;
+		const selectedEngine = modelId ? await assertLocalVoiceEngineAvailable(modelId) : void 0;
+		return {
+			ok: true,
+			protocolVersion: 2,
+			engine: "transformers.js+sherpa-onnx",
+			engines: ["transformers.js", "sherpa-onnx"],
+			...modelId ? {
+				modelId,
+				selectedEngine
+			} : {}
+		};
+	}
 	if (request.method === "model.install") {
 		const modelId = String(params.modelId ?? "");
 		const modelDir = resolve(resolveLocalVoiceModelDir(modelId));

package/dist/src/workflows/service/workflow-run-service.js

@@ -1,6 +1,6 @@
 import { getDefaultAgentId, init_resolve_route } from "../../routing/resolve-route.js";
-import { init_providers, resolveModel } from "../../providers/index.js";
 import { extractProfileAgentId, resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
+import { init_providers, resolveModel } from "../../providers/index.js";
 import { TaskRepository } from "../../tasks/task-repository.js";
 import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
 import { TaskRunRepository } from "../../tasks/task-run-repository.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/xopc",
-  "version": "0.0.221",
+  "version": "0.0.223",
   "description": "Local-first personal AI assistant with reviewable user understanding, durable tasks, workflows, automations, and local or cloud models.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -108,27 +108,22 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@huggingface/transformers": "3.8.1",
     "@larksuiteoapi/node-sdk": "^1.66.0",
-    "playwright-core": "^1.60.0",
-    "sherpa-onnx-node": "1.13.4"
+    "playwright-core": "^1.60.0"
   },
   "peerDependenciesMeta": {
-    "@huggingface/transformers": {
-      "optional": true
-    },
     "@larksuiteoapi/node-sdk": {
       "optional": true
     },
     "playwright-core": {
       "optional": true
-    },
-    "sherpa-onnx-node": {
-      "optional": true
     }
   },
-  "devDependencies": {
+  "optionalDependencies": {
     "@huggingface/transformers": "3.8.1",
+    "sherpa-onnx-node": "1.13.4"
+  },
+  "devDependencies": {
     "@larksuiteoapi/node-sdk": "^1.66.0",
     "@resvg/resvg-js": "^2.6.2",
     "@tailwindcss/vite": "^4.3.0",
@@ -152,7 +147,6 @@
     "onnxruntime-common": "1.21.0",
     "node-pty": "1.1.0",
     "playwright-core": "^1.60.0",
-    "sherpa-onnx-node": "1.13.4",
     "svgo": "4.0.2",
     "tailwindcss": "^4.3.0",
     "tsdown": "0.21.10",
@@ -165,8 +159,8 @@
     "vue": "^3.5.35",
     "@xopcai/endpoint-tools-protocol": "0.0.0",
     "@xopcai/gateway-contract": "0.0.0",
-    "@xopcai/realtime-protocol": "0.0.0",
-    "@xopcai/realtime-client": "0.0.0"
+    "@xopcai/realtime-client": "0.0.0",
+    "@xopcai/realtime-protocol": "0.0.0"
   },
   "scripts": {
     "assets:brand": "node scripts/generate-brand-assets.mjs",