@xopcai/xopc 0.0.222 → 0.0.224

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/stt/transcribe-core.js

@@ -10,6 +10,7 @@ function classifyFailureReason(reason) {
 	const lower = reason.toLowerCase();
 	if (lower.includes("not configured") || lower.includes("api key") || lower.includes("missing")) return "not_configured";
 	if (lower.includes("timeout") || lower.includes("timed out") || lower.includes("aborted")) return "timeout";
+	if (lower.includes("empty transcription") || lower.includes("no speech") || lower.includes("no voice detected")) return "no_speech";
 	if (lower.includes("unsupported") || lower.includes("format") || lower.includes("audio decoder")) return "unsupported_format";
 	return "provider_error";
 }
@@ -51,7 +52,23 @@ async function transcribe(audioBuffer, config, options) {
 	const attachmentDecision = result.decision.attachments[0];
 	const attempts = (attachmentDecision?.attempts ?? []).map(toAttempt);
 	const attemptedProviders = attempts.map((a) => a.provider);
+	const primaryProvider = providersWithLanguage[0].id;
 	if (!attachmentDecision?.chosen) {
+		const noSpeechAttempt = attempts.findLast((attempt) => attempt.reasonCode === "no_speech");
+		if (noSpeechAttempt) {
+			log.debug({
+				attempts,
+				attemptedProviders
+			}, "STT completed without recognized speech");
+			const fallbackFrom = noSpeechAttempt.provider !== primaryProvider ? primaryProvider : void 0;
+			return {
+				text: "",
+				provider: noSpeechAttempt.provider,
+				attempts,
+				...fallbackFrom ? { fallbackFrom } : {},
+				attemptedProviders
+			};
+		}
 		log.error({
 			attempts,
 			attemptedProviders
@@ -62,7 +79,6 @@ async function transcribe(audioBuffer, config, options) {
 	const chosen = attachmentDecision.chosen;
 	const output = result.outputs[0];
 	if (!output) throw new Error("STT runner returned chosen attempt but no output text");
-	const primaryProvider = providersWithLanguage[0].id;
 	const fallbackFrom = chosen.provider && chosen.provider !== primaryProvider ? primaryProvider : void 0;
 	return {
 		text: output.text,

package/dist/src/voice/stt/types.d.ts

@@ -47,7 +47,7 @@ export interface STTConfig {
     timeoutMs?: number;
 }
 export type STTProviderAttemptTask = 'success' | 'skipped' | 'failed';
-export type STTProviderFailureReason = 'success' | 'not_configured' | 'timeout' | 'provider_error' | 'unsupported_format' | 'unknown';
+export type STTProviderFailureReason = 'success' | 'not_configured' | 'timeout' | 'no_speech' | 'provider_error' | 'unsupported_format' | 'unknown';
 export interface STTProviderAttempt {
     provider: string;
     task: STTProviderAttemptTask;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/xopc",
-  "version": "0.0.222",
+  "version": "0.0.224",
   "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",
@@ -157,9 +157,9 @@
     "vitepress": "^1.6.4",
     "vitest": "4.1.5",
     "vue": "^3.5.35",
+    "@xopcai/gateway-contract": "0.0.0",
     "@xopcai/endpoint-tools-protocol": "0.0.0",
     "@xopcai/realtime-protocol": "0.0.0",
-    "@xopcai/gateway-contract": "0.0.0",
     "@xopcai/realtime-client": "0.0.0"
   },
   "scripts": {