@hyperdrive.bot/paseo-protocol 0.3.45 → 0.3.47

package/dist/language.d.ts

@@ -0,0 +1,82 @@
+/** BCP-47 tag used when nothing else is known. */
+export declare const DEFAULT_LANGUAGE_TAG = "en-US";
+/**
+ * Curated language list offered in the audio-mode pickers.
+ *
+ * Covers the app's own eight shipped UI locales plus the widely-requested
+ * European speech languages. It is intentionally a curated list rather than
+ * "everything a provider supports": STT coverage is provider-dependent (the
+ * default local Parakeet v2 model is English-only; OpenAI Whisper is not), so a
+ * longer list would promise accuracy paseo cannot deliver on the default stack.
+ */
+export declare const AUDIO_LANGUAGES: readonly [{
+    readonly tag: "en-US";
+    readonly label: "English";
+    readonly nativeLabel: "English";
+}, {
+    readonly tag: "pt-BR";
+    readonly label: "Portuguese (Brazil)";
+    readonly nativeLabel: "Português (Brasil)";
+}, {
+    readonly tag: "es-ES";
+    readonly label: "Spanish";
+    readonly nativeLabel: "Español";
+}, {
+    readonly tag: "fr-FR";
+    readonly label: "French";
+    readonly nativeLabel: "Français";
+}, {
+    readonly tag: "de-DE";
+    readonly label: "German";
+    readonly nativeLabel: "Deutsch";
+}, {
+    readonly tag: "it-IT";
+    readonly label: "Italian";
+    readonly nativeLabel: "Italiano";
+}, {
+    readonly tag: "ja-JP";
+    readonly label: "Japanese";
+    readonly nativeLabel: "日本語";
+}, {
+    readonly tag: "zh-CN";
+    readonly label: "Chinese (Simplified)";
+    readonly nativeLabel: "简体中文";
+}, {
+    readonly tag: "ru-RU";
+    readonly label: "Russian";
+    readonly nativeLabel: "Русский";
+}, {
+    readonly tag: "ar-SA";
+    readonly label: "Arabic";
+    readonly nativeLabel: "العربية";
+}];
+export type AudioLanguageTag = (typeof AUDIO_LANGUAGES)[number]["tag"];
+/**
+ * Normalize any user- or config-supplied tag to canonical BCP-47 casing
+ * ("PT-br" -> "pt-BR"). Returns undefined for empty/unusable input rather than
+ * inventing a default, so callers decide their own fallback.
+ */
+export declare function normalizeLanguageTag(value: string | null | undefined): string | undefined;
+/**
+ * BCP-47 -> ISO-639-1, the form the speech daemon and OpenAI Whisper expect
+ * ("pt-BR" -> "pt"). This is the ONLY place the conversion happens.
+ */
+export declare function toIso639(value: string | null | undefined): string | undefined;
+/**
+ * True when the tag resolves to a language paseo can NAME in English.
+ *
+ * `normalizeLanguageTag` only checks shape, and a 2-3 letter shape is cheap to
+ * hit by accident: "not-a-language" normalizes to the syntactically valid
+ * subtag "not". Callers that put the name into a prompt must gate on this, so
+ * a typo produces NO instruction rather than a confident instruction to write
+ * everything in "not".
+ */
+export declare function isKnownLanguage(value: string | null | undefined): boolean;
+/**
+ * Human-readable English name for a language tag, for embedding in prompts and
+ * logs. Falls back to the normalized tag itself so an unlisted-but-valid
+ * language still renders as something in a UI or a log line. Prompt builders
+ * must gate on {@link isKnownLanguage} first.
+ */
+export declare function languageLabel(value: string | null | undefined): string | undefined;
+//# sourceMappingURL=language.d.ts.map

package/dist/language.js

