@hyperdrive.bot/paseo-protocol 0.3.45 → 0.3.46

package/dist/agent-types.d.ts

@@ -429,6 +429,23 @@ export interface AgentSessionConfig {
      * Mapped by each provider to its native instruction field.
      */
     systemPrompt?: string;
+    /**
+     * BCP-47 tag for the language the agent must WRITE and SPEAK back in
+     * ("en-US", "pt-BR"). Session-scoped on purpose: it describes the work
+     * ("this agent works in English"), so it follows the agent across every
+     * device, client and resume, and it applies to typed input just as much as
+     * to dictated or spoken input.
+     *
+     * Deliberately a structured field and NOT prose folded into `systemPrompt`:
+     * voice mode rewrites `systemPrompt` by regex on every toggle
+     * (`stripVoiceModeSystemPrompt`), so anything stored in that string is
+     * living in a field another feature routinely edits. The instruction text is
+     * composed at prompt-build time instead.
+     *
+     * Undefined means "no instruction", i.e. the model mirrors the user's own
+     * language, which is the pre-existing behaviour.
+     */
+    outputLanguage?: string;
     modeId?: string;
     model?: string;
     thinkingOptionId?: string;

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

package/dist/messages.d.ts

@@ -1861,6 +1861,7 @@ export declare const CreateAgentRequestMessageSchema: z.ZodObject<{
             claude: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
         }, z.core.$strip>>;
         systemPrompt: z.ZodOptional<z.ZodString>;
+        outputLanguage: z.ZodOptional<z.ZodString>;
         mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"stdio">;
             command: z.ZodString;
@@ -2050,6 +2051,7 @@ export declare const ResumeAgentRequestMessageSchema: z.ZodObject<{
             claude: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
         }, z.core.$strip>>>;
         systemPrompt: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        outputLanguage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         mcpServers: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"stdio">;
             command: z.ZodString;
@@ -4089,6 +4091,7 @@ export declare const SessionInboundMessageSchema: z.ZodDiscriminatedUnion<[z.Zod
             claude: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
         }, z.core.$strip>>;
         systemPrompt: z.ZodOptional<z.ZodString>;
+        outputLanguage: z.ZodOptional<z.ZodString>;
         mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"stdio">;
             command: z.ZodString;
@@ -4273,6 +4276,7 @@ export declare const SessionInboundMessageSchema: z.ZodDiscriminatedUnion<[z.Zod
             claude: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
         }, z.core.$strip>>>;
         systemPrompt: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        outputLanguage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         mcpServers: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"stdio">;
             command: z.ZodString;
@@ -21461,6 +21465,7 @@ export declare const WSSessionInboundSchema: z.ZodObject<{
                 claude: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
             }, z.core.$strip>>;
             systemPrompt: z.ZodOptional<z.ZodString>;
+            outputLanguage: z.ZodOptional<z.ZodString>;
             mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"stdio">;
                 command: z.ZodString;
@@ -21645,6 +21650,7 @@ export declare const WSSessionInboundSchema: z.ZodObject<{
                 claude: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
             }, z.core.$strip>>>;
             systemPrompt: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            outputLanguage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
             mcpServers: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"stdio">;
                 command: z.ZodString;
@@ -31087,6 +31093,7 @@ export declare const WSInboundMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
                 claude: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
             }, z.core.$strip>>;
             systemPrompt: z.ZodOptional<z.ZodString>;
+            outputLanguage: z.ZodOptional<z.ZodString>;
             mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"stdio">;
                 command: z.ZodString;
@@ -31271,6 +31278,7 @@ export declare const WSInboundMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
                 claude: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
             }, z.core.$strip>>>;
             systemPrompt: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            outputLanguage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
             mcpServers: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"stdio">;
                 command: z.ZodString;

package/dist/messages.js

@@ -516,6 +516,11 @@ const AgentSessionConfigSchema = z.object({
         .partial()
         .optional(),
     systemPrompt: z.string().optional(),
+    // BCP-47 tag the agent must write and speak back in. Session-scoped, so it
+    // follows the agent across devices and survives resume. See
+    // AgentSessionConfig.outputLanguage in agent-types.ts for why it is a
+    // structured field rather than prose inside systemPrompt.
+    outputLanguage: z.string().optional(),
     mcpServers: z.record(z.string(), McpServerConfigSchema).optional(),
     // Per-run tool allowlist, in Claude Code permission-rule syntax ("Bash",
     // "Bash(git:*)", "mcp__server__tool"). Optional: absent means "no allowlist",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/paseo-protocol",
-  "version": "0.3.45",
+  "version": "0.3.46",
   "description": "Paseo shared protocol schemas and wire types",
   "files": [
     "dist",