@nac3/forge-cli 0.2.0-alpha.5 → 0.2.0-alpha.59z.118

package/dist/telemetry/usage.js

@@ -0,0 +1,208 @@
+/**
+ * Yujin Forge -- usage + cost telemetry.
+ *
+ * Append-only event log at ~/.yujin-forge/usage.jsonl. Every
+ * Claude API call (or other priced operation) records one JSONL
+ * line with { ts, kind, model?, tokens_in?, tokens_out?, units?,
+ * label?, project_root? }.
+ *
+ * The reader (`yf operate costs`) aggregates by day + by kind +
+ * by model and applies a pricing table to produce a cost report.
+ *
+ * Append is best-effort: telemetry failures NEVER throw to the
+ * caller -- a broken usage file should not break user work.
+ *
+ * Pricing is hard-coded for the 2026 model lineup. Users can
+ * override via ~/.yujin-forge/pricing.json:
+ *   {
+ *     "models": {
+ *        "claude-opus-4-7":  { "in_per_mtok": 15, "out_per_mtok": 75 },
+ *        "claude-sonnet-4-6": { "in_per_mtok":  3, "out_per_mtok": 15 }
+ *     },
+ *     "voice": {
+ *        "tts_per_million_chars": 16,
+ *        "stt_per_minute":        0.006
+ *     }
+ *   }
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { configDir } from '../license/index.js';
+/* Defaults reflect early-2026 Anthropic + Google Cloud pricing.
+ * Users can override via ~/.yujin-forge/pricing.json. */
+export const DEFAULT_PRICING = {
+    models: {
+        'claude-opus-4-7': { in_per_mtok: 15, out_per_mtok: 75 },
+        'claude-opus-4': { in_per_mtok: 15, out_per_mtok: 75 },
+        'claude-sonnet-4-6': { in_per_mtok: 3, out_per_mtok: 15 },
+        'claude-sonnet-4': { in_per_mtok: 3, out_per_mtok: 15 },
+        'claude-haiku-4-5': { in_per_mtok: 1, out_per_mtok: 5 },
+        /* Older lineup kept for back-compat. */
+        'claude-3-5-sonnet': { in_per_mtok: 3, out_per_mtok: 15 },
+        'claude-3-5-haiku': { in_per_mtok: 0.8, out_per_mtok: 4 },
+    },
+    voice: {
+        tts_per_million_chars: 16, /* Google Cloud TTS Neural2 */
+        stt_per_minute: 0.006, /* Google Cloud STT enhanced */
+    },
+};
+function usageFile() {
+    return path.join(configDir(), 'usage.jsonl');
+}
+function pricingFile() {
+    return path.join(configDir(), 'pricing.json');
+}
+async function ensureDir() {
+    try {
+        await fs.mkdir(configDir(), { recursive: true });
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Append a usage event. Never throws -- failures swallowed.
+ */
+export async function recordUsage(ev) {
+    try {
+        await ensureDir();
+        const line = { ts: ev.ts ?? new Date().toISOString(), ...ev };
+        await fs.appendFile(usageFile(), JSON.stringify(line) + '\n', 'utf-8');
+    }
+    catch {
+        /* swallow -- telemetry must never break user flow */
+    }
+}
+/**
+ * Load pricing table (defaults overlaid with user overrides).
+ */
+export async function loadPricing() {
+    try {
+        const raw = await fs.readFile(pricingFile(), 'utf-8');
+        const override = JSON.parse(raw);
+        return {
+            models: { ...(DEFAULT_PRICING.models ?? {}), ...(override.models ?? {}) },
+            voice: { ...(DEFAULT_PRICING.voice ?? {}), ...(override.voice ?? {}) },
+        };
+    }
+    catch {
+        return DEFAULT_PRICING;
+    }
+}
+/**
+ * Read all usage events. Tolerates malformed lines.
+ */
+export async function readUsage() {
+    try {
+        const raw = await fs.readFile(usageFile(), 'utf-8');
+        return raw.split('\n')
+            .filter((l) => l.trim().length > 0)
+            .map((l) => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((x) => x !== null);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Compute cost breakdown over a time window. `sinceDays` defaults
+ * to 30. Pass 0 to mean "all-time".
+ */
+export async function computeCosts(sinceDays = 30) {
+    const events = await readUsage();
+    const pricing = await loadPricing();
+    const now = Date.now();
+    const cutoffMs = sinceDays > 0 ? now - sinceDays * 24 * 60 * 60 * 1000 : 0;
+    const inWindow = events.filter((e) => Date.parse(e.ts) >= cutoffMs);
+    const breakdown = {
+        total_usd: 0,
+        by_kind: {},
+        by_model: {},
+        by_day: {},
+        events_total: events.length,
+        events_window: inWindow.length,
+        window_label: sinceDays === 0 ? 'all-time' : 'last ' + sinceDays + ' days',
+    };
+    for (const ev of inWindow) {
+        let usd = 0;
+        if (ev.kind.startsWith('claude.')) {
+            const m = ev.model ?? 'unknown';
+            const p = pricing.models?.[m];
+            if (p) {
+                usd = ((ev.tokens_in ?? 0) / 1_000_000) * p.in_per_mtok
+                    + ((ev.tokens_out ?? 0) / 1_000_000) * p.out_per_mtok;
+            }
+            if (!breakdown.by_model[m]) {
+                breakdown.by_model[m] = { count: 0, tokens_in: 0, tokens_out: 0, usd: 0 };
+            }
+            const slot = breakdown.by_model[m];
+            slot.count++;
+            slot.tokens_in += ev.tokens_in ?? 0;
+            slot.tokens_out += ev.tokens_out ?? 0;
+            slot.usd += usd;
+        }
+        else if (ev.kind === 'voice.tts') {
+            usd = ((ev.units ?? 0) / 1_000_000) * (pricing.voice?.tts_per_million_chars ?? 0);
+        }
+        else if (ev.kind === 'voice.stt') {
+            usd = (ev.units ?? 0) * (pricing.voice?.stt_per_minute ?? 0);
+        }
+        breakdown.total_usd += usd;
+        if (!breakdown.by_kind[ev.kind])
+            breakdown.by_kind[ev.kind] = { count: 0, usd: 0 };
+        breakdown.by_kind[ev.kind].count++;
+        breakdown.by_kind[ev.kind].usd += usd;
+        const day = ev.ts.slice(0, 10);
+        if (!breakdown.by_day[day])
+            breakdown.by_day[day] = { count: 0, usd: 0 };
+        breakdown.by_day[day].count++;
+        breakdown.by_day[day].usd += usd;
+    }
+    return breakdown;
+}
+/**
+ * Pretty-format a CostBreakdown for terminal output. Returns
+ * lines; caller does the printing.
+ */
+export function formatCosts(b) {
+    const lines = [];
+    lines.push('Window:          ' + b.window_label);
+    lines.push('Events total:    ' + b.events_total);
+    lines.push('Events in window:' + b.events_window);
+    lines.push('Total USD:       $' + b.total_usd.toFixed(4));
+    lines.push('');
+    lines.push('By kind:');
+    const kinds = Object.entries(b.by_kind).sort((a, c) => c[1].usd - a[1].usd);
+    for (const [k, v] of kinds) {
+        lines.push('  ' + k.padEnd(18) + 'count=' + String(v.count).padStart(5) + '  usd=$' + v.usd.toFixed(4));
+    }
+    if (Object.keys(b.by_model).length > 0) {
+        lines.push('');
+        lines.push('By model:');
+        const models = Object.entries(b.by_model).sort((a, c) => c[1].usd - a[1].usd);
+        for (const [m, v] of models) {
+            lines.push('  ' + m.padEnd(24)
+                + 'count=' + String(v.count).padStart(5)
+                + '  in=' + String(v.tokens_in).padStart(8)
+                + '  out=' + String(v.tokens_out).padStart(7)
+                + '  usd=$' + v.usd.toFixed(4));
+        }
+    }
+    if (Object.keys(b.by_day).length > 0) {
+        lines.push('');
+        lines.push('By day:');
+        const days = Object.entries(b.by_day).sort((a, c) => (a[0] < c[0] ? 1 : -1)).slice(0, 14);
+        for (const [d, v] of days) {
+            lines.push('  ' + d + '  count=' + String(v.count).padStart(5) + '  usd=$' + v.usd.toFixed(4));
+        }
+    }
+    return lines;
+}
+//# sourceMappingURL=usage.js.map

package/dist/telemetry/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/telemetry/usage.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -4,5 +4,5 @@
  * into the npm metadata) so we don't end up with two versions
  * drifting.
  */
-export declare const VERSION = "0.2.0-alpha.5";
+export declare const VERSION = "0.2.0-alpha.59z.118";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,OAAO,kBAAkB,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,OAAO,wBAAwB,CAAC"}

package/dist/version.js

@@ -4,5 +4,5 @@
  * into the npm metadata) so we don't end up with two versions
  * drifting.
  */
-export const VERSION = '0.2.0-alpha.5';
+export const VERSION = '0.2.0-alpha.59z.118';
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,qBAAqB,CAAC"}

package/dist/voice/config.d.ts

@@ -1,11 +1,23 @@
 import { type WakeMatchResult } from './wake.js';
 export declare const VOICE_CONFIG_VERSION = 1;
+/** alpha.44 F5 -- STT provider preference. */
+export type SttProvider = 'browser' | 'google' | 'whisper';
+export declare const ALL_STT_PROVIDERS: readonly SttProvider[];
+/** alpha.44 F5 -- TTS provider preference. */
+export type TtsProvider = 'browser' | 'google' | 'elevenlabs' | 'yujin_cloud';
+export declare const ALL_TTS_PROVIDERS: readonly TtsProvider[];
 export interface VoiceConfig {
     version: 1;
     /** Extra aliases the user wants matched (e.g. "koe", "yoo-jin"). */
     wake_aliases_extra: string[];
     /** Levenshtein cap. 0 = exact-only. 2 = default. */
     wake_max_distance: number;
+    /** alpha.44 F5 -- which STT engine to use at runtime. Default
+     *  'browser' (Web Speech API) since it is fastest + free. */
+    stt_provider?: SttProvider;
+    /** alpha.44 F5 -- which TTS engine to use at runtime. Default
+     *  'browser' (SpeechSynthesisUtterance). */
+    tts_provider?: TtsProvider;
 }
 export declare function readVoiceConfig(): Promise<VoiceConfig>;
 export declare function writeVoiceConfig(cfg: VoiceConfig): Promise<void>;

package/dist/voice/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/voice/config.ts"],"names":[],"mappings":"AAYA,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAE9E,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,oEAAoE;IACpE,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,oDAAoD;IACpD,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAWD,wBAAsB,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CAe5D;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAItE;AAED,iEAAiE;AACjE,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAIrF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/voice/config.ts"],"names":[],"mappings":"AAYA,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAE9E,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAC3D,eAAO,MAAM,iBAAiB,EAAE,SAAS,WAAW,EAAqC,CAAC;AAE1F,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;AAC9E,eAAO,MAAM,iBAAiB,EAAE,SAAS,WAAW,EAAuD,CAAC;AAE5G,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,oEAAoE;IACpE,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,oDAAoD;IACpD,iBAAiB,EAAE,MAAM,CAAC;IAC1B;iEAC6D;IAC7D,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B;gDAC4C;IAC5C,YAAY,CAAC,EAAE,WAAW,CAAC;CAC5B;AA6BD,wBAAsB,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CAiB5D;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAItE;AAED,iEAAiE;AACjE,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAIrF"}

package/dist/voice/config.js

@@ -12,12 +12,33 @@ import path from 'node:path';
 import os from 'node:os';
 import { mergeAliases, matchWakeWord } from './wake.js';
 export const VOICE_CONFIG_VERSION = 1;
+export const ALL_STT_PROVIDERS = ['browser', 'google', 'whisper'];
+export const ALL_TTS_PROVIDERS = ['browser', 'google', 'elevenlabs', 'yujin_cloud'];
 function voiceConfigPath() {
     const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
-    return path.join(home, '.yujin-forge', 'voice.json');
+    const base = process.env.YF_CONFIG_DIR || path.join(home, '.yujin-forge');
+    return path.join(base, 'voice.json');
 }
 function defaultConfig() {
-    return { version: 1, wake_aliases_extra: [], wake_max_distance: 2 };
+    return {
+        version: 1,
+        wake_aliases_extra: [],
+        wake_max_distance: 2,
+        stt_provider: 'browser',
+        tts_provider: 'browser',
+    };
+}
+function normaliseStt(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const s = v.toLowerCase().trim();
+    return ALL_STT_PROVIDERS.includes(s) ? s : undefined;
+}
+function normaliseTts(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const s = v.toLowerCase().trim();
+    return ALL_TTS_PROVIDERS.includes(s) ? s : undefined;
 }
 export async function readVoiceConfig() {
     const p = voiceConfigPath();
@@ -28,6 +49,8 @@ export async function readVoiceConfig() {
             version: 1,
             wake_aliases_extra: Array.isArray(obj.wake_aliases_extra) ? obj.wake_aliases_extra : [],
             wake_max_distance: typeof obj.wake_max_distance === 'number' ? obj.wake_max_distance : 2,
+            stt_provider: normaliseStt(obj.stt_provider) ?? 'browser',
+            tts_provider: normaliseTts(obj.tts_provider) ?? 'browser',
         };
     }
     catch (err) {

package/dist/voice/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/voice/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAwB,MAAM,WAAW,CAAC;AAE9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAUtC,SAAS,eAAe;IACtB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;IACzE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,aAAa;IACpB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,kBAAkB,EAAE,EAAE,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,CAAC,GAAG,eAAe,EAAE,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QACpD,OAAO;YACL,OAAO,EAAE,CAAC;YACV,kBAAkB,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE;YACvF,iBAAiB,EAAE,OAAO,GAAG,CAAC,iBAAiB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;SACzF,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,aAAa,EAAE,CAAC;QAC9C,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAgB;IACrD,MAAM,CAAC,GAAG,eAAe,EAAE,CAAC;IAC5B,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AACrE,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,KAAa;IACzD,MAAM,GAAG,GAAG,MAAM,eAAe,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACrD,OAAO,aAAa,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,iBAAiB,EAAE,CAAC,CAAC;AAC/E,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/voice/config.ts"],"names":[],"mappings":"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"}

package/dist/voice/providers/google.d.ts

@@ -27,6 +27,15 @@ export interface GoogleProviderOptions {
     fetchImpl?: typeof fetch;
     vaultOpener?: () => Promise<Vault>;
 }
+/** Google STT enhanced models only certify a subset of Spanish
+ *  locale codes. Map any specifically-regional Latin-Spanish
+ *  locale (es-AR, es-CL, es-PE, es-CO, es-VE, etc) to es-US
+ *  (Latin American Spanish neutral). Pass through:
+ *    es-ES (Spain), es-US (Latin neutral), es-419 (Latin
+ *    generic) -- all supported directly by latest_long +
+ *    useEnhanced. Bare 'es' also routes to es-US.
+ *  Exported for tests. */
+export declare function normaliseSpanishLocale(locale: string): string;
 /** Map our SttAudioFormat to Google's encoding enum. */
 declare function sttFormatToGoogleEncoding(format: SttAudioFormat): string;
 /** Map our TtsAudioFormat to Google's audio encoding enum. */

package/dist/voice/providers/google.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"google.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/google.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACf,MAAM,aAAa,CAAC;AAQrB,QAAA,MAAM,UAAU,iBAAiB,CAAC;AAElC,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;CACpC;AAED,wDAAwD;AACxD,iBAAS,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAUjE;AAED,8DAA8D;AAC9D,iBAAS,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAQjE;AAqBD,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,EAAE,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;gBAEvC,IAAI,GAAE,qBAA0B;IAKtC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAS9B,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;CAwExD;AAMD,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,EAAE,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;gBAEvC,IAAI,GAAE,qBAA0B;IAKtC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAS9B,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAiEvD;qDACiD;IACjD,OAAO,CAAC,sBAAsB;IAQ9B,qDAAqD;IACrD,OAAO,CAAC,UAAU;CAMnB;AAGD,OAAO,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"google.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/google.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACf,MAAM,aAAa,CAAC;AAuErB,QAAA,MAAM,UAAU,iBAAiB,CAAC;AAElC,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;CACpC;AAED;;;;;;;0BAO0B;AAC1B,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAU7D;AAED,wDAAwD;AACxD,iBAAS,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAUjE;AAED,8DAA8D;AAC9D,iBAAS,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAQjE;AAoED,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,EAAE,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;gBAEvC,IAAI,GAAE,qBAA0B;IAKtC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAI9B,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;CAgGxD;AAMD,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,EAAE,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;gBAEvC,IAAI,GAAE,qBAA0B;IAKtC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAI9B,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAoGvD;qDACiD;IACjD,OAAO,CAAC,sBAAsB;IAQ9B,qDAAqD;IACrD,OAAO,CAAC,UAAU;CAMnB;AAGD,OAAO,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,UAAU,EAAE,CAAC"}

package/dist/voice/providers/google.js

@@ -27,8 +27,85 @@ const TTS_ENDPOINT = 'https://texttospeech.googleapis.com/v1/text:synthesize';
 const DEFAULT_STT_LANGUAGE = 'en-US';
 const DEFAULT_TTS_LANGUAGE = 'en-US';
 const DEFAULT_TTS_VOICE = 'en-US-Neural2-C';
+/** Per-locale voice persona for Google Cloud TTS Neural2 voices.
+ *  Selected to sound native to the locale + warm + neutral
+ *  gender where possible. Keys are lowercased; we lookup with
+ *  region first (es-ar) then language alone (es) as fallback. */
+const LOCALE_TO_VOICE = {
+    /* Spanish family. ES-AR uses the rioplatense (Spain Neural2-A
+       sounds neutral enough; Argentina-specific voices are limited).
+       Mexican Latin Spanish prefers Wavenet-A. */
+    'es': 'es-ES-Neural2-A',
+    'es-ar': 'es-US-Neural2-A',
+    'es-es': 'es-ES-Neural2-A',
+    'es-mx': 'es-US-Neural2-A',
+    'es-us': 'es-US-Neural2-A',
+    /* English. en-US-Neural2-C is warm + neutral. */
+    'en': 'en-US-Neural2-C',
+    'en-us': 'en-US-Neural2-C',
+    'en-gb': 'en-GB-Neural2-A',
+    /* Portuguese. */
+    'pt': 'pt-BR-Neural2-A',
+    'pt-br': 'pt-BR-Neural2-A',
+    'pt-pt': 'pt-PT-Wavenet-A',
+    /* French. */
+    'fr': 'fr-FR-Neural2-A',
+    'fr-fr': 'fr-FR-Neural2-A',
+    'fr-ca': 'fr-CA-Neural1-A',
+    /* Italian. */
+    'it': 'it-IT-Neural2-A',
+    'it-it': 'it-IT-Neural2-A',
+    /* German. */
+    'de': 'de-DE-Neural2-A',
+    'de-de': 'de-DE-Neural2-A',
+    /* Japanese. */
+    'ja': 'ja-JP-Neural2-B',
+    'ja-jp': 'ja-JP-Neural2-B',
+    /* Mandarin Chinese. */
+    'zh': 'cmn-CN-Wavenet-A',
+    'zh-cn': 'cmn-CN-Wavenet-A',
+    'zh-tw': 'cmn-TW-Wavenet-A',
+    /* Hindi. */
+    'hi': 'hi-IN-Neural2-A',
+    'hi-in': 'hi-IN-Neural2-A',
+    /* Arabic. */
+    'ar': 'ar-XA-Wavenet-A',
+    'ar-xa': 'ar-XA-Wavenet-A',
+};
+function voiceForLocale(key) {
+    if (LOCALE_TO_VOICE[key])
+        return LOCALE_TO_VOICE[key];
+    /* Strip region: es-ar -> es. */
+    const base = key.split('-')[0];
+    if (base && LOCALE_TO_VOICE[base])
+        return LOCALE_TO_VOICE[base];
+    return undefined;
+}
 const DEFAULT_TTS_FORMAT = 'mp3';
 const VAULT_SLOT = 'google_voice';
+/** Google STT enhanced models only certify a subset of Spanish
+ *  locale codes. Map any specifically-regional Latin-Spanish
+ *  locale (es-AR, es-CL, es-PE, es-CO, es-VE, etc) to es-US
+ *  (Latin American Spanish neutral). Pass through:
+ *    es-ES (Spain), es-US (Latin neutral), es-419 (Latin
+ *    generic) -- all supported directly by latest_long +
+ *    useEnhanced. Bare 'es' also routes to es-US.
+ *  Exported for tests. */
+export function normaliseSpanishLocale(locale) {
+    const norm = locale.toLowerCase();
+    if (!norm.startsWith('es'))
+        return locale;
+    if (norm === 'es' || norm === 'es-419')
+        return 'es-US';
+    /* Spain Spanish -- preserve canonical case. */
+    if (norm === 'es-es')
+        return 'es-ES';
+    /* US Latin neutral -- preserve canonical case. */
+    if (norm === 'es-us')
+        return 'es-US';
+    /* Every other es-XX -> es-US. */
+    return 'es-US';
+}
 /** Map our SttAudioFormat to Google's encoding enum. */
 function sttFormatToGoogleEncoding(format) {
     switch (format) {
@@ -51,13 +128,61 @@ function ttsFormatToGoogleEncoding(format) {
         default: return 'MP3';
     }
 }
-async function readKey(opener) {
-    const vault = await opener();
-    if (!vault.has(VAULT_SLOT)) {
-        throw new Error('google voice: vault slot "' + VAULT_SLOT + '" not set. '
-            + 'Run `yf vault set ' + VAULT_SLOT + '` to configure your Google Cloud API key.');
+/** Read the per-use-case key from the encrypted Vault (alpha.44 C1
+ *  canonical BYOK path; legacy provider_keys.json is auto-migrated
+ *  by core/provider_keys.ts on first access). STT prefers
+ *  google_stt_key; TTS prefers google_tts_key; if neither is set
+ *  but the other one is, we fall back to the cross-set key (STT
+ *  keys typically work for TTS and vice versa on Google Cloud
+ *  projects with both APIs enabled). */
+async function readProviderKey(useCase) {
+    try {
+        const { getKey } = await import('../../core/provider_keys.js');
+        const stt = (await getKey('google_stt_key')) || '';
+        const tts = (await getKey('google_tts_key')) || '';
+        const primary = useCase === 'stt' ? stt : tts;
+        const fallback = useCase === 'stt' ? tts : stt;
+        if (primary !== '')
+            return primary.trim();
+        if (fallback !== '')
+            return fallback.trim();
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readKey(opener, useCase) {
+    /* 1. BYOK provider_keys.json -- canonical alpha.4+ path. */
+    const fromBYOK = await readProviderKey(useCase);
+    if (fromBYOK)
+        return fromBYOK;
+    /* 2. Vault slot google_voice -- legacy / shared path. */
+    try {
+        const vault = await opener();
+        if (vault.has(VAULT_SLOT)) {
+            return vault.get(VAULT_SLOT);
+        }
+    }
+    catch { /* vault unavailable -- fall through to the throw */ }
+    const slotName = useCase === 'stt' ? 'google_stt_key' : 'google_tts_key';
+    throw new Error('google voice: no key found. Configure either:\n'
+        + '  - `yf keys setup` (writes ' + slotName + ' to provider_keys.json)   (recommended)\n'
+        + '  - `yf vault set ' + VAULT_SLOT + ' <your Google Cloud API key>`     (legacy)');
+}
+/** Cheap "are we configured?" check used by readyToRun. Mirrors
+ *  the resolution order in readKey + returns boolean instead of
+ *  throwing. */
+async function hasKey(opener, useCase) {
+    if ((await readProviderKey(useCase)) !== null)
+        return true;
+    try {
+        const vault = await opener();
+        return vault.has(VAULT_SLOT);
+    }
+    catch {
+        return false;
     }
-    return vault.get(VAULT_SLOT);
 }
 async function safeText(r) {
     try {
@@ -79,13 +204,7 @@ export class GoogleSttProvider {
         this.vaultOpener = opts.vaultOpener ?? (() => Vault.open({ configDir: configDir() }));
     }
     async readyToRun() {
-        try {
-            const vault = await this.vaultOpener();
-            return vault.has(VAULT_SLOT);
-        }
-        catch {
-            return false;
-        }
+        return hasKey(this.vaultOpener, 'stt');
     }
     async transcribe(req) {
         if (!req.audio || req.audio.length === 0) {
@@ -93,25 +212,46 @@ export class GoogleSttProvider {
         }
         let apiKey;
         try {
-            apiKey = await readKey(this.vaultOpener);
+            apiKey = await readKey(this.vaultOpener, 'stt');
         }
         catch (err) {
             throw err;
         }
-        const language = req.languageHint || DEFAULT_STT_LANGUAGE;
+        const rawLanguage = req.languageHint || DEFAULT_STT_LANGUAGE;
         const encoding = sttFormatToGoogleEncoding(req.format);
-        const model = req.model ?? 'latest_short';
+        /* Spanish locale normalisation (post-2026-05-31).
+         * Google STT enhanced models support a limited set of
+         * Spanish locale codes -- es-AR, es-CL, es-PE, etc are NOT
+         * in the matrix and trigger "model not supported for
+         * language". We map any specifically-regional Latin-Spanish
+         * locale to es-US (Latin American Spanish neutral), which
+         * IS supported by latest_long + useEnhanced and produces
+         * vastly better transcripts than the basic model for
+         * conversational castellano. es-ES (Spain) + es-US +
+         * es-419 (Latin neutral) pass through unchanged. */
+        const language = normaliseSpanishLocale(rawLanguage);
+        const isSpanish = /^es(-|$)/i.test(language);
+        /* Model handling: caller-supplied wins; otherwise force
+         * latest_long for Spanish (accent + aspirated-s handling). */
+        const model = req.model
+            ?? (isSpanish ? 'latest_long' : undefined);
+        const useEnhanced = isSpanish;
         const body = {
             config: {
                 encoding,
                 languageCode: language,
-                model,
                 enableAutomaticPunctuation: true,
             },
             audio: {
                 content: req.audio.toString('base64'),
             },
         };
+        if (model) {
+            body.config.model = model;
+        }
+        if (useEnhanced) {
+            body.config.useEnhanced = true;
+        }
         const t0 = Date.now();
         const resp = await this.fetchImpl(STT_ENDPOINT + '?key=' + encodeURIComponent(apiKey), {
             method: 'POST',
@@ -147,7 +287,7 @@ export class GoogleSttProvider {
             text,
             latency_ms,
             provider: this.id,
-            model,
+            ...(model ? { model } : {}),
             ...(confidence !== undefined ? { confidence } : {}),
             ...(detectedLang ? { language: detectedLang } : {}),
         };
@@ -165,21 +305,50 @@ export class GoogleTtsProvider {
         this.vaultOpener = opts.vaultOpener ?? (() => Vault.open({ configDir: configDir() }));
     }
     async readyToRun() {
-        try {
-            const vault = await this.vaultOpener();
-            return vault.has(VAULT_SLOT);
-        }
-        catch {
-            return false;
-        }
+        return hasKey(this.vaultOpener, 'tts');
     }
     async synthesize(req) {
         if (!req.text || req.text.trim() === '') {
             throw new Error('google TTS: text is empty');
         }
-        const apiKey = await readKey(this.vaultOpener);
-        const voice = req.voice ?? DEFAULT_TTS_VOICE;
-        const language = req.language ?? this.inferLanguageFromVoice(voice) ?? DEFAULT_TTS_LANGUAGE;
+        const apiKey = await readKey(this.vaultOpener, 'tts');
+        /* Voice persona resolution. Priority:
+         *  1. explicit req.voice (caller overrides)
+         *  2. mapped from req.language via LOCALE_TO_VOICE
+         *  3. DEFAULT_TTS_VOICE (en-US-Neural2-C)
+         *  This makes the bot sound natural per language without
+         *  the caller having to know Google's voice catalog.
+         *
+         *  Language code derivation (post-2026-05-31 fix). Google
+         *  REQUIRES voice.languageCode to match the voice's own
+         *  language. If we pick voice="es-US-Neural2-A" for a
+         *  request that asked for "es-AR", we MUST send
+         *  languageCode="es-US" -- otherwise Google rejects with
+         *  "language code doesn't match the voice's". Concretely:
+         *   - if caller passed an explicit req.voice, trust caller's
+         *     req.language as the contract.
+         *   - if we picked the voice from the locale map, the voice
+         *     wins: language gets inferred from voice.
+         *   - if neither, both default.
+         *
+         *  alpha.29 bugfix: previously the caller-supplied path
+         *  trusted req.language even when it did NOT match the
+         *  voice's own language. Google rejects mismatch:
+         *    "Requested language code 'es' doesn't match the voice
+         *     'es-ES-Neural2-A''s language code 'es-es'."
+         *  New rule: when we have a voice (regardless of where it
+         *  came from), the voice ALWAYS dictates languageCode.
+         *  req.language is only used as a hint to pick the voice
+         *  when the caller did not supply one. */
+        const langKey = (req.language || '').toLowerCase();
+        const voice = req.voice
+            ?? (langKey ? voiceForLocale(langKey) : undefined)
+            ?? DEFAULT_TTS_VOICE;
+        const inferred = this.inferLanguageFromVoice(voice);
+        /* Always prefer the voice's own languageCode; fall back to
+         * req.language only when the voice name is non-standard
+         * (cannot parse first two segments). */
+        const language = inferred ?? req.language ?? DEFAULT_TTS_LANGUAGE;
         const format = req.format ?? DEFAULT_TTS_FORMAT;
         const encoding = ttsFormatToGoogleEncoding(format);
         const speakingRate = this.clampSpeed(req.speed);