@@ -0,0 +1,148 @@
+// Shared language vocabulary for paseo's two audio modes (dictation + voice mode)
+// and for the agent's output language.
+//
+// Two DIFFERENT parameters live here, and conflating them is the bug this module
+// exists to prevent:
+//
+// - **input language**  = the language the human SPEAKS into the microphone.
+//   Per device, never per session: the same agent can be open on a phone, a
+//   desktop and a watch, each with a different microphone in front of a
+//   different mouth. It drives STT only.
+// - **output language** = the language the agent WRITES and SPEAKS back in.
+//   Per session, replicated with the agent record, because it is a property of
+//   the work ("this agent works in English"), not of any one microphone.
+//
+// The two are deliberately decoupled: speaking Portuguese while the repo, the
+// commits and the docs stay English is a first-class combination, not an edge
+// case.
+//
+// Tag formats: the app edge speaks BCP-47 ("pt-BR"), the speech daemon speaks
+// ISO-639-1 ("pt"). `toIso639` is the single conversion point; do the
+// conversion at the boundary and nowhere else.
+/** BCP-47 tag used when nothing else is known. */
+export const DEFAULT_LANGUAGE_TAG = "en-US";
+/**
+ * Curated language list offered in the audio-mode pickers.
+ *
+ * Covers the app's own eight shipped UI locales plus the widely-requested
+ * European speech languages. It is intentionally a curated list rather than
+ * "everything a provider supports": STT coverage is provider-dependent (the
+ * default local Parakeet v2 model is English-only; OpenAI Whisper is not), so a
+ * longer list would promise accuracy paseo cannot deliver on the default stack.
+ */
+export const AUDIO_LANGUAGES = [
+    { tag: "en-US", label: "English", nativeLabel: "English" },
+    { tag: "pt-BR", label: "Portuguese (Brazil)", nativeLabel: "Português (Brasil)" },
+    { tag: "es-ES", label: "Spanish", nativeLabel: "Español" },
+    { tag: "fr-FR", label: "French", nativeLabel: "Français" },
+    { tag: "de-DE", label: "German", nativeLabel: "Deutsch" },
+    { tag: "it-IT", label: "Italian", nativeLabel: "Italiano" },
+    { tag: "ja-JP", label: "Japanese", nativeLabel: "日本語" },
+    { tag: "zh-CN", label: "Chinese (Simplified)", nativeLabel: "简体中文" },
+    { tag: "ru-RU", label: "Russian", nativeLabel: "Русский" },
+    { tag: "ar-SA", label: "Arabic", nativeLabel: "العربية" },
+];
+/**
+ * English display names keyed by ISO-639-1, used to render a language name
+ * inside a system prompt.
+ *
+ * Deliberately a static map rather than `Intl.DisplayNames`: the value is
+ * embedded in a prompt and must be byte-identical across the daemon, the tests
+ * and every Node/Hermes runtime paseo runs on. `Intl` availability and output
+ * both vary by runtime.
+ */
+const LANGUAGE_LABELS_BY_ISO639 = {
+    ar: "Arabic",
+    de: "German",
+    en: "English",
+    es: "Spanish",
+    fr: "French",
+    hi: "Hindi",
+    it: "Italian",
+    ja: "Japanese",
+    ko: "Korean",
+    nl: "Dutch",
+    pl: "Polish",
+    pt: "Portuguese",
+    ru: "Russian",
+    sv: "Swedish",
+    tr: "Turkish",
+    zh: "Chinese",
+};
+/** Region subtags worth naming explicitly, because the variants differ in use. */
+const REGION_LABELS = {
+    "pt-BR": "Portuguese (Brazil)",
+    "pt-PT": "Portuguese (Portugal)",
+    "en-US": "English (US)",
+    "en-GB": "English (UK)",
+    "zh-CN": "Chinese (Simplified)",
+    "zh-TW": "Chinese (Traditional)",
+};
+/**
+ * Normalize any user- or config-supplied tag to canonical BCP-47 casing
+ * ("PT-br" -> "pt-BR"). Returns undefined for empty/unusable input rather than
+ * inventing a default, so callers decide their own fallback.
+ */
+export function normalizeLanguageTag(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const [primary, ...rest] = trimmed.replace(/_/g, "-").split("-");
+    if (!primary) {
+        return undefined;
+    }
+    const language = primary.toLowerCase();
+    if (!/^[a-z]{2,3}$/.test(language)) {
+        return undefined;
+    }
+    const region = rest.find((part) => /^[A-Za-z]{2}$/.test(part) || /^[0-9]{3}$/.test(part));
+    return region ? `${language}-${region.toUpperCase()}` : language;
+}
+/**
+ * BCP-47 -> ISO-639-1, the form the speech daemon and OpenAI Whisper expect
+ * ("pt-BR" -> "pt"). This is the ONLY place the conversion happens.
+ */
+export function toIso639(value) {
+    const normalized = normalizeLanguageTag(value);
+    return normalized?.split("-")[0];
+}
+/**
+ * True when the tag resolves to a language paseo can NAME in English.
+ *
+ * `normalizeLanguageTag` only checks shape, and a 2-3 letter shape is cheap to
+ * hit by accident: "not-a-language" normalizes to the syntactically valid
+ * subtag "not". Callers that put the name into a prompt must gate on this, so
+ * a typo produces NO instruction rather than a confident instruction to write
+ * everything in "not".
+ */
+export function isKnownLanguage(value) {
+    const normalized = normalizeLanguageTag(value);
+    if (!normalized) {
+        return false;
+    }
+    if (REGION_LABELS[normalized]) {
+        return true;
+    }
+    const iso = normalized.split("-")[0] ?? normalized;
+    return Boolean(LANGUAGE_LABELS_BY_ISO639[iso]);
+}
+/**
+ * Human-readable English name for a language tag, for embedding in prompts and
+ * logs. Falls back to the normalized tag itself so an unlisted-but-valid
+ * language still renders as something in a UI or a log line. Prompt builders
+ * must gate on {@link isKnownLanguage} first.
+ */
+export function languageLabel(value) {
+    const normalized = normalizeLanguageTag(value);
+    if (!normalized) {
+        return undefined;
+    }
+    const regionLabel = REGION_LABELS[normalized];
+    if (regionLabel) {
+        return regionLabel;
+    }
+    const iso = normalized.split("-")[0] ?? normalized;
+    return LANGUAGE_LABELS_BY_ISO639[iso] ?? normalized;
+}
+//# sourceMappingURL=language.js.map