pi-meta-oauth 0.4.2 → 0.4.4

package/extensions/meta.ts

@@ -1,4 +1,7 @@
 import type {
+	Api,
+	Model,
+	ModelsStoreEntry,
 	OAuthCredentials,
 	OAuthLoginCallbacks,
 	RefreshModelsContext,
@@ -14,6 +17,7 @@ export const META_MODEL_CATALOG_URL = "https://api.meta.ai/v1/models";
 export const META_AUTH_BASE_URL = "https://auth.meta.com";
 export const META_CLIENT_ID = "1031625952748946";
 export const META_FILES_URL = `${META_API_BASE_URL}/files`;
+const META_ENV_VAR = "META_API_KEY";
 
 const DEVICE_AUTHORIZATION_URL = `${META_AUTH_BASE_URL}/oidc/device/authorization/`;
 const DEVICE_TOKEN_URL = `${META_AUTH_BASE_URL}/oidc/device/token/`;
@@ -199,9 +203,19 @@ async function postForm<T>(
 	};
 }
 
+function isAbortSignal(value: unknown): value is AbortSignal {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"aborted" in value &&
+		typeof (value as AbortSignal).aborted === "boolean"
+	);
+}
+
 export async function mintMetaApiKey(
 	identityToken: string,
 	fetchImpl: Fetch = fetch,
+	signal?: AbortSignal,
 ): Promise<string> {
 	const response = await fetchImpl(API_KEY_MINT_URL, {
 		method: "POST",
@@ -212,6 +226,7 @@ export async function mintMetaApiKey(
 			"x-api-version": "1.0.0",
 		},
 		body: "{}",
+		signal,
 	});
 	const body = (await responseBody(response)) as MintResponse &
 		Record<string, unknown>;
@@ -248,9 +263,7 @@ export async function loginMeta(
 	}
 	const device = authorization.body;
 	if (!device.device_code || !device.user_code || !device.verification_uri) {
-		throw new Error(
-			"Meta device authorization returned an incomplete response",
-		);
+		throw new Error("Meta device authorization returned an incomplete response");
 	}
 
 	let intervalSeconds =
@@ -264,8 +277,7 @@ export async function loginMeta(
 	const deadline = Date.now() + expiresInSeconds * 1000;
 	callbacks.onDeviceCode({
 		userCode: device.user_code,
-		verificationUri:
-			device.verification_uri_complete || device.verification_uri,
+		verificationUri: device.verification_uri_complete || device.verification_uri,
 		intervalSeconds,
 		expiresInSeconds,
 	});
@@ -316,15 +328,23 @@ export async function loginMeta(
 
 export async function refreshMetaToken(
 	credentials: OAuthCredentials,
-	fetchImpl: Fetch = fetch,
+	fetchOrSignal: Fetch | AbortSignal = fetch,
 ): Promise<OAuthCredentials> {
 	if (!credentials.refresh)
 		throw new Error(
 			"Meta login is missing its identity token; run /login meta again",
 		);
+	// Pi 0.83 calls refreshToken(credentials). Pi 0.84 passes AbortSignal as
+	// the second argument. Tests inject a fetch mock in that slot.
+	const fetchImpl =
+		typeof fetchOrSignal === "function" ? fetchOrSignal : fetch;
+	const signal = isAbortSignal(fetchOrSignal) ? fetchOrSignal : undefined;
+	if (signal?.aborted) {
+		throw new Error("Meta token refresh was cancelled");
+	}
 	return {
 		...credentials,
-		access: await mintMetaApiKey(credentials.refresh, fetchImpl),
+		access: await mintMetaApiKey(credentials.refresh, fetchImpl, signal),
 		expires: Date.now() + API_KEY_REFRESH_INTERVAL_MS,
 	};
 }
@@ -339,7 +359,7 @@ function numericCost(value: unknown, fallback: number): number {
 	const number =
 		typeof value === "number"
 			? value
-			: typeof value === "string"
+			: typeof value === "string" && value.trim()
 				? Number(value)
 				: Number.NaN;
 	return Number.isFinite(number) && number >= 0 ? number : fallback;
@@ -379,19 +399,17 @@ export function toProviderModels(
 		const metadata = entry.metadata?.["muse-code"];
 		if (metadata?.is_hidden) return [];
 		const fallback = FALLBACK_MODELS.find((model) => model.id === entry.id);
-		const catalogName =
-			metadata?.name === entry.id ? undefined : metadata?.name;
+		const catalogName = metadata?.name === entry.id ? undefined : metadata?.name;
 		const variants = metadata?.variants ?? {};
-		const thinkingLevelMap: NonNullable<MetaProviderModel["thinkingLevelMap"]> =
-			{
-				off: null,
-				minimal: variants.minimal?.reasoningEffort ?? "minimal",
-				low: variants.low?.reasoningEffort ?? "low",
-				medium: variants.medium?.reasoningEffort ?? "medium",
-				high: variants.high?.reasoningEffort ?? "high",
-				xhigh: variants.xhigh?.reasoningEffort ?? "xhigh",
-				max: null,
-			};
+		const thinkingLevelMap: NonNullable<MetaProviderModel["thinkingLevelMap"]> = {
+			off: null,
+			minimal: variants.minimal?.reasoningEffort ?? "minimal",
+			low: variants.low?.reasoningEffort ?? "low",
+			medium: variants.medium?.reasoningEffort ?? "medium",
+			high: variants.high?.reasoningEffort ?? "high",
+			xhigh: variants.xhigh?.reasoningEffort ?? "xhigh",
+			max: null,
+		};
 		return [
 			{
 				id: entry.id,
@@ -401,10 +419,7 @@ export function toProviderModels(
 				input: modalitiesToInput(metadata?.modalities?.input, fallback?.input),
 				cost: {
 					input: numericCost(metadata?.cost?.input, fallback?.cost.input ?? 0),
-					output: numericCost(
-						metadata?.cost?.output,
-						fallback?.cost.output ?? 0,
-					),
+					output: numericCost(metadata?.cost?.output, fallback?.cost.output ?? 0),
 					cacheRead: numericCost(
 						metadata?.cost?.cached,
 						fallback?.cost.cacheRead ?? 0,
@@ -425,36 +440,146 @@ export function toProviderModels(
 	});
 }
 
+interface CatalogStore {
+	read(): Promise<ModelsStoreEntry | undefined>;
+	write(entry: ModelsStoreEntry): Promise<void>;
+}
+
+interface CompatibleRefreshContext {
+	credential?: RefreshModelsContext["credential"];
+	allowNetwork: boolean;
+	signal?: AbortSignal;
+	// Pi 0.83 catalog persistence API.
+	store?: CatalogStore;
+	// Pi 0.84 generation-checked catalog persistence API.
+	stored?: Readonly<ModelsStoreEntry>;
+	publish?(publication: { persist?: ModelsStoreEntry | null }): Promise<boolean>;
+}
+
+function providerModelsFromStore(
+	entry: Readonly<ModelsStoreEntry> | undefined,
+): MetaProviderModel[] {
+	return (entry?.models ?? []).flatMap((model: Model<Api>) => {
+		if (model.provider !== META_PROVIDER_ID || model.api !== "openai-responses")
+			return [];
+		return [
+			{
+				id: model.id,
+				name: model.name,
+				api: model.api,
+				baseUrl: model.baseUrl,
+				reasoning: model.reasoning,
+				thinkingLevelMap: model.thinkingLevelMap,
+				input: model.input as MetaProviderModel["input"],
+				cost: model.cost,
+				contextWindow: model.contextWindow,
+				maxTokens: model.maxTokens,
+				headers: model.headers,
+				compat: model.compat as MetaProviderModel["compat"],
+			},
+		];
+	});
+}
+
+function modelsForStore(
+	models: MetaProviderModel[],
+): Model<"openai-responses">[] {
+	return models.map((model) => ({
+		...model,
+		api: "openai-responses",
+		provider: META_PROVIDER_ID,
+		baseUrl: model.baseUrl ?? META_API_BASE_URL,
+		input: model.input as Model<"openai-responses">["input"],
+		compat: model.compat as Model<"openai-responses">["compat"],
+	}));
+}
+
+async function cachedMetaModels(
+	context: CompatibleRefreshContext,
+): Promise<MetaProviderModel[]> {
+	try {
+		const stored = context.stored ?? (await context.store?.read());
+		return providerModelsFromStore(stored);
+	} catch {
+		// Catalog persistence is best-effort; bundled fallbacks remain available.
+		return [];
+	}
+}
+
+async function persistMetaModels(
+	context: CompatibleRefreshContext,
+	entry: ModelsStoreEntry,
+): Promise<void> {
+	if (context.publish) {
+		await context.publish({ persist: entry });
+		return;
+	}
+	await context.store?.write(entry);
+}
+
 export async function refreshMetaModels(
 	context: RefreshModelsContext,
 	fetchImpl: Fetch = fetch,
 ): Promise<MetaProviderModel[]> {
-	if (!context.allowNetwork || context.signal?.aborted)
-		return [...FALLBACK_MODELS];
+	const compatibleContext = context as unknown as CompatibleRefreshContext;
+	if (!context.allowNetwork || context.signal?.aborted) {
+		const cached = await cachedMetaModels(compatibleContext);
+		return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+	}
 	const apiKey =
 		context.credential?.type === "oauth"
 			? context.credential.access
 			: context.credential?.type === "api_key"
 				? context.credential.key
 				: undefined;
-	if (!apiKey) return [...FALLBACK_MODELS];
+	if (!apiKey) {
+		const cached = await cachedMetaModels(compatibleContext);
+		return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+	}
 
-	const response = await fetchImpl(META_MODEL_CATALOG_URL, {
-		headers: {
-			Accept: "application/json",
-			Authorization: `Bearer ${apiKey}`,
-			"x-api-version": "1.0.0",
-		},
-		signal: context.signal,
-	});
-	const body = (await responseBody(response)) as CatalogResponse &
-		Record<string, unknown>;
-	if (!response.ok) {
-		throw new Error(
-			`Meta model catalog failed (HTTP ${response.status})${errorDetail(body) ? `: ${errorDetail(body)}` : ""}`,
-		);
+	try {
+		const response = await fetchImpl(META_MODEL_CATALOG_URL, {
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${apiKey}`,
+				"x-api-version": "1.0.0",
+			},
+			signal: context.signal,
+		});
+		const body = (await responseBody(response)) as CatalogResponse &
+			Record<string, unknown>;
+		if (!response.ok) {
+			throw new Error(
+				`Meta model catalog failed (HTTP ${response.status})${errorDetail(body) ? `: ${errorDetail(body)}` : ""}`,
+			);
+		}
+		const models = toProviderModels(body);
+		if (models.length === 0) {
+			const cached = await cachedMetaModels(compatibleContext);
+			return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+		}
+		if (!context.signal?.aborted) {
+			try {
+				await persistMetaModels(compatibleContext, {
+					models: modelsForStore(models),
+					checkedAt: Date.now(),
+				});
+			} catch {
+				// Keep the fresh catalog usable even if persistence fails.
+			}
+		}
+		return models;
+	} catch (error) {
+		if (context.signal?.aborted) throw error;
+		const cached = await cachedMetaModels(compatibleContext);
+		return cached.length > 0 ? cached : [...FALLBACK_MODELS];
 	}
-	return toProviderModels(body);
+}
+
+export function metaFallbackCost(
+	modelId: string,
+): MetaProviderModel["cost"] | undefined {
+	return FALLBACK_MODELS.find((model) => model.id === modelId)?.cost;
 }
 
 export function createMetaProviderConfig(): ProviderConfig {
@@ -462,6 +587,7 @@ export function createMetaProviderConfig(): ProviderConfig {
 		name: "Meta Model API",
 		baseUrl: META_API_BASE_URL,
 		api: "openai-responses",
+		apiKey: "$META_API_KEY",
 		models: [...FALLBACK_MODELS],
 		refreshModels: refreshMetaModels,
 		oauth: {
@@ -474,5 +600,18 @@ export function createMetaProviderConfig(): ProviderConfig {
 }
 
 export default function metaOAuthProvider(pi: ExtensionAPI): void {
+	// Allow MODEL_API_KEY as fallback for API-key users — shim to META_API_KEY so $META_API_KEY interpolation works.
+	if (
+		process.env[META_ENV_VAR] === undefined &&
+		process.env["MODEL_API_KEY"] !== undefined
+	) {
+		process.env[META_ENV_VAR] = process.env["MODEL_API_KEY"];
+	}
+	if (
+		process.env["MODEL_API_KEY"] === undefined &&
+		process.env[META_ENV_VAR] !== undefined
+	) {
+		process.env["MODEL_API_KEY"] = process.env[META_ENV_VAR];
+	}
 	pi.registerProvider(META_PROVIDER_ID, createMetaProviderConfig());
 }

package/extensions/voice/asr.ts

@@ -0,0 +1,107 @@
+const DEFAULT_ASR_ENDPOINT =
+	"wss://shortwave.facebook.com/voyager/v1/asr/duplex";
+export const DEFAULT_ASR_MODEL = "prod_tbh";
+
+export function pcmAudioLevel(chunk: Buffer): number {
+	if (chunk.length < 2) return 0;
+	let sumSquares = 0;
+	let samples = 0;
+	for (let offset = 0; offset + 1 < chunk.length; offset += 2) {
+		const normalized = chunk.readInt16LE(offset) / 32_768;
+		sumSquares += normalized * normalized;
+		samples += 1;
+	}
+	if (samples === 0) return 0;
+	const rms = Math.sqrt(sumSquares / samples);
+	return Math.min(1, Math.log10(1 + rms * 90));
+}
+
+function hypothesisWords(value: string): string[] {
+	return value
+		.trim()
+		.split(/\s+/)
+		.map((word) => word.toLocaleLowerCase().replace(/[^\p{L}\p{N}'’]/gu, ""))
+		.filter(Boolean);
+}
+
+export function chooseTranscript(previous: string, incoming: string): string {
+	const next = incoming.trim();
+	if (!next) return previous;
+	if (!previous.trim()) return next;
+
+	const previousWords = hypothesisWords(previous);
+	const nextWords = hypothesisWords(next);
+	const sharedLength = Math.min(previousWords.length, nextWords.length);
+	let commonPrefix = 0;
+	while (
+		commonPrefix < sharedLength &&
+		previousWords[commonPrefix] === nextWords[commonPrefix]
+	) {
+		commonPrefix += 1;
+	}
+
+	if (commonPrefix === sharedLength || commonPrefix >= 2) {
+		const isRegression =
+			nextWords.length < previousWords.length &&
+			nextWords.every((word, index) => previousWords[index] === word);
+		return isRegression ? previous : next;
+	}
+	return next.length >= previous.length ? next : previous;
+}
+
+export function formatAuthorization(apiKey: string): string {
+	return apiKey.startsWith("OAuth ") ? apiKey : `OAuth ${apiKey}`;
+}
+
+export function asrEndpoint(sessionId: string): string {
+	const configured =
+		process.env.PI_META_VOICE_ASR_ENDPOINT ??
+		process.env.MUSE_VOICE_ASR_ENDPOINT ??
+		DEFAULT_ASR_ENDPOINT;
+	let endpoint: URL;
+	try {
+		endpoint = new URL(configured);
+	} catch {
+		throw new Error("Voice ASR endpoint is not a valid URL");
+	}
+	const localInsecureEndpoint =
+		endpoint.protocol === "ws:" &&
+		(endpoint.hostname === "localhost" || endpoint.hostname === "127.0.0.1");
+	if (endpoint.protocol !== "wss:" && !localInsecureEndpoint) {
+		throw new Error(
+			"Voice ASR endpoint must use wss:// (or ws://localhost for testing)",
+		);
+	}
+	endpoint.searchParams.set("sessionId", sessionId);
+	return endpoint.toString();
+}
+
+export async function socketMessageText(
+	data: unknown,
+): Promise<string | undefined> {
+	if (typeof data === "string") return data;
+	if (data instanceof Blob) return data.text();
+	if (data instanceof ArrayBuffer) return Buffer.from(data).toString("utf8");
+	if (ArrayBuffer.isView(data)) {
+		return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString(
+			"utf8",
+		);
+	}
+	return undefined;
+}
+
+export function parseJsonObject(text: string): Record<string, unknown> | undefined {
+	try {
+		const value = JSON.parse(text) as unknown;
+		if (value && typeof value === "object" && !Array.isArray(value)) {
+			return value as Record<string, unknown>;
+		}
+	} catch {
+		// Ignore non-JSON ASR messages.
+	}
+	return undefined;
+}
+
+export function isNormalSocketClose(code: number): boolean {
+	return code === 1000 || code === 1005;
+}

package/extensions/voice/helpers.ts

@@ -0,0 +1,243 @@
+import { spawn } from "node:child_process";
+import {
+	existsSync,
+	mkdirSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+} from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const AGENT_DIR = join(homedir(), ".pi/agent");
+const HELPER_DIR = dirname(fileURLToPath(import.meta.url));
+const HELPER_SOURCE = join(HELPER_DIR, "macos-audio.swift");
+const HELPER_PLIST = join(HELPER_DIR, "Info.plist");
+const HELPER_ENTITLEMENTS = join(HELPER_DIR, "Entitlements.plist");
+const HELPER_BINARY = join(AGENT_DIR, "bin/pi-meta-oauth-voice-v1");
+const WINDOWS_HELPER_SOURCE = join(HELPER_DIR, "windows-audio.cs");
+const WINDOWS_HELPER_PS1 = join(HELPER_DIR, "windows-audio.ps1");
+const WINDOWS_HELPER_BINARY = join(AGENT_DIR, "bin/pi-meta-oauth-voice-v1.exe");
+
+export function isMacOS(): boolean {
+	return platform() === "darwin";
+}
+
+export function isWindows(): boolean {
+	return platform() === "win32";
+}
+
+export function isSupportedPlatform(): boolean {
+	return isMacOS() || isWindows();
+}
+
+export function supportedPlatformLabel(): string {
+	if (isMacOS()) return "macOS";
+	if (isWindows()) return "Windows";
+	return `${platform()}`;
+}
+
+async function runProcess(command: string, args: string[]): Promise<void> {
+	await new Promise<void>((resolve, reject) => {
+		const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (chunk: Buffer) => {
+			stdout = `${stdout}${chunk.toString("utf8")}`.slice(-8_000);
+		});
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderr = `${stderr}${chunk.toString("utf8")}`.slice(-8_000);
+		});
+		child.once("error", reject);
+		child.once("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(
+				new Error(
+					(
+						stderr ||
+						stdout ||
+						`${command} exited with code ${code ?? "unknown"}`
+					).trim(),
+				),
+			);
+		});
+	});
+}
+
+function helperNeedsBuild(): boolean {
+	if (!existsSync(HELPER_BINARY)) return true;
+	const binaryTime = statSync(HELPER_BINARY).mtimeMs;
+	return [HELPER_SOURCE, HELPER_PLIST, HELPER_ENTITLEMENTS].some(
+		(path) => !existsSync(path) || statSync(path).mtimeMs > binaryTime,
+	);
+}
+
+function windowsHelperNeedsBuild(): boolean {
+	if (!existsSync(WINDOWS_HELPER_BINARY)) return true;
+	if (!existsSync(WINDOWS_HELPER_SOURCE)) return false;
+	return statSync(WINDOWS_HELPER_SOURCE).mtimeMs > statSync(WINDOWS_HELPER_BINARY).mtimeMs;
+}
+
+function removeIfExists(path: string): void {
+	try {
+		unlinkSync(path);
+	} catch {
+		// Staging or previous binary may already be gone.
+	}
+}
+
+async function ensureMacOSHelper(): Promise<string> {
+	if (!isMacOS()) {
+		throw new Error(
+			"Muse-style voice input is currently available only on macOS and Windows",
+		);
+	}
+	if (
+		!existsSync(HELPER_SOURCE) ||
+		!existsSync(HELPER_PLIST) ||
+		!existsSync(HELPER_ENTITLEMENTS)
+	) {
+		throw new Error("The macOS microphone helper sources are incomplete");
+	}
+	if (!helperNeedsBuild()) return HELPER_BINARY;
+
+	mkdirSync(join(AGENT_DIR, "bin"), { recursive: true });
+	const staging = `${HELPER_BINARY}.building`;
+	removeIfExists(staging);
+	try {
+		await runProcess("/usr/bin/xcrun", [
+			"swiftc",
+			HELPER_SOURCE,
+			"-o",
+			staging,
+			"-framework",
+			"AVFoundation",
+			"-Xlinker",
+			"-sectcreate",
+			"-Xlinker",
+			"__TEXT",
+			"-Xlinker",
+			"__info_plist",
+			"-Xlinker",
+			HELPER_PLIST,
+		]);
+		await runProcess("/usr/bin/codesign", [
+			"--force",
+			"--sign",
+			"-",
+			"--entitlements",
+			HELPER_ENTITLEMENTS,
+			staging,
+		]);
+		renameSync(staging, HELPER_BINARY);
+	} catch (error) {
+		removeIfExists(staging);
+		throw error;
+	}
+	return HELPER_BINARY;
+}
+
+async function tryCompileWindowsHelper(): Promise<boolean> {
+	if (!existsSync(WINDOWS_HELPER_SOURCE)) return false;
+	mkdirSync(join(AGENT_DIR, "bin"), { recursive: true });
+
+	const candidates: string[] = [
+		"csc",
+		"csc.exe",
+		"C:\\Windows\\Microsoft.NET\\Framework\\v4.0.30319\\csc.exe",
+		"C:\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319\\csc.exe",
+	];
+	const staging = `${WINDOWS_HELPER_BINARY}.building`;
+	removeIfExists(staging);
+	for (const c of candidates) {
+		try {
+			await runProcess(c, [
+				"/nologo",
+				"/target:exe",
+				`/out:${staging}`,
+				WINDOWS_HELPER_SOURCE,
+			]);
+			if (existsSync(staging)) {
+				renameSync(staging, WINDOWS_HELPER_BINARY);
+				return true;
+			}
+		} catch {
+			removeIfExists(staging);
+		}
+	}
+	return false;
+}
+
+function findPowerShellCommand(): string {
+	if (existsSync("C:\\Program Files\\PowerShell\\7\\pwsh.exe"))
+		return "C:\\Program Files\\PowerShell\\7\\pwsh.exe";
+	if (existsSync("C:\\Program Files\\PowerShell\\7\\pwsh")) return "pwsh";
+	if (
+		existsSync("C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe")
+	)
+		return "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe";
+	return "powershell.exe";
+}
+
+async function ensureWindowsHelper(): Promise<{
+	command: string;
+	args: string[];
+}> {
+	if (!isWindows()) {
+		throw new Error(
+			"Muse-style voice input is currently available only on macOS and Windows",
+		);
+	}
+	if (!existsSync(WINDOWS_HELPER_SOURCE) && !existsSync(WINDOWS_HELPER_PS1)) {
+		throw new Error("The Windows microphone helper sources are incomplete");
+	}
+
+	if (existsSync(WINDOWS_HELPER_BINARY) && !windowsHelperNeedsBuild()) {
+		return { command: WINDOWS_HELPER_BINARY, args: [] };
+	}
+
+	if (existsSync(WINDOWS_HELPER_SOURCE)) {
+		const compiled = await tryCompileWindowsHelper();
+		if (compiled && existsSync(WINDOWS_HELPER_BINARY)) {
+			return { command: WINDOWS_HELPER_BINARY, args: [] };
+		}
+	}
+
+	if (existsSync(WINDOWS_HELPER_PS1)) {
+		const ps = findPowerShellCommand();
+		return {
+			command: ps,
+			args: [
+				"-NoProfile",
+				"-ExecutionPolicy",
+				"Bypass",
+				"-File",
+				WINDOWS_HELPER_PS1,
+			],
+		};
+	}
+
+	throw new Error(
+		"Windows voice helper could not be prepared — no compiled binary and no PowerShell fallback found",
+	);
+}
+
+export async function ensureHelper(): Promise<{
+	command: string;
+	args: string[];
+}> {
+	if (isMacOS()) {
+		const bin = await ensureMacOSHelper();
+		return { command: bin, args: [] };
+	}
+	if (isWindows()) {
+		return ensureWindowsHelper();
+	}
+	throw new Error(
+		`Muse-style voice input is currently available only on macOS and Windows (current: ${supportedPlatformLabel()})`,
+	);
+}