@shogo-ai/voice 1.10.0 → 2.4.2

package/dist/route/op.cjs

@@ -0,0 +1,2127 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/route/op.ts
+var op_exports = {};
+__export(op_exports, {
+  GET: () => GET,
+  POST: () => POST,
+  voiceOpRoutes: () => voiceOpRoutes
+});
+module.exports = __toCommonJS(op_exports);
+
+// src/audioTags.ts
+var AUDIO_TAGS = [
+  // Emotions
+  { tag: "happy", group: "emotion", label: "Happy", description: "Warm, upbeat delivery.", example: "[happy] Oh, I\u2019m so glad you stopped by." },
+  { tag: "sad", group: "emotion", label: "Sad", description: "Subdued, heavy-hearted tone.", example: "[sad] I wish things had gone differently." },
+  { tag: "excited", group: "emotion", label: "Excited", description: "Energized, eager delivery.", example: "[excited] Wait until you hear this!" },
+  { tag: "curious", group: "emotion", label: "Curious", description: "Inquisitive, rising inflection.", example: "[curious] Hmm, what did they look like?" },
+  { tag: "sarcastic", group: "emotion", label: "Sarcastic", description: "Dry, ironic tone.", example: "[sarcastic] Oh, fantastic. Another Monday." },
+  { tag: "angry", group: "emotion", label: "Angry", description: "Sharp, irritated edge.", example: "[angry] I told you not to touch that." },
+  { tag: "nervous", group: "emotion", label: "Nervous", description: "Uneasy, faltering delivery.", example: "[nervous] I\u2014 I didn\u2019t think you\u2019d actually come." },
+  { tag: "confident", group: "emotion", label: "Confident", description: "Grounded, assured delivery.", example: "[confident] Trust me. I\u2019ve done this before." },
+  // Delivery
+  { tag: "whispers", group: "delivery", label: "Whispers", description: "Hushed, close-mic delivery.", example: "[whispers] Don\u2019t say it too loud." },
+  { tag: "shouts", group: "delivery", label: "Shouts", description: "Loud, projected delivery.", example: "[shouts] Look out behind you!" },
+  { tag: "softly", group: "delivery", label: "Softly", description: "Gentle, quiet tone.", example: "[softly] It\u2019s okay. I\u2019m here." },
+  { tag: "slowly", group: "delivery", label: "Slowly", description: "Deliberate pacing.", example: "[slowly] Tell me\u2026 exactly\u2026 what happened." },
+  { tag: "quickly", group: "delivery", label: "Quickly", description: "Rapid, urgent pacing.", example: "[quickly] We need to go, right now." },
+  // Reactions (non-verbal sounds)
+  { tag: "laughs", group: "reaction", label: "Laughs", description: "A genuine laugh.", example: "That\u2019s ridiculous [laughs]." },
+  { tag: "chuckles", group: "reaction", label: "Chuckles", description: "A small, warm chuckle.", example: "[chuckles] You always say that." },
+  { tag: "sighs", group: "reaction", label: "Sighs", description: "An audible sigh.", example: "[sighs] Alright, fine. Let\u2019s do it." },
+  { tag: "gasps", group: "reaction", label: "Gasps", description: "A sharp inhale of surprise.", example: "[gasps] You didn\u2019t!" },
+  { tag: "hesitates", group: "reaction", label: "Hesitates", description: "A pause with uncertainty.", example: "[hesitates] I\u2019m not sure I should say." },
+  { tag: "clears throat", group: "reaction", label: "Clears throat", description: "Throat-clearing beat.", example: "[clears throat] As I was saying\u2026" }
+];
+var AUDIO_TAG_GROUPS = [
+  { id: "emotion", label: "Emotions", description: "Overall feeling carried through the line." },
+  { id: "delivery", label: "Delivery", description: "How the words are spoken (pace, volume)." },
+  { id: "reaction", label: "Reactions", description: "Non-verbal sounds mixed into speech." }
+];
+var EXPRESSIVITY_OPTIONS = [
+  { id: "off", label: "Off", description: "No audio tags. Plain, natural delivery." },
+  { id: "subtle", label: "Subtle", description: "Occasional tag when it genuinely fits. Default." },
+  { id: "full", label: "Full", description: "Freely expressive \u2014 tags sprinkled to carry emotion and reactions." }
+];
+var DEFAULT_ALLOWED_TAGS = [
+  "whispers",
+  "laughs",
+  "sighs",
+  "excited",
+  "curious",
+  "softly"
+];
+var DEFAULT_VOICE_SETTINGS = {
+  stability: 0.5,
+  similarity_boost: 0.8,
+  style: 0,
+  use_speaker_boost: true
+};
+var KNOWN_TAG_SET = new Set(AUDIO_TAGS.map((t) => t.tag.toLowerCase()));
+var EXPRESSIVITY_BLOCK_OPEN = "<!--expressivity-->";
+var EXPRESSIVITY_BLOCK_CLOSE = "<!--/expressivity-->";
+function stripExpressivityBlock(prompt) {
+  if (!prompt) return prompt;
+  const open = EXPRESSIVITY_BLOCK_OPEN;
+  const close = EXPRESSIVITY_BLOCK_CLOSE;
+  const openIdx = prompt.indexOf(open);
+  if (openIdx === -1) return prompt;
+  const closeIdx = prompt.indexOf(close, openIdx);
+  if (closeIdx === -1) return prompt;
+  const before = prompt.slice(0, openIdx).replace(/\s+$/, "");
+  const after = prompt.slice(closeIdx + close.length).replace(/^\s+/, "");
+  return [before, after].filter(Boolean).join("\n\n");
+}
+function composeExpressivityBlock(expressivity, allowedTags) {
+  if (expressivity === "off") return "";
+  const allowed = (allowedTags && allowedTags.length > 0 ? allowedTags : DEFAULT_ALLOWED_TAGS).filter((t) => AUDIO_TAGS.some((a) => a.tag === t));
+  if (allowed.length === 0) return "";
+  const intensity = expressivity === "full" ? "Use audio tags liberally to color your speech with emotion, delivery, and non-verbal reactions. Most substantive replies should include at least one tag. Never add so many tags that a line becomes unnatural." : "Use audio tags sparingly \u2014 only when one genuinely fits the emotion or reaction of the moment. Most lines will have no tag. At most one or two tags per reply.";
+  const tagList = allowed.map((t) => {
+    const entry = AUDIO_TAGS.find((a) => a.tag === t);
+    return `  - [${entry.tag}] \u2014 ${entry.description} Example: ${entry.example}`;
+  }).join("\n");
+  const body = [
+    "You speak through an expressive TTS engine that understands inline audio tags.",
+    'Audio tags are lowercase words in square brackets placed directly in your spoken text \u2014 e.g. "[whispers] don\u2019t tell anyone" or "that was wild [laughs]".',
+    'Tags are performance cues, not words. Never describe a tag (do not say "asterisk laughs asterisk" or "*laughs*"). Never read a tag aloud. Never put tags inside quoted speech from another character.',
+    intensity,
+    "You may only use tags from this allow-list:",
+    tagList,
+    "If no tag fits, use none. Tags are optional flavor, not filler."
+  ].join("\n");
+  return `${EXPRESSIVITY_BLOCK_OPEN}
+${body}
+${EXPRESSIVITY_BLOCK_CLOSE}`;
+}
+function buildPreviewLine(allowedTags, characterName = "your companion") {
+  const tags = (allowedTags ?? []).filter((t) => AUDIO_TAGS.some((a) => a.tag === t));
+  if (tags.length === 0) {
+    return `Hi there. This is a quick preview of how ${characterName} sounds.`;
+  }
+  const pick = tags.slice(0, 3);
+  const lead = pick[0];
+  const mid = pick[1];
+  const tail = pick[2];
+  if (pick.length === 1) {
+    return `[${lead}] Hey \u2014 this is how ${characterName} sounds when the mood takes over.`;
+  }
+  if (pick.length === 2) {
+    return `[${lead}] Oh, this is fun. [${mid}] Let me know what you think.`;
+  }
+  return `[${lead}] Okay, listen. [${mid}] This is the new voice. [${tail}] How does it feel?`;
+}
+function normalizeAudioTags(raw) {
+  if (!Array.isArray(raw)) return null;
+  const cleaned = raw.filter((x) => typeof x === "string").map((x) => x.trim().toLowerCase()).filter((x) => AUDIO_TAGS.some((a) => a.tag === x));
+  return Array.from(new Set(cleaned));
+}
+function normalizeExpressivity(raw) {
+  if (raw === "off" || raw === "subtle" || raw === "full") return raw;
+  return void 0;
+}
+function normalizeVoiceSettings(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const src = raw;
+  const out = {};
+  const clamp = (v) => typeof v === "number" && Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : void 0;
+  const stability = clamp(src.stability);
+  const similarity = clamp(src.similarity_boost ?? src.similarityBoost);
+  const style = clamp(src.style);
+  const boost = src.use_speaker_boost ?? src.useSpeakerBoost;
+  if (stability !== void 0) out.stability = stability;
+  if (similarity !== void 0) out.similarity_boost = similarity;
+  if (style !== void 0) out.style = style;
+  if (typeof boost === "boolean") out.use_speaker_boost = boost;
+  return Object.keys(out).length ? out : void 0;
+}
+function readAudioTags(raw) {
+  const norm = normalizeAudioTags(raw);
+  return norm && norm.length > 0 ? norm : DEFAULT_ALLOWED_TAGS;
+}
+function readExpressivity(raw) {
+  return normalizeExpressivity(raw) ?? "subtle";
+}
+function readVoiceSettings(raw) {
+  return normalizeVoiceSettings(raw) ?? { ...DEFAULT_VOICE_SETTINGS };
+}
+
+// src/prompt.ts
+var DEFAULT_MEMORY_BLOCK = `# Memory
+
+Known context about this user from past conversations:
+{{user_context}}
+
+Memory retrieval is automatic \u2014 the top matching facts are already injected above. Never say "let me check my memory" or "searching memories."
+
+You have one tool:
+- add_memory(fact): save a concise, canonical fact about the user \u2014 preferences, decisions, personal details, follow-ups. Use short normalized phrasings like "favorite color: green" or "lives in Honolulu". Always call it when the user explicitly asks you to remember something.`;
+function stripMemoryBlock(prompt) {
+  if (!prompt) return prompt;
+  return prompt.replace(/\n*<!-- zix-memory-v\d+ -->[\s\S]*$/m, "").replace(/\n*# Memory\s*\n\s*Known context about this user[\s\S]*$/m, "").trimEnd();
+}
+function extractBasePrompt(prompt) {
+  return stripExpressivityBlock(stripMemoryBlock(prompt));
+}
+function composeAgentPrompt(basePrompt, options = {}) {
+  const { expressivity = "subtle", audioTags = null, memoryBlock = DEFAULT_MEMORY_BLOCK } = options;
+  const stripped = extractBasePrompt(basePrompt);
+  const expr = composeExpressivityBlock(expressivity, audioTags);
+  const parts = [stripped];
+  if (expr) parts.push(expr);
+  if (memoryBlock) parts.push(memoryBlock);
+  return parts.join("\n\n");
+}
+
+// src/elevenlabs.ts
+var DEFAULT_ELEVENLABS_BASE_URL = "https://api.elevenlabs.io";
+var VOICE_TTS_MODELS = [
+  { id: "eleven_v4", label: "Eleven v4", realtime: false, maxChars: 1e4 },
+  { id: "eleven_v4_turbo", label: "Eleven v4 Turbo", realtime: true, maxChars: 1e4 },
+  { id: "eleven_v3", label: "Eleven v3", realtime: false, maxChars: 5e3 },
+  {
+    id: "eleven_v3_conversational",
+    label: "Eleven v3 Conversational",
+    realtime: true,
+    maxChars: 5e3
+  },
+  { id: "eleven_multilingual_v2", label: "Eleven Multilingual v2", realtime: false, maxChars: 1e4 },
+  { id: "eleven_flash_v2_5", label: "Eleven Flash v2.5", realtime: true, maxChars: 4e4 },
+  { id: "eleven_flash_v2", label: "Eleven Flash v2", realtime: true, maxChars: 3e4 },
+  { id: "eleven_turbo_v2_5", label: "Eleven Turbo v2.5", realtime: true, maxChars: 4e4 },
+  { id: "eleven_turbo_v2", label: "Eleven Turbo v2", realtime: true, maxChars: 3e4, deprecated: true }
+];
+var VOICE_TTS_MODEL_IDS = VOICE_TTS_MODELS.map((m) => m.id);
+var DEFAULT_TTS_MODEL = "eleven_v4";
+var CONVAI_SUPPORTED_TTS_MODELS = new Set(
+  VOICE_TTS_MODELS.filter((m) => m.realtime).map((m) => m.id)
+);
+var CONVAI_TTS_MODEL_FALLBACK = "eleven_v4_turbo";
+var TTS_FALLBACK_MODEL = "eleven_flash_v2_5";
+function getVoiceTtsModel(modelId) {
+  if (!modelId) return void 0;
+  return VOICE_TTS_MODELS.find((m) => m.id === modelId);
+}
+var loggedDowngrades = /* @__PURE__ */ new Set();
+function resolveConvaiTtsModelDetailed(requested) {
+  if (requested && CONVAI_SUPPORTED_TTS_MODELS.has(requested)) {
+    return { modelId: requested, requested, downgraded: false };
+  }
+  const known = getVoiceTtsModel(requested);
+  const reason = !requested ? void 0 : known ? `${requested} is not supported by the convai realtime runtime` : `unknown TTS model ${requested}`;
+  if (reason && !loggedDowngrades.has(requested)) {
+    loggedDowngrades.add(requested);
+    try {
+      console.warn(
+        `[voice] convai TTS model ${requested} is unavailable (${reason}); using ${CONVAI_TTS_MODEL_FALLBACK}`
+      );
+    } catch {
+    }
+  }
+  return {
+    modelId: CONVAI_TTS_MODEL_FALLBACK,
+    requested: requested ?? null,
+    downgraded: Boolean(requested),
+    ...reason ? { reason } : {}
+  };
+}
+function resolveConvaiTtsModel(requested) {
+  return resolveConvaiTtsModelDetailed(requested).modelId;
+}
+function isModelRelatedTtsFailure(status, body) {
+  if (status === 402) return true;
+  if (status !== 400 && status !== 403 && status !== 404 && status !== 422) return false;
+  return /model|plan|permission/i.test(body);
+}
+var DEFAULT_MUSIC_MODEL = "music_v1";
+var VOICE_STS_MODEL_IDS = [
+  "eleven_multilingual_sts_v2",
+  "eleven_english_sts_v2"
+];
+var DEFAULT_STS_MODEL = "eleven_multilingual_sts_v2";
+var VOICE_SPEECH_TO_TEXT_MODEL_IDS = ["scribe_v1"];
+var DEFAULT_SPEECH_TO_TEXT_MODEL = "scribe_v1";
+var VOICE_SOUND_GENERATION_MODEL_IDS = ["eleven_text_to_sound_v2"];
+var DEFAULT_SOUND_GENERATION_MODEL = "eleven_text_to_sound_v2";
+var ElevenLabsApiError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "ElevenLabsApiError";
+  }
+};
+var ElevenLabsClient = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.apiKey) throw new Error("ElevenLabsClient: apiKey is required");
+    this.baseUrl = (config.baseUrl ?? DEFAULT_ELEVENLABS_BASE_URL).replace(/\/+$/, "");
+    this.fetchImpl = config.fetch ?? globalThis.fetch;
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("ElevenLabsClient: global fetch is unavailable; pass config.fetch");
+    }
+  }
+  headers(extra = {}) {
+    return {
+      "xi-api-key": this.config.apiKey,
+      ...extra
+    };
+  }
+  /** Create a new convai agent. Returns the new `agent_id`. */
+  async createAgent(params) {
+    const prompt = composeAgentPrompt(params.systemPrompt, {
+      expressivity: params.expressivity ?? "subtle",
+      audioTags: params.audioTags ?? null,
+      memoryBlock: params.memoryBlock
+    });
+    const ttsConfig = {
+      voice_id: params.voiceId,
+      model_id: resolveConvaiTtsModel(params.ttsModelId)
+    };
+    if (params.voiceSettings) ttsConfig.voice_settings = params.voiceSettings;
+    const body = {
+      name: `Companion-${params.characterName}-for-${params.displayName}`,
+      conversation_config: {
+        agent: {
+          prompt: {
+            prompt,
+            ...params.tools ? { tools: params.tools } : {}
+          },
+          first_message: params.firstMessage,
+          language: params.language ?? "en"
+        },
+        tts: ttsConfig
+      },
+      platform_settings: {
+        overrides: {
+          conversation_config_override: {
+            agent: { prompt: { prompt: true }, first_message: true, language: true },
+            tts: { voice_id: true },
+            conversation: { text_only: true }
+          }
+        },
+        dynamic_variables: {
+          dynamic_variable_placeholders: {
+            user_context: "No prior memories yet.",
+            character_name: "",
+            ...params.dynamicVariablePlaceholders ?? {}
+          }
+        }
+      }
+    };
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/convai/agents/create`, {
+      method: "POST",
+      headers: this.headers({ "content-type": "application/json" }),
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new ElevenLabsApiError(`createAgent failed: ${res.status}`, res.status, text);
+    }
+    const data = await res.json();
+    return data.agent_id;
+  }
+  /** PATCH any subset of agent settings. Idempotent; only sends the keys you supply. */
+  async patchAgent(agentId, params) {
+    const body = {};
+    if (params.displayName !== void 0 || params.characterName !== void 0) {
+      body.name = `Companion-${params.characterName ?? ""}-for-${params.displayName ?? ""}`.replace(
+        /-for-$/,
+        ""
+      );
+    }
+    const conv = {};
+    const agent = {};
+    const prompt = {};
+    if (params.systemPrompt !== void 0) {
+      prompt.prompt = composeAgentPrompt(params.systemPrompt, {
+        expressivity: params.expressivity ?? "subtle",
+        audioTags: params.audioTags ?? null,
+        memoryBlock: params.memoryBlock
+      });
+    }
+    if (params.tools) prompt.tools = params.tools;
+    if (Object.keys(prompt).length) agent.prompt = prompt;
+    if (params.firstMessage !== void 0) agent.first_message = params.firstMessage;
+    if (Object.keys(agent).length) conv.agent = agent;
+    const tts = {};
+    if (params.voiceId !== void 0) tts.voice_id = params.voiceId;
+    if (params.voiceSettings) tts.voice_settings = params.voiceSettings;
+    if (params.ttsModelId !== void 0) tts.model_id = resolveConvaiTtsModel(params.ttsModelId);
+    if (Object.keys(tts).length) conv.tts = tts;
+    if (Object.keys(conv).length) body.conversation_config = conv;
+    if (params.enableUserContextOverride) {
+      body.platform_settings = {
+        overrides: {
+          conversation_config_override: {
+            agent: { prompt: { prompt: true }, first_message: true, language: true },
+            tts: { voice_id: true },
+            conversation: { text_only: true }
+          },
+          custom_llm_extra_body: false,
+          enable_conversation_initiation_client_data_from_webhook: false
+        },
+        dynamic_variables: {
+          dynamic_variable_placeholders: {
+            user_context: "No prior memories yet.",
+            character_name: ""
+          }
+        }
+      };
+    }
+    if (!Object.keys(body).length) return;
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/convai/agents/${encodeURIComponent(agentId)}`, {
+      method: "PATCH",
+      headers: this.headers({ "content-type": "application/json" }),
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new ElevenLabsApiError(`patchAgent failed: ${res.status}`, res.status, text);
+    }
+  }
+  /**
+   * Delete a convai agent. Best-effort: swallow errors so teardown during a
+   * 500 response doesn't cascade into a second failure.
+   */
+  async deleteAgent(agentId) {
+    try {
+      await this.fetchImpl(`${this.baseUrl}/v1/convai/agents/${encodeURIComponent(agentId)}`, {
+        method: "DELETE",
+        headers: this.headers()
+      });
+    } catch {
+    }
+  }
+  /** Fetch a short-lived signed URL the browser can use to start a session. */
+  async getSignedUrl(agentId) {
+    const res = await this.fetchImpl(
+      `${this.baseUrl}/v1/convai/conversation/get-signed-url?agent_id=${encodeURIComponent(agentId)}`,
+      { headers: this.headers() }
+    );
+    if (!res.ok) {
+      const text = await res.text();
+      throw new ElevenLabsApiError(`getSignedUrl failed: ${res.status}`, res.status, text);
+    }
+    const data = await res.json();
+    return data.signed_url;
+  }
+  /**
+   * One-shot TTS. Returns the raw audio bytes plus the model that actually
+   * produced them.
+   *
+   * The requested model is never swapped silently: we only retry on
+   * {@link TTS_FALLBACK_MODEL} when the failure is plausibly about
+   * the model (400/403/404/422 whose body mentions model/plan/permission,
+   * or 402 for an out-of-plan model). Auth (401), rate limit (429), 5xx and
+   * network errors are surfaced as-is. When a fallback does happen the
+   * result reports `requestedModel`, `fellBack` and `fallbackReason`.
+   */
+  async textToSpeech(params) {
+    const requestedModel = params.modelId && params.modelId.length > 0 ? params.modelId : DEFAULT_TTS_MODEL;
+    const accept = params.accept ?? "audio/mpeg";
+    const attempt = async (m) => {
+      const res2 = await this.fetchImpl(
+        `${this.baseUrl}/v1/text-to-speech/${encodeURIComponent(params.voiceId)}`,
+        {
+          method: "POST",
+          headers: this.headers({ "content-type": "application/json", accept }),
+          body: JSON.stringify({
+            text: params.text,
+            model_id: m,
+            voice_settings: params.voiceSettings
+          })
+        }
+      );
+      return res2;
+    };
+    let res = await attempt(requestedModel);
+    let used = requestedModel;
+    let fellBack = false;
+    let fallbackReason;
+    if (!res.ok) {
+      const body = await res.text();
+      if (requestedModel !== TTS_FALLBACK_MODEL && isModelRelatedTtsFailure(res.status, body)) {
+        fallbackReason = `elevenlabs ${res.status} for ${requestedModel}: ${body.slice(0, 200)}`;
+        res = await attempt(TTS_FALLBACK_MODEL);
+        used = TTS_FALLBACK_MODEL;
+        fellBack = true;
+        if (!res.ok) {
+          const retryBody = await res.text();
+          throw new ElevenLabsApiError(
+            `textToSpeech failed: ${res.status}`,
+            res.status,
+            retryBody
+          );
+        }
+      } else {
+        throw new ElevenLabsApiError(`textToSpeech failed: ${res.status}`, res.status, body);
+      }
+    }
+    const audio = await res.arrayBuffer();
+    const contentType = res.headers.get("content-type") ?? accept;
+    return {
+      audio,
+      modelId: used,
+      requestedModel,
+      fellBack,
+      ...fallbackReason ? { fallbackReason } : {},
+      contentType
+    };
+  }
+  /**
+   * Low-level escape hatch for any ElevenLabs endpoint not covered by a
+   * dedicated method (music, sound-generation, speech-to-text, dubbing,
+   * voice-design, …). Handles auth, query encoding, JSON body encoding,
+   * and JSON-vs-binary response parsing; non-2xx responses throw
+   * {@link ElevenLabsApiError} like the typed methods do.
+   *
+   * @example
+   * ```ts
+   * const { json } = await el.request({ method: 'GET', path: '/v1/models' })
+   * const { audio } = await el.request({
+   *   method: 'POST',
+   *   path: '/v1/sound-generation',
+   *   body: { text: 'door creak' },
+   *   accept: 'audio/mpeg',
+   * })
+   * ```
+   */
+  async request(opts) {
+    const accept = opts.accept ?? "application/json";
+    let url = `${this.baseUrl}${opts.path.startsWith("/") ? "" : "/"}${opts.path}`;
+    if (opts.query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== null && v !== void 0) params.set(k, String(v));
+      }
+      const qs = params.toString();
+      if (qs) url += `${url.includes("?") ? "&" : "?"}${qs}`;
+    }
+    const headers = this.headers({ accept, ...opts.headers ?? {} });
+    const init = { method: opts.method, headers };
+    if (opts.body !== void 0 && opts.body !== null) {
+      const isPlainPayload = typeof opts.body === "object" && !(opts.body instanceof ArrayBuffer) && !(opts.body instanceof Uint8Array) && !(typeof Blob !== "undefined" && opts.body instanceof Blob) && !(typeof FormData !== "undefined" && opts.body instanceof FormData);
+      if (isPlainPayload) {
+        headers["content-type"] = "application/json";
+        init.body = JSON.stringify(opts.body);
+      } else {
+        init.body = opts.body;
+      }
+    }
+    const res = await this.fetchImpl(url, init);
+    if (!res.ok) {
+      const text = await res.text();
+      throw new ElevenLabsApiError(
+        `request ${opts.method} ${opts.path} failed: ${res.status}`,
+        res.status,
+        text
+      );
+    }
+    const contentType = res.headers.get("content-type") ?? accept;
+    if (contentType.includes("application/json")) {
+      return { status: res.status, contentType, json: await res.json() };
+    }
+    return { status: res.status, contentType, audio: await res.arrayBuffer() };
+  }
+  /**
+   * Generate music via `POST /v1/music`. Provide exactly one of `prompt`
+   * or `compositionPlan` (ElevenLabs returns 422 otherwise). Returns the
+   * raw audio bytes plus the response content type.
+   *
+   * @example
+   * ```ts
+   * const { audio } = await el.composeMusic({
+   *   prompt: 'Upbeat synthwave with driving bass',
+   *   musicLengthMs: 30_000,
+   * })
+   * ```
+   */
+  async composeMusic(params) {
+    const hasPrompt = typeof params.prompt === "string" && params.prompt.length > 0;
+    const hasPlan = params.compositionPlan != null;
+    if (hasPrompt === hasPlan) {
+      throw new Error(
+        "composeMusic: provide exactly one of `prompt` or `compositionPlan`"
+      );
+    }
+    const body = {
+      model_id: params.modelId ?? DEFAULT_MUSIC_MODEL
+    };
+    if (hasPrompt) {
+      body.prompt = params.prompt;
+      if (params.musicLengthMs !== void 0) body.music_length_ms = params.musicLengthMs;
+      if (params.forceInstrumental !== void 0) {
+        body.force_instrumental = params.forceInstrumental;
+      }
+    } else {
+      body.composition_plan = params.compositionPlan;
+    }
+    const { audio, contentType } = await this.request({
+      method: "POST",
+      path: "/v1/music",
+      body,
+      accept: "audio/mpeg",
+      ...params.outputFormat ? { query: { output_format: params.outputFormat } } : {}
+    });
+    if (!audio) {
+      throw new ElevenLabsApiError(
+        "composeMusic: expected audio bytes but got a JSON response",
+        500,
+        ""
+      );
+    }
+    return { audio, contentType };
+  }
+  /**
+   * Convert speech to speech — the "voice changer": keep the performance,
+   * swap the voice. `POST /v1/speech-to-speech/{voiceId}` with a multipart
+   * audio part. Returns the converted audio bytes.
+   *
+   * @example
+   * ```ts
+   * const { audio } = await el.speechToSpeech({
+   *   voiceId: '21m00Tcm4TlvDq8ikWAM',
+   *   audio: await fetch(myRecording).then((r) => r.blob()),
+   *   modelId: 'eleven_multilingual_sts_v2',
+   * })
+   * ```
+   */
+  async speechToSpeech(params) {
+    if (!params.voiceId) throw new Error("speechToSpeech: voiceId is required");
+    if (!params.audio) throw new Error("speechToSpeech: audio is required");
+    const form = new FormData();
+    form.set("audio", params.audio, params.fileName ?? "audio");
+    form.set("model_id", params.modelId ?? DEFAULT_STS_MODEL);
+    if (params.voiceSettings) {
+      form.set("voice_settings", JSON.stringify(params.voiceSettings));
+    }
+    if (params.outputFormat) form.set("output_format", params.outputFormat);
+    if (params.fileFormat) form.set("file_format", params.fileFormat);
+    if (params.seed !== void 0) form.set("seed", String(params.seed));
+    if (params.removeBackgroundNoise !== void 0) {
+      form.set("remove_background_noise", String(params.removeBackgroundNoise));
+    }
+    const { audio, contentType } = await this.request({
+      method: "POST",
+      path: `/v1/speech-to-speech/${encodeURIComponent(params.voiceId)}`,
+      body: form,
+      accept: "audio/mpeg"
+    });
+    if (!audio) {
+      throw new ElevenLabsApiError(
+        "speechToSpeech: expected audio bytes but got a JSON response",
+        500,
+        ""
+      );
+    }
+    return { audio, contentType };
+  }
+  /**
+   * Generate a sound effect from a text prompt. `POST /v1/sound-generation`.
+   *
+   * @example
+   * ```ts
+   * const { audio } = await el.soundEffects({ text: 'heavy wooden door creaking' })
+   * ```
+   */
+  async soundEffects(params) {
+    if (!params.text || !params.text.trim()) {
+      throw new Error("soundEffects: text is required");
+    }
+    const body = {
+      text: params.text,
+      model_id: params.modelId ?? DEFAULT_SOUND_GENERATION_MODEL
+    };
+    if (params.durationSeconds !== void 0) body.duration_seconds = params.durationSeconds;
+    if (params.promptInfluence !== void 0) body.prompt_influence = params.promptInfluence;
+    if (params.loop !== void 0) body.loop = params.loop;
+    const { audio, contentType } = await this.request({
+      method: "POST",
+      path: "/v1/sound-generation",
+      body,
+      accept: "audio/mpeg",
+      ...params.outputFormat ? { query: { output_format: params.outputFormat } } : {}
+    });
+    if (!audio) {
+      throw new ElevenLabsApiError(
+        "soundEffects: expected audio bytes but got a JSON response",
+        500,
+        ""
+      );
+    }
+    return { audio, contentType };
+  }
+  /**
+   * Transcribe audio with Scribe. `POST /v1/speech-to-text` (multipart).
+   *
+   * @example
+   * ```ts
+   * const { text } = await el.transcribe({ file: recording })
+   * ```
+   */
+  async transcribe(params) {
+    if (!params.file) throw new Error("transcribe: file is required");
+    const form = new FormData();
+    form.set("file", params.file, params.fileName ?? "audio");
+    form.set("model_id", params.modelId ?? DEFAULT_SPEECH_TO_TEXT_MODEL);
+    if (params.languageCode) form.set("language_code", params.languageCode);
+    if (params.diarize !== void 0) form.set("diarize", String(params.diarize));
+    if (params.tagAudioEvents !== void 0) {
+      form.set("tag_audio_events", String(params.tagAudioEvents));
+    }
+    if (params.numSpeakers !== void 0) form.set("num_speakers", String(params.numSpeakers));
+    const { json: json2 } = await this.request({
+      method: "POST",
+      path: "/v1/speech-to-text",
+      body: form,
+      accept: "application/json"
+    });
+    if (!json2 || typeof json2 !== "object") {
+      throw new ElevenLabsApiError(
+        "transcribe: expected a JSON transcription but got audio",
+        500,
+        ""
+      );
+    }
+    return json2;
+  }
+  /** Probe whether a given voice id still exists on the caller's account. */
+  async voiceExists(voiceId) {
+    const res = await this.fetchImpl(
+      `${this.baseUrl}/v1/voices/${encodeURIComponent(voiceId)}`,
+      { headers: this.headers() }
+    );
+    return res.ok;
+  }
+  /**
+   * Register a Twilio phone number with an ElevenLabs agent. EL becomes
+   * the SIP target for inbound calls to that number — Twilio bridges
+   * the call via EL's native integration and we never have to run a
+   * Media Streams ↔ convai WebSocket bridge ourselves.
+   *
+   * Returns the ElevenLabs `phone_number_id` (distinct from the Twilio
+   * `sid`) which is the handle used by `outboundCall` + `deletePhoneNumber`.
+   */
+  async createPhoneNumberTwilio(params) {
+    const body = {
+      phone_number: params.phoneNumber,
+      label: params.label ?? params.phoneNumber,
+      provider: "twilio",
+      sid: params.twilioAccountSid,
+      token: params.twilioAuthToken
+    };
+    const res = await this.fetchImpl(
+      `${this.baseUrl}/v1/convai/phone-numbers`,
+      {
+        method: "POST",
+        headers: this.headers({ "content-type": "application/json" }),
+        body: JSON.stringify(body)
+      }
+    );
+    if (!res.ok) {
+      const text = await res.text();
+      throw new ElevenLabsApiError(
+        `createPhoneNumberTwilio failed: ${res.status}`,
+        res.status,
+        text
+      );
+    }
+    const data = await res.json();
+    const id = data.phone_number_id ?? data.id;
+    if (!id) {
+      throw new ElevenLabsApiError(
+        "createPhoneNumberTwilio returned no id",
+        500,
+        JSON.stringify(data)
+      );
+    }
+    const patchRes = await this.fetchImpl(
+      `${this.baseUrl}/v1/convai/phone-numbers/${encodeURIComponent(id)}`,
+      {
+        method: "PATCH",
+        headers: this.headers({ "content-type": "application/json" }),
+        body: JSON.stringify({ agent_id: params.agentId })
+      }
+    );
+    if (!patchRes.ok) {
+      const text = await patchRes.text();
+      try {
+        await this.deletePhoneNumber(id);
+      } catch {
+      }
+      throw new ElevenLabsApiError(
+        `assignAgentToPhoneNumber failed: ${patchRes.status}`,
+        patchRes.status,
+        text
+      );
+    }
+    return { phoneNumberId: id };
+  }
+  /** Detach a previously-registered phone number from ElevenLabs. */
+  async deletePhoneNumber(phoneNumberId) {
+    const res = await this.fetchImpl(
+      `${this.baseUrl}/v1/convai/phone-numbers/${encodeURIComponent(phoneNumberId)}`,
+      { method: "DELETE", headers: this.headers() }
+    );
+    if (!res.ok && res.status !== 404) {
+      const text = await res.text();
+      throw new ElevenLabsApiError(
+        `deletePhoneNumber failed: ${res.status}`,
+        res.status,
+        text
+      );
+    }
+  }
+  /**
+   * Place an outbound PSTN call via a previously-registered EL phone
+   * number. EL drives Twilio (or a SIP trunk) under the hood — we just
+   * hand it the destination number and the agent to bridge to. Returns
+   * the Twilio `callSid` + EL `conversationId` for metering / tracing.
+   *
+   * As of 2026-Q2 the EL API uses provider-scoped routes:
+   *   - Twilio numbers → POST /v1/convai/twilio/outbound-call
+   *   - SIP numbers    → POST /v1/convai/sip-trunk/outbound-call
+   * and `agent_phone_number_id` is a body field (no longer a path
+   * segment). The previous `/v1/convai/phone-numbers/{id}/outbound-call`
+   * route now returns 404. Callers that don't know the provider can
+   * look it up from `GET /v1/convai/phone-numbers/{id}` (`provider:
+   * "twilio" | "sip_trunk"`); most hosted setups are Twilio, so that's
+   * the default here.
+   */
+  async outboundCall(params) {
+    const provider = params.provider ?? "twilio";
+    const body = {
+      agent_id: params.agentId,
+      agent_phone_number_id: params.phoneNumberId,
+      to_number: params.toNumber
+    };
+    if (params.dynamicVariables) {
+      body.conversation_initiation_client_data = {
+        dynamic_variables: params.dynamicVariables
+      };
+    }
+    const res = await this.fetchImpl(
+      `${this.baseUrl}/v1/convai/${provider}/outbound-call`,
+      {
+        method: "POST",
+        headers: this.headers({ "content-type": "application/json" }),
+        body: JSON.stringify(body)
+      }
+    );
+    if (!res.ok) {
+      const text = await res.text();
+      throw new ElevenLabsApiError(
+        `outboundCall failed: ${res.status}`,
+        res.status,
+        text
+      );
+    }
+    const data = await res.json();
+    const callSid = data.call_sid ?? data.callSid;
+    const conversationId = data.conversation_id ?? data.conversationId;
+    if (!callSid || !conversationId) {
+      throw new ElevenLabsApiError(
+        "outboundCall missing callSid or conversationId",
+        500,
+        JSON.stringify(data)
+      );
+    }
+    return { callSid, conversationId };
+  }
+};
+var MEMORY_CLIENT_TOOLS = [
+  {
+    type: "client",
+    name: "add_memory",
+    description: "Save a concise canonical fact about the user (preferences, decisions, personal details, follow-ups). Use whenever the user shares something worth remembering.",
+    expects_response: true,
+    parameters: {
+      type: "object",
+      properties: {
+        fact: {
+          type: "string",
+          description: 'A short normalized fact, e.g. "prefers window seats", "favorite color: green". Max 500 chars.'
+        }
+      },
+      required: ["fact"]
+    }
+  }
+];
+
+// src/ops.ts
+var MAX_AUDIO_BYTES = 25 * 1024 * 1024;
+var MAX_JSON_BYTES = 8 * 1024;
+var MAX_TEXT_BYTES = 256 * 1024;
+var VOICE_OPS = [
+  {
+    id: "text-to-speech",
+    method: "POST",
+    hostedPath: "/voice/op/text-to-speech",
+    legacyHostedPath: "/voice/tts",
+    upstreamPath: "/v1/text-to-speech/{voiceId}",
+    pathParams: ["voiceId"],
+    transport: "json-binary",
+    call: "textToSpeech",
+    permission: "project:read",
+    maxBodyBytes: MAX_TEXT_BYTES,
+    cost: { unit: "character", per: 1 },
+    models: VOICE_TTS_MODEL_IDS,
+    defaultModel: CONVAI_TTS_MODEL_FALLBACK,
+    defaultVoiceId: true,
+    forward: {
+      text: "text",
+      voiceId: "voice_id",
+      modelId: "model_id",
+      voiceSettings: "voice_settings"
+    },
+    required: ["text"],
+    responseHeaders: ["x-tts-model-used", "x-tts-model-requested", "warning"],
+    accept: "audio/mpeg",
+    errorLabel: "TTS failed"
+  },
+  {
+    id: "text-to-speech-with-timestamps",
+    method: "POST",
+    hostedPath: "/voice/op/text-to-speech-with-timestamps",
+    upstreamPath: "/v1/text-to-speech/{voiceId}/with-timestamps",
+    pathParams: ["voiceId"],
+    transport: "json-json",
+    permission: "project:read",
+    maxBodyBytes: MAX_TEXT_BYTES,
+    cost: { unit: "character", per: 1 },
+    models: VOICE_TTS_MODEL_IDS,
+    defaultModel: CONVAI_TTS_MODEL_FALLBACK,
+    defaultVoiceId: true,
+    forward: {
+      text: "text",
+      voiceId: "voice_id",
+      modelId: "model_id",
+      voiceSettings: "voice_settings",
+      outputFormat: "output_format"
+    },
+    required: ["text"],
+    accept: "application/json"
+  },
+  {
+    id: "speech-to-speech",
+    method: "POST",
+    hostedPath: "/voice/op/speech-to-speech",
+    upstreamPath: "/v1/speech-to-speech/{voiceId}",
+    pathParams: ["voiceId"],
+    transport: "multipart-binary",
+    permission: "project:read",
+    maxBodyBytes: MAX_AUDIO_BYTES,
+    cost: { unit: "second", per: 1 },
+    models: VOICE_STS_MODEL_IDS,
+    defaultModel: DEFAULT_STS_MODEL,
+    defaultVoiceId: true,
+    forward: {
+      audio: "audio",
+      voiceId: "voice_id",
+      modelId: "model_id",
+      voiceSettings: "voice_settings",
+      outputFormat: "output_format",
+      fileFormat: "file_format",
+      seed: "seed",
+      removeBackgroundNoise: "remove_background_noise"
+    },
+    required: ["audio"],
+    accept: "audio/mpeg"
+  },
+  {
+    id: "speech-to-text",
+    method: "POST",
+    hostedPath: "/voice/op/speech-to-text",
+    upstreamPath: "/v1/speech-to-text",
+    transport: "multipart-json",
+    permission: "project:read",
+    maxBodyBytes: MAX_AUDIO_BYTES,
+    cost: { unit: "second", per: 1 },
+    models: VOICE_SPEECH_TO_TEXT_MODEL_IDS,
+    defaultModel: DEFAULT_SPEECH_TO_TEXT_MODEL,
+    forward: {
+      file: "file",
+      modelId: "model_id",
+      languageCode: "language_code",
+      diarize: "diarize",
+      tagAudioEvents: "tag_audio_events",
+      numSpeakers: "num_speakers"
+    },
+    required: ["file"],
+    accept: "application/json"
+  },
+  {
+    id: "sound-generation",
+    method: "POST",
+    hostedPath: "/voice/op/sound-generation",
+    upstreamPath: "/v1/sound-generation",
+    transport: "json-binary",
+    permission: "project:read",
+    maxBodyBytes: MAX_JSON_BYTES,
+    cost: { unit: "second", per: 1 },
+    models: VOICE_SOUND_GENERATION_MODEL_IDS,
+    defaultModel: DEFAULT_SOUND_GENERATION_MODEL,
+    forward: {
+      text: "text",
+      durationSeconds: "duration_seconds",
+      promptInfluence: "prompt_influence",
+      loop: "loop",
+      modelId: "model_id"
+    },
+    // `output_format` is a query param on this endpoint, not a body field — the
+    // typed `soundEffects()` client sends it there, and a body field is
+    // silently ignored upstream.
+    queryForward: ["output_format"],
+    required: ["text"],
+    accept: "audio/mpeg"
+  },
+  {
+    id: "music",
+    method: "POST",
+    hostedPath: "/voice/op/music",
+    legacyHostedPath: "/voice/music",
+    upstreamPath: "/v1/music",
+    transport: "json-binary",
+    call: "composeMusic",
+    permission: "project:read",
+    maxBodyBytes: MAX_JSON_BYTES,
+    cost: { unit: "second", per: 1 },
+    models: [DEFAULT_MUSIC_MODEL],
+    defaultModel: DEFAULT_MUSIC_MODEL,
+    forward: {
+      prompt: "prompt",
+      compositionPlan: "composition_plan",
+      musicLengthMs: "music_length_ms",
+      modelId: "model_id",
+      forceInstrumental: "force_instrumental",
+      outputFormat: "output_format"
+    },
+    accept: "audio/mpeg",
+    errorLabel: "Music generation failed",
+    validate: (fields) => {
+      const hasPrompt = typeof fields.prompt === "string" && fields.prompt.trim().length > 0;
+      const hasPlan = fields.compositionPlan != null && typeof fields.compositionPlan === "object";
+      return hasPrompt === hasPlan ? "Provide exactly one of `prompt` or `compositionPlan`" : null;
+    }
+  },
+  {
+    id: "voices",
+    method: "GET",
+    hostedPath: "/voice/op/voices",
+    upstreamPath: "/v1/voices",
+    transport: "json-json",
+    permission: "project:read",
+    maxBodyBytes: 0,
+    cost: { unit: "request", per: 1 },
+    queryForward: ["page_size", "search", "voice_type", "category", "next_page_token"],
+    accept: "application/json"
+  },
+  {
+    id: "models",
+    method: "GET",
+    hostedPath: "/voice/op/models",
+    upstreamPath: "/v1/models",
+    transport: "json-json",
+    permission: "project:read",
+    maxBodyBytes: 0,
+    cost: { unit: "request", per: 1 },
+    accept: "application/json"
+  }
+];
+var VOICE_OP_IDS = VOICE_OPS.map((op) => op.id);
+function getVoiceOp(id) {
+  if (!id) return void 0;
+  return VOICE_OPS.find((op) => op.id === id);
+}
+function voiceOpForwardPath(op) {
+  return op.legacyHostedPath ?? op.hostedPath;
+}
+function voiceOpReturnsAudio(op) {
+  return op.transport === "json-binary" || op.transport === "multipart-binary";
+}
+function voiceOpUpstreamPath(op, params) {
+  let path = op.upstreamPath;
+  for (const name of op.pathParams ?? []) {
+    const value = params[name];
+    if (!value) {
+      return { error: `Missing \`${name}\` (required path parameter for ${op.id})` };
+    }
+    path = path.split(`{${name}}`).join(encodeURIComponent(value));
+  }
+  return path;
+}
+var MODEL_FIELD = "modelId";
+function parseVoiceOpJsonBody(op, raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, status: 400, error: "Invalid JSON body" };
+  }
+  const body = raw;
+  const fields = {};
+  for (const [callerField, upstreamField] of Object.entries(op.forward ?? {})) {
+    if (upstreamField && body[callerField] !== void 0) fields[callerField] = body[callerField];
+  }
+  for (const name of op.required ?? []) {
+    const value = fields[name];
+    if (value === void 0 || value === null || typeof value === "string" && !value.trim()) {
+      return { ok: false, status: 400, error: `Missing \`${name}\`` };
+    }
+  }
+  const modelCheck = checkVoiceOpModel(op, fields);
+  if ("error" in modelCheck) return { ok: false, status: 400, ...modelCheck };
+  if (op.validate) {
+    const message = op.validate(fields);
+    if (message) return { ok: false, status: 400, error: message };
+  }
+  return { ok: true, fields };
+}
+function parseVoiceOpForm(op, form) {
+  const fields = {};
+  for (const callerField of Object.keys(op.forward ?? {})) {
+    const value = form.get(callerField);
+    if (value !== null) fields[callerField] = value;
+  }
+  for (const name of op.required ?? []) {
+    const value = fields[name];
+    if (!(value instanceof Blob)) {
+      return {
+        ok: false,
+        status: 400,
+        error: `Missing \`${name}\` file part`,
+        detail: value === void 0 ? `send a multipart body with a \`${name}\` file part` : `\`${name}\` must be a file part, not a text field`
+      };
+    }
+    if (value.size === 0) {
+      return { ok: false, status: 400, error: `Empty \`${name}\` file part` };
+    }
+  }
+  const modelCheck = checkVoiceOpModel(op, fields);
+  if ("error" in modelCheck) return { ok: false, status: 400, ...modelCheck };
+  const forward = op.forward ?? {};
+  const pathParams = new Set(op.pathParams ?? []);
+  const out = new FormData();
+  for (const [callerField, upstreamField] of Object.entries(forward)) {
+    if (pathParams.has(callerField)) continue;
+    const value = fields[callerField];
+    if (value === void 0 || value === null || value === "") continue;
+    if (value instanceof Blob) {
+      const name = value instanceof File ? value.name : callerField;
+      out.set(upstreamField, value, name);
+    } else if (typeof value === "string") {
+      out.set(upstreamField, value);
+    } else {
+      out.set(upstreamField, JSON.stringify(value));
+    }
+  }
+  const modelField = forward[MODEL_FIELD];
+  if (op.defaultModel && modelField && out.get(modelField) === null) {
+    out.set(modelField, op.defaultModel);
+  }
+  return { ok: true, form: out, fields };
+}
+function voiceOpUpstreamBody(op, fields) {
+  const pathParams = new Set(op.pathParams ?? []);
+  const body = {};
+  for (const [callerField, upstreamField] of Object.entries(op.forward ?? {})) {
+    if (pathParams.has(callerField)) continue;
+    const value = fields[callerField];
+    if (value === void 0 || value === null) continue;
+    body[upstreamField] = value;
+  }
+  return body;
+}
+function voiceOpPathParams(op, fields, query) {
+  const out = {};
+  for (const name of op.pathParams ?? []) {
+    const fromBody = fields[name];
+    const value = typeof fromBody === "string" && fromBody.length > 0 ? fromBody : query.get(name);
+    if (value) out[name] = value;
+  }
+  return out;
+}
+function checkVoiceOpModel(op, fields) {
+  const requested = fields[MODEL_FIELD];
+  if (requested === void 0 || requested === null || requested === "") return { ok: true };
+  if (typeof requested !== "string") {
+    return { error: `\`${MODEL_FIELD}\` must be a string` };
+  }
+  if (op.models && !op.models.includes(requested)) {
+    return {
+      error: "unknown_model",
+      detail: `Unknown model '${requested}' for ${op.id}`,
+      allowed: op.models
+    };
+  }
+  return { ok: true };
+}
+
+// src/runtime-token.ts
+var WORKSPACE_RUNTIME_TOKEN_MESSAGE = "RUNTIME_AUTH_SECRET is the workspace runtime token; app code needs its project token (rt_v1_\u2026). Start the app through the preview (server_sync / restart), not from a workspace shell.";
+function readRuntimeAuthSecret(env = typeof process === "undefined" ? void 0 : process.env) {
+  const token = env?.RUNTIME_AUTH_SECRET;
+  if (!token) return void 0;
+  if (token.startsWith("wrt_v1_")) throw new Error(WORKSPACE_RUNTIME_TOKEN_MESSAGE);
+  return token;
+}
+
+// src/server.ts
+function json(data, status = 200, extraHeaders = {}) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json", ...extraHeaders }
+  });
+}
+async function readJson(req) {
+  try {
+    const text = await req.text();
+    if (!text) return {};
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+var NOOP_LOGGER = () => {
+};
+function parseMusicBody(raw) {
+  if (raw === null || typeof raw !== "object") return { error: "Invalid JSON body" };
+  const b = raw;
+  const hasPrompt = typeof b.prompt === "string" && b.prompt.trim().length > 0;
+  const hasPlan = b.compositionPlan != null && typeof b.compositionPlan === "object";
+  if (hasPrompt === hasPlan) {
+    return { error: "Provide exactly one of `prompt` or `compositionPlan`" };
+  }
+  const params = {};
+  if (hasPrompt) {
+    params.prompt = b.prompt.trim();
+    if (typeof b.musicLengthMs === "number") params.musicLengthMs = b.musicLengthMs;
+    if (typeof b.forceInstrumental === "boolean") params.forceInstrumental = b.forceInstrumental;
+  } else {
+    params.compositionPlan = b.compositionPlan;
+  }
+  if (typeof b.modelId === "string" && b.modelId.length > 0) params.modelId = b.modelId;
+  if (typeof b.outputFormat === "string" && b.outputFormat.length > 0) {
+    params.outputFormat = b.outputFormat;
+  }
+  return { params };
+}
+var MISSING_API_HOST_MESSAGE = "createVoiceHandlers: runtime-token proxy mode needs SHOGO_API_URL (or SHOGO_CLOUD_URL) in env; refusing to guess an API host";
+function envApiUrl() {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env.SHOGO_API_URL ?? process.env.SHOGO_CLOUD_URL;
+}
+function resolveProxyOptions(config) {
+  if (config.mode === "byo") {
+    if (config.proxy) {
+      throw new Error(
+        "createVoiceHandlers: mode 'byo' cannot be combined with an explicit proxy"
+      );
+    }
+    return null;
+  }
+  const envProxy = () => {
+    if (config.mode === "proxy" && config.apiKey) {
+      LOG_WARN_CACHE.apiKeyIgnored(config.logger);
+    }
+    if (typeof process === "undefined" || !process.env) return null;
+    const runtimeToken = readRuntimeAuthSecret();
+    const projectId = process.env.PROJECT_ID;
+    if (!runtimeToken || !projectId) return null;
+    return {
+      runtimeToken,
+      projectId,
+      // Deliberately not required here: see `resolveApiBase`. Throwing at
+      // construction made every local-only handler (400 validation, 405s,
+      // the static audio-tags catalog) unusable on a host with a token but
+      // no URL — which is exactly CI's env.
+      apiUrl: envApiUrl() ?? "",
+      ...config.fetch ? { fetch: config.fetch } : {}
+    };
+  };
+  if (config.proxy) {
+    if (!config.proxy.runtimeToken || !config.proxy.projectId || !config.proxy.apiUrl) {
+      throw new Error(
+        "createVoiceHandlers: proxy requires runtimeToken, projectId, and apiUrl"
+      );
+    }
+    if (config.apiKey) LOG_WARN_CACHE.apiKeyIgnored(config.logger);
+    return config.proxy;
+  }
+  if (config.mode === "proxy") return envProxy();
+  if (config.apiKey) return null;
+  return envProxy();
+}
+var LOG_WARN_CACHE = {
+  warned: false,
+  apiKeyIgnored(logger) {
+    if (LOG_WARN_CACHE.warned) return;
+    LOG_WARN_CACHE.warned = true;
+    (logger ?? NOOP_LOGGER)(
+      "warn",
+      'createVoiceHandlers: apiKey provided but runtime-token proxy mode is active; apiKey is ignored (pass mode: "byo" to use it)'
+    );
+  }
+};
+function resolveOpId(req, opId) {
+  if (opId) return opId;
+  try {
+    const url = new URL(req.url);
+    const fromQuery = url.searchParams.get("op");
+    if (fromQuery) return fromQuery;
+    const segments = url.pathname.split("/").filter(Boolean);
+    const last = segments[segments.length - 1];
+    if (last && segments[segments.length - 2] === "op") return last;
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function readVoiceOpBody(op, req) {
+  if (op.method === "GET") return { kind: "none" };
+  if (op.transport === "multipart-binary" || op.transport === "multipart-json") {
+    let form;
+    try {
+      form = await req.formData();
+    } catch {
+      return json({ error: "Invalid multipart body", detail: "send a multipart/form-data body" }, 400);
+    }
+    const parsed2 = parseVoiceOpForm(op, form);
+    if (!parsed2.ok) {
+      return json(
+        {
+          error: parsed2.error,
+          ...parsed2.detail ? { detail: parsed2.detail } : {},
+          ...parsed2.allowed ? { allowed: parsed2.allowed } : {}
+        },
+        parsed2.status
+      );
+    }
+    return { kind: "form", form: parsed2.form, fields: parsed2.fields };
+  }
+  const raw = await readJson(req);
+  const parsed = parseVoiceOpJsonBody(op, raw);
+  if (!parsed.ok) {
+    return json(
+      {
+        error: parsed.error,
+        ...parsed.detail ? { detail: parsed.detail } : {},
+        ...parsed.allowed ? { allowed: parsed.allowed } : {}
+      },
+      parsed.status
+    );
+  }
+  return { kind: "json", fields: parsed.fields };
+}
+function createProxyHandlers(proxy, log) {
+  const fetchImpl = proxy.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error(
+      "createVoiceHandlers proxy: global fetch is unavailable; pass proxy.fetch"
+    );
+  }
+  function resolveApiBase() {
+    const raw = proxy.apiUrl || envApiUrl();
+    if (!raw) throw new Error(MISSING_API_HOST_MESSAGE);
+    return raw.replace(/\/+$/, "");
+  }
+  function proxyUrl(base, path, forward) {
+    const tail = [`projectId=${encodeURIComponent(proxy.projectId)}`];
+    for (const [k, v] of Object.entries(forward)) {
+      if (typeof v === "string" && v.length > 0) {
+        tail.push(`${k}=${encodeURIComponent(v)}`);
+      }
+    }
+    const sep = path.includes("?") ? "&" : "?";
+    return `${base}${path}${sep}${tail.join("&")}`;
+  }
+  const FORWARDED_SIGNED_URL_PARAMS = ["agentName"];
+  async function doSignedUrl(req) {
+    if (req.method !== "GET") return json({ error: "Method Not Allowed" }, 405);
+    const base = resolveApiBase();
+    try {
+      let incomingUrl = null;
+      try {
+        incomingUrl = new URL(req.url);
+      } catch {
+      }
+      const forward = {};
+      if (incomingUrl) {
+        for (const key of FORWARDED_SIGNED_URL_PARAMS) {
+          const v = incomingUrl.searchParams.get(key);
+          if (v != null) forward[key] = v;
+        }
+      }
+      const upstream = await fetchImpl(proxyUrl(base, "/api/voice/signed-url", forward), {
+        method: "GET",
+        headers: { "x-runtime-token": proxy.runtimeToken },
+        credentials: "omit"
+      });
+      const body = await upstream.text();
+      const headers = { "content-type": "application/json" };
+      const ct = upstream.headers.get("content-type");
+      if (ct) headers["content-type"] = ct;
+      return new Response(body, { status: upstream.status, headers });
+    } catch (err) {
+      log("error", "proxy signedUrl failed", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+      return json({ error: "signedUrl proxy failed" }, 502);
+    }
+  }
+  async function doAudioTags(req) {
+    if (req.method !== "GET") return json({ error: "Method Not Allowed" }, 405);
+    return json({
+      tags: AUDIO_TAGS,
+      groups: AUDIO_TAG_GROUPS,
+      expressivity: EXPRESSIVITY_OPTIONS,
+      defaults: {
+        allowedTags: DEFAULT_ALLOWED_TAGS,
+        voiceSettings: DEFAULT_VOICE_SETTINGS,
+        ttsModelId: CONVAI_TTS_MODEL_FALLBACK
+      }
+    });
+  }
+  async function doOp(req, opId) {
+    const id = resolveOpId(req, opId);
+    const op = getVoiceOp(id);
+    if (!op) {
+      return json(
+        { error: "unknown_op", detail: `Unknown voice op '${id ?? ""}'`, allowed: VOICE_OP_IDS },
+        404
+      );
+    }
+    if (req.method !== op.method) return json({ error: "Method Not Allowed" }, 405);
+    const parsed = await readVoiceOpBody(op, req);
+    if (parsed instanceof Response) return parsed;
+    const base = resolveApiBase();
+    const forward = {};
+    let incomingUrl = null;
+    try {
+      incomingUrl = new URL(req.url);
+    } catch {
+    }
+    if (incomingUrl) {
+      for (const key of [...op.pathParams ?? [], ...op.queryForward ?? []]) {
+        const value = incomingUrl.searchParams.get(key);
+        if (value != null) forward[key] = value;
+      }
+    }
+    if (parsed.kind === "form") {
+      for (const name of op.pathParams ?? []) {
+        const value = parsed.fields[name];
+        if (typeof value === "string" && value.length > 0) forward[name] = value;
+      }
+    }
+    const hostedPath = `/api${voiceOpForwardPath(op)}`;
+    const headers = { "x-runtime-token": proxy.runtimeToken };
+    let body;
+    if (parsed.kind === "json") {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(parsed.fields);
+    } else if (parsed.kind === "form") {
+      body = parsed.form;
+    }
+    if (op.accept) headers.accept = op.accept;
+    try {
+      const upstream = await fetchImpl(proxyUrl(base, hostedPath, forward), {
+        method: op.method,
+        headers,
+        ...body !== void 0 ? { body } : {},
+        credentials: "omit"
+      });
+      if (upstream.status === 404) {
+        return json(
+          {
+            error: "Not Implemented",
+            detail: `this Shogo API has no voice routes (desktop without ELEVENLABS_API_KEY?) \u2014 ${hostedPath} returned 404 upstream`
+          },
+          501
+        );
+      }
+      const buf = await upstream.arrayBuffer();
+      const responseHeaders = {};
+      const ct = upstream.headers.get("content-type");
+      if (ct) responseHeaders["content-type"] = ct;
+      for (const name of op.responseHeaders ?? []) {
+        const value = upstream.headers.get(name);
+        if (value) responseHeaders[name] = value;
+      }
+      return new Response(buf, { status: upstream.status, headers: responseHeaders });
+    } catch (err) {
+      log("error", `proxy ${op.id} failed`, {
+        error: err instanceof Error ? err.message : String(err)
+      });
+      return json({ error: `${op.id} proxy failed` }, 502);
+    }
+  }
+  const doMusic = (req) => doOp(req, "music");
+  function notImplemented(label) {
+    return async () => json(
+      {
+        error: "Not Implemented",
+        detail: `${label} is not available in runtime-token proxy mode; use BYO-EL or the hosted bearer SDK path.`
+      },
+      501
+    );
+  }
+  async function doTts(req) {
+    if (req.method === "POST") {
+      let raw = null;
+      try {
+        const parsed = await req.clone().json();
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          raw = parsed;
+        }
+      } catch {
+      }
+      if (raw && (typeof raw.text !== "string" || raw.text.trim().length === 0)) {
+        const sentTags = Array.isArray(raw.audioTags) && raw.audioTags.length > 0;
+        if (sentTags) {
+          const tags = normalizeAudioTags(raw.audioTags) ?? [];
+          const characterName = typeof raw.characterName === "string" ? raw.characterName : void 0;
+          const text = buildPreviewLine(tags, characterName ?? "your companion");
+          return doOp(
+            new Request(req.url, {
+              method: "POST",
+              headers: { "content-type": "application/json" },
+              body: JSON.stringify({ ...raw, text })
+            }),
+            "text-to-speech"
+          );
+        }
+      }
+    }
+    return doOp(req, "text-to-speech");
+  }
+  function createProxyElevenLabs() {
+    const unsupported = (prop) => {
+      throw new Error(
+        `createVoiceHandlers: elevenLabs.${prop} is not available in runtime-token proxy mode (textToSpeech, composeMusic, speechToSpeech, soundEffects and transcribe are hosted); pass mode: 'byo' with an apiKey`
+      );
+    };
+    const textToSpeech = async (params) => {
+      const upstream = await fetchImpl(proxyUrl(resolveApiBase(), "/api/voice/tts", {}), {
+        method: "POST",
+        headers: {
+          "x-runtime-token": proxy.runtimeToken,
+          "content-type": "application/json",
+          accept: params.accept ?? "audio/mpeg"
+        },
+        body: JSON.stringify({
+          text: params.text,
+          voiceId: params.voiceId,
+          ...params.modelId ? { modelId: params.modelId } : {},
+          ...params.voiceSettings ? { voiceSettings: params.voiceSettings } : {}
+        }),
+        credentials: "omit"
+      });
+      if (upstream.status === 404) {
+        throw new Error(
+          "this Shogo API has no voice routes (desktop without ELEVENLABS_API_KEY?) \u2014 /api/voice/tts returned 404 upstream"
+        );
+      }
+      if (!upstream.ok) {
+        throw new ElevenLabsApiError(
+          `textToSpeech failed: ${upstream.status}`,
+          upstream.status,
+          await upstream.text()
+        );
+      }
+      const requestedModel = params.modelId ?? DEFAULT_TTS_MODEL;
+      const usedModel = upstream.headers.get("x-tts-model-used") ?? requestedModel;
+      const requestedHeader = upstream.headers.get("x-tts-model-requested") ?? requestedModel;
+      return {
+        audio: await upstream.arrayBuffer(),
+        modelId: usedModel,
+        requestedModel: requestedHeader,
+        fellBack: usedModel !== requestedHeader,
+        contentType: upstream.headers.get("content-type") ?? params.accept ?? "audio/mpeg"
+      };
+    };
+    const composeMusic = async (params) => {
+      const upstream = await fetchImpl(proxyUrl(resolveApiBase(), "/api/voice/music", {}), {
+        method: "POST",
+        headers: {
+          "x-runtime-token": proxy.runtimeToken,
+          "content-type": "application/json",
+          accept: "audio/mpeg"
+        },
+        body: JSON.stringify(params),
+        credentials: "omit"
+      });
+      if (upstream.status === 404) {
+        throw new Error(
+          "this Shogo API has no voice routes (desktop without ELEVENLABS_API_KEY?) \u2014 /api/voice/music returned 404 upstream"
+        );
+      }
+      if (!upstream.ok) {
+        throw new ElevenLabsApiError(
+          `composeMusic failed: ${upstream.status}`,
+          upstream.status,
+          await upstream.text()
+        );
+      }
+      return {
+        audio: await upstream.arrayBuffer(),
+        contentType: upstream.headers.get("content-type") ?? "audio/mpeg"
+      };
+    };
+    const opResponse = async (opId, req) => {
+      const op = getVoiceOp(opId);
+      const res = await doOp(req, opId);
+      if (res.status === 404) {
+        throw new Error(
+          `this Shogo API has no voice routes (desktop without ELEVENLABS_API_KEY?) \u2014 /api${voiceOpForwardPath(op)} returned 404 upstream`
+        );
+      }
+      if (!res.ok) {
+        throw new ElevenLabsApiError(
+          `${opId} failed: ${res.status}`,
+          res.status,
+          await res.text()
+        );
+      }
+      return res;
+    };
+    const opAudio = async (opId, req) => {
+      const res = await opResponse(opId, req);
+      return {
+        audio: await res.arrayBuffer(),
+        contentType: res.headers.get("content-type") ?? "audio/mpeg"
+      };
+    };
+    const speechToSpeech = (params) => {
+      const form = new FormData();
+      form.set("audio", params.audio, params.fileName ?? "audio");
+      if (params.modelId) form.set("modelId", params.modelId);
+      if (params.voiceSettings) form.set("voiceSettings", JSON.stringify(params.voiceSettings));
+      if (params.outputFormat) form.set("outputFormat", params.outputFormat);
+      if (params.fileFormat) form.set("fileFormat", params.fileFormat);
+      if (params.seed !== void 0) form.set("seed", String(params.seed));
+      if (params.removeBackgroundNoise !== void 0) {
+        form.set("removeBackgroundNoise", String(params.removeBackgroundNoise));
+      }
+      const query = `?voiceId=${encodeURIComponent(params.voiceId)}`;
+      return opAudio(
+        "speech-to-speech",
+        new Request(`http://voice.invalid/voice/op/speech-to-speech${query}`, {
+          method: "POST",
+          body: form
+        })
+      );
+    };
+    const soundEffects = (params) => opAudio(
+      "sound-generation",
+      new Request(
+        // `output_format` is a query param on this endpoint (see the row's
+        // `queryForward`); sending it in the body would be dropped at EL.
+        `http://voice.invalid/voice/op/sound-generation${params.outputFormat ? `?output_format=${encodeURIComponent(params.outputFormat)}` : ""}`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            text: params.text,
+            ...params.durationSeconds !== void 0 ? { durationSeconds: params.durationSeconds } : {},
+            ...params.promptInfluence !== void 0 ? { promptInfluence: params.promptInfluence } : {},
+            ...params.loop !== void 0 ? { loop: params.loop } : {},
+            ...params.modelId ? { modelId: params.modelId } : {}
+          })
+        }
+      )
+    );
+    const transcribe = async (params) => {
+      const form = new FormData();
+      form.set("file", params.file, params.fileName ?? "audio");
+      if (params.modelId) form.set("modelId", params.modelId);
+      if (params.languageCode) form.set("languageCode", params.languageCode);
+      if (params.diarize !== void 0) form.set("diarize", String(params.diarize));
+      if (params.tagAudioEvents !== void 0) {
+        form.set("tagAudioEvents", String(params.tagAudioEvents));
+      }
+      if (params.numSpeakers !== void 0) form.set("numSpeakers", String(params.numSpeakers));
+      const res = await opResponse(
+        "speech-to-text",
+        new Request("http://voice.invalid/voice/op/speech-to-text", {
+          method: "POST",
+          body: form
+        })
+      );
+      return await res.json();
+    };
+    return new Proxy({}, {
+      get(_t, prop) {
+        if (prop === "textToSpeech") return textToSpeech;
+        if (prop === "composeMusic") return composeMusic;
+        if (prop === "speechToSpeech") return speechToSpeech;
+        if (prop === "soundEffects") return soundEffects;
+        if (prop === "transcribe") return transcribe;
+        return unsupported(String(prop));
+      }
+    });
+  }
+  return {
+    signedUrl: doSignedUrl,
+    tts: doTts,
+    music: doMusic,
+    agent: {
+      create: notImplemented("agent.create"),
+      patch: notImplemented("agent.patch"),
+      delete: notImplemented("agent.delete")
+    },
+    audioTags: doAudioTags,
+    op: doOp,
+    // In proxy mode we don't own an EL client: media calls go through the
+    // Shogo API, anything else is a loud error.
+    elevenLabs: createProxyElevenLabs()
+  };
+}
+function createVoiceHandlers(config) {
+  const log = config.logger ?? NOOP_LOGGER;
+  const proxy = resolveProxyOptions(config);
+  if (proxy) {
+    return createProxyHandlers(proxy, log);
+  }
+  if (!config.apiKey) {
+    throw new Error(
+      config.mode === "proxy" ? 'createVoiceHandlers: mode "proxy" needs RUNTIME_AUTH_SECRET + PROJECT_ID (+ SHOGO_API_URL) in env' : "createVoiceHandlers: apiKey is required (or run in a pod with RUNTIME_AUTH_SECRET + PROJECT_ID for proxy mode)"
+    );
+  }
+  const getUser = config.getUser;
+  const companionStore = config.companionStore;
+  const includeMemoryTools = config.includeMemoryTools ?? true;
+  const tools = includeMemoryTools ? MEMORY_CLIENT_TOOLS : void 0;
+  const elConfig = {
+    apiKey: config.apiKey,
+    ...config.elevenLabsBaseUrl ? { baseUrl: config.elevenLabsBaseUrl } : {},
+    ...config.fetch ? { fetch: config.fetch } : {}
+  };
+  const el = new ElevenLabsClient(elConfig);
+  async function resolveUser(req) {
+    if (!getUser) {
+      return json(
+        {
+          error: "Voice handler misconfigured",
+          detail: "signedUrl / agent.* need getUser (and companionStore); tts and music do not."
+        },
+        500
+      );
+    }
+    const u = await getUser(req);
+    if (!u) return json({ error: "Unauthorized" }, 401);
+    return u;
+  }
+  function missingCompanionStore() {
+    return json(
+      {
+        error: "Voice handler misconfigured",
+        detail: "companionStore is required for signedUrl / agent.*; tts and music do not need it."
+      },
+      500
+    );
+  }
+  function handleElError(e, fallbackLabel) {
+    if (e instanceof ElevenLabsApiError) {
+      log("warn", `${fallbackLabel}: 11Labs ${e.status}`, { body: e.body });
+      return json({ error: fallbackLabel, detail: e.body }, 502);
+    }
+    const message = e instanceof Error ? e.message : String(e);
+    log("error", `${fallbackLabel}: ${message}`);
+    return json({ error: fallbackLabel, detail: message }, 500);
+  }
+  async function doSignedUrl(req) {
+    if (req.method !== "GET") return json({ error: "Method Not Allowed" }, 405);
+    const u = await resolveUser(req);
+    if (u instanceof Response) return u;
+    if (!companionStore) return missingCompanionStore();
+    const companion = await companionStore.findByUserId(u.id);
+    if (!companion || !companion.agentId) return json({ error: "No companion" }, 404);
+    const basePrompt = extractBasePrompt(companion.systemPrompt || "");
+    try {
+      await el.patchAgent(companion.agentId, {
+        systemPrompt: basePrompt,
+        tools,
+        enableUserContextOverride: includeMemoryTools,
+        voiceId: companion.voiceId,
+        expressivity: readExpressivity(companion.expressivity),
+        audioTags: readAudioTags(companion.audioTags),
+        voiceSettings: readVoiceSettings(companion.voiceSettings),
+        ttsModelId: companion.ttsModelId ?? null,
+        ...includeMemoryTools ? {} : { memoryBlock: null }
+      });
+      if (basePrompt !== companion.systemPrompt) {
+        await companionStore.update(u.id, { systemPrompt: basePrompt });
+      }
+    } catch (e) {
+      log("warn", "signedUrl: pre-sync patch failed; continuing", {
+        error: e instanceof Error ? e.message : String(e)
+      });
+    }
+    let signedUrl;
+    try {
+      signedUrl = await el.getSignedUrl(companion.agentId);
+    } catch (e) {
+      return handleElError(e, "Failed to get signed url");
+    }
+    let userContext = "";
+    if (config.memoryStore) {
+      try {
+        const store = config.memoryStore(u.id);
+        const hits = store.search(companion.characterName || "recent context", { limit: 5 });
+        if (hits.length) {
+          userContext = hits.map(
+            (h) => `- ${h.matchType ? `[${h.matchType}] ` : ""}${h.chunk.trim().replace(/\s+/g, " ").slice(0, 220)}`
+          ).join("\n");
+        }
+      } catch (e) {
+        log("warn", "signedUrl: memory preload failed", {
+          error: e instanceof Error ? e.message : String(e)
+        });
+      }
+    }
+    return json({ signedUrl, agentId: companion.agentId, userContext });
+  }
+  async function doTts(req) {
+    if (req.method !== "POST") return json({ error: "Method Not Allowed" }, 405);
+    if (getUser) {
+      const u = await resolveUser(req);
+      if (u instanceof Response) return u;
+    }
+    const raw = await readJson(req);
+    if (raw === null || typeof raw !== "object") return json({ error: "Invalid JSON body" }, 400);
+    const body = raw;
+    const voiceId = typeof body.voiceId === "string" ? body.voiceId.trim() : "";
+    if (!voiceId) return json({ error: "Missing voiceId" }, 400);
+    const voiceSettings = normalizeVoiceSettings(body.voiceSettings) ?? { stability: 0.5, similarity_boost: 0.8, style: 0 };
+    let text;
+    if (typeof body.text === "string" && body.text.trim().length > 0) {
+      text = body.text.slice(0, 400);
+    } else {
+      const tags = normalizeAudioTags(body.audioTags) ?? [];
+      text = buildPreviewLine(tags, body.characterName ?? "your companion").slice(0, 400);
+    }
+    try {
+      const result = await el.textToSpeech({
+        voiceId,
+        text,
+        ...body.modelId ? { modelId: body.modelId } : {},
+        voiceSettings
+      });
+      const headers = {
+        "content-type": result.contentType,
+        "cache-control": "private, max-age=3600",
+        "x-tts-model-used": result.modelId,
+        "x-tts-model-requested": result.requestedModel
+      };
+      if (result.fellBack) {
+        headers.warning = `199 - "model ${result.requestedModel} not available, used ${result.modelId}"`;
+        log("warn", "tts fell back to another model", {
+          requested: result.requestedModel,
+          used: result.modelId,
+          reason: result.fallbackReason
+        });
+      }
+      return new Response(result.audio, { headers });
+    } catch (e) {
+      return handleElError(e, "TTS failed");
+    }
+  }
+  async function doMusic(req) {
+    if (req.method !== "POST") return json({ error: "Method Not Allowed" }, 405);
+    if (getUser) {
+      const u = await resolveUser(req);
+      if (u instanceof Response) return u;
+    }
+    const raw = await readJson(req);
+    const parsed = parseMusicBody(raw);
+    if ("error" in parsed) return json({ error: parsed.error }, 400);
+    try {
+      const { audio, contentType } = await el.composeMusic(parsed.params);
+      return new Response(audio, {
+        headers: {
+          "content-type": contentType,
+          "cache-control": "private, max-age=3600"
+        }
+      });
+    } catch (e) {
+      return handleElError(e, "Music generation failed");
+    }
+  }
+  async function doOp(req, opId) {
+    const id = resolveOpId(req, opId);
+    const op = getVoiceOp(id);
+    if (!op) {
+      return json(
+        { error: "unknown_op", detail: `Unknown voice op '${id ?? ""}'`, allowed: VOICE_OP_IDS },
+        404
+      );
+    }
+    if (req.method !== op.method) return json({ error: "Method Not Allowed" }, 405);
+    const parsed = await readVoiceOpBody(op, req);
+    if (parsed instanceof Response) return parsed;
+    const fields = parsed.kind === "none" ? {} : parsed.fields;
+    let query;
+    try {
+      query = new URL(req.url).searchParams;
+    } catch {
+      query = new URLSearchParams();
+    }
+    const pathParams = voiceOpPathParams(op, fields, query);
+    const upstream = voiceOpUpstreamPath(op, pathParams);
+    if (typeof upstream !== "string") {
+      return json({ error: upstream.error, detail: `set it in the body or as ?${op.pathParams?.[0]}=` }, 400);
+    }
+    const forwardedQuery = {};
+    for (const key of op.queryForward ?? []) {
+      const value = query.get(key);
+      if (value) forwardedQuery[key] = value;
+    }
+    if (op.defaultVoiceId && !pathParams.voiceId) {
+      return json(
+        {
+          error: "Missing `voiceId`",
+          detail: `BYO mode has no project default voice \u2014 pass voiceId (or ?voiceId=)`
+        },
+        400
+      );
+    }
+    try {
+      if (op.call === "textToSpeech") {
+        const result = await el.textToSpeech({
+          voiceId: pathParams.voiceId ?? String(fields.voiceId ?? ""),
+          text: String(fields.text ?? ""),
+          ...typeof fields.modelId === "string" ? { modelId: fields.modelId } : {},
+          ...fields.voiceSettings ? { voiceSettings: fields.voiceSettings } : {},
+          ...op.accept ? { accept: op.accept } : {}
+        });
+        const headers2 = {
+          "content-type": result.contentType,
+          "cache-control": "private, max-age=3600",
+          "x-tts-model-used": result.modelId,
+          "x-tts-model-requested": result.requestedModel
+        };
+        if (result.fellBack) {
+          headers2.warning = `199 - "model ${result.requestedModel} not available, used ${result.modelId}"`;
+        }
+        return new Response(result.audio, { headers: headers2 });
+      }
+      if (op.call === "composeMusic") {
+        const { audio, contentType } = await el.composeMusic({
+          ...typeof fields.prompt === "string" ? { prompt: fields.prompt } : {},
+          ...fields.compositionPlan ? { compositionPlan: fields.compositionPlan } : {},
+          ...typeof fields.musicLengthMs === "number" ? { musicLengthMs: fields.musicLengthMs } : {},
+          ...typeof fields.modelId === "string" ? { modelId: fields.modelId } : {},
+          ...typeof fields.forceInstrumental === "boolean" ? { forceInstrumental: fields.forceInstrumental } : {},
+          ...typeof fields.outputFormat === "string" ? { outputFormat: fields.outputFormat } : {}
+        });
+        return new Response(audio, {
+          headers: {
+            "content-type": contentType,
+            "cache-control": "private, max-age=3600"
+          }
+        });
+      }
+      const upstreamBody = voiceOpUpstreamBody(op, fields);
+      if (op.defaultModel && upstreamBody.model_id === void 0) {
+        upstreamBody.model_id = op.defaultModel;
+      }
+      const response = await el.request({
+        method: op.method,
+        path: upstream,
+        ...parsed.kind === "form" ? { body: parsed.form } : parsed.kind === "json" ? { body: upstreamBody } : {},
+        ...Object.keys(forwardedQuery).length ? { query: forwardedQuery } : {},
+        ...op.accept ? { accept: op.accept } : {}
+      });
+      const headers = { "content-type": response.contentType };
+      if (voiceOpReturnsAudio(op)) headers["cache-control"] = "private, max-age=3600";
+      const body = response.audio ?? JSON.stringify(response.json ?? {});
+      return new Response(body, { status: response.status, headers });
+    } catch (e) {
+      return handleElError(e, `${op.id} failed`);
+    }
+  }
+  async function doAgentCreate(req) {
+    if (req.method !== "POST") return json({ error: "Method Not Allowed" }, 405);
+    const u = await resolveUser(req);
+    if (u instanceof Response) return u;
+    if (!companionStore) return missingCompanionStore();
+    const existing = await companionStore.findByUserId(u.id);
+    if (existing) return json({ error: "Companion already exists" }, 409);
+    const raw = await readJson(req);
+    if (raw === null || typeof raw !== "object") return json({ error: "Invalid JSON body" }, 400);
+    const body = raw;
+    if (typeof body.displayName !== "string" || typeof body.characterName !== "string" || typeof body.voiceId !== "string" || typeof body.systemPrompt !== "string" || typeof body.firstMessage !== "string") {
+      return json({ error: "Missing required fields" }, 400);
+    }
+    const expressivity = readExpressivity(body.expressivity);
+    const audioTags = readAudioTags(body.audioTags);
+    const voiceSettings = readVoiceSettings(body.voiceSettings);
+    const ttsModelId = resolveConvaiTtsModel(body.ttsModelId);
+    let agentId;
+    try {
+      agentId = await el.createAgent({
+        displayName: body.displayName,
+        characterName: body.characterName,
+        voiceId: body.voiceId,
+        systemPrompt: body.systemPrompt,
+        firstMessage: body.firstMessage,
+        expressivity,
+        audioTags,
+        voiceSettings,
+        ttsModelId,
+        ...tools ? { tools } : {},
+        ...includeMemoryTools ? {} : { memoryBlock: null }
+      });
+    } catch (e) {
+      return handleElError(e, "Failed to create agent");
+    }
+    const cleanedPrompt = extractBasePrompt(body.systemPrompt);
+    const companion = await companionStore.create({
+      userId: u.id,
+      agentId,
+      displayName: body.displayName,
+      characterName: body.characterName,
+      voiceId: body.voiceId,
+      systemPrompt: cleanedPrompt,
+      firstMessage: body.firstMessage,
+      expressivity,
+      audioTags,
+      voiceSettings,
+      ttsModelId
+    });
+    return json(companion);
+  }
+  async function doAgentPatch(req) {
+    if (req.method !== "PATCH") return json({ error: "Method Not Allowed" }, 405);
+    const u = await resolveUser(req);
+    if (u instanceof Response) return u;
+    if (!companionStore) return missingCompanionStore();
+    const existing = await companionStore.findByUserId(u.id);
+    if (!existing) return json({ error: "No companion" }, 404);
+    const raw = await readJson(req);
+    if (raw === null || typeof raw !== "object") return json({ error: "Invalid JSON body" }, 400);
+    const body = raw;
+    const patch = {};
+    if (body.displayName !== void 0) patch.displayName = body.displayName;
+    if (body.characterName !== void 0) patch.characterName = body.characterName;
+    if (body.voiceId !== void 0) patch.voiceId = body.voiceId;
+    if (body.firstMessage !== void 0) patch.firstMessage = body.firstMessage;
+    const expressivity = normalizeExpressivity(body.expressivity);
+    if (expressivity !== void 0) patch.expressivity = expressivity;
+    let audioTagsPatch;
+    if (body.audioTags !== void 0) {
+      audioTagsPatch = normalizeAudioTags(body.audioTags) ?? [];
+      patch.audioTags = audioTagsPatch;
+    }
+    if (body.voiceSettings !== void 0) {
+      const vs = normalizeVoiceSettings(body.voiceSettings);
+      patch.voiceSettings = vs ?? null;
+    }
+    if (body.ttsModelId !== void 0) patch.ttsModelId = body.ttsModelId ?? null;
+    const cleanedPrompt = body.systemPrompt !== void 0 ? extractBasePrompt(body.systemPrompt) : void 0;
+    if (cleanedPrompt !== void 0) patch.systemPrompt = cleanedPrompt;
+    const needs11Labs = body.displayName !== void 0 || body.characterName !== void 0 || body.voiceId !== void 0 || body.systemPrompt !== void 0 || body.firstMessage !== void 0 || body.expressivity !== void 0 || body.audioTags !== void 0 || body.voiceSettings !== void 0 || body.ttsModelId !== void 0;
+    if (existing.agentId && needs11Labs) {
+      const finalExpressivity = patch.expressivity ?? readExpressivity(existing.expressivity);
+      const finalTags = audioTagsPatch !== void 0 ? audioTagsPatch : readAudioTags(existing.audioTags);
+      const finalVoiceSettings = body.voiceSettings !== void 0 ? normalizeVoiceSettings(body.voiceSettings) ?? void 0 : readVoiceSettings(existing.voiceSettings);
+      const finalTtsModelId = body.ttsModelId !== void 0 ? body.ttsModelId ?? null : existing.ttsModelId ?? null;
+      try {
+        await el.patchAgent(existing.agentId, {
+          ...body.displayName !== void 0 ? { displayName: body.displayName } : {},
+          ...body.characterName !== void 0 ? { characterName: body.characterName } : {},
+          ...body.voiceId !== void 0 ? { voiceId: body.voiceId } : {},
+          systemPrompt: cleanedPrompt !== void 0 ? cleanedPrompt : body.expressivity !== void 0 || body.audioTags !== void 0 ? existing.systemPrompt : void 0,
+          ...body.firstMessage !== void 0 ? { firstMessage: body.firstMessage } : {},
+          expressivity: finalExpressivity,
+          audioTags: finalTags,
+          ...finalVoiceSettings ? { voiceSettings: finalVoiceSettings } : {},
+          ttsModelId: finalTtsModelId,
+          ...includeMemoryTools ? {} : { memoryBlock: null }
+        });
+      } catch (e) {
+        return handleElError(e, "Failed to patch agent");
+      }
+    }
+    const companion = await companionStore.update(u.id, patch);
+    return json(companion);
+  }
+  async function doAgentDelete(req) {
+    if (req.method !== "DELETE") return json({ error: "Method Not Allowed" }, 405);
+    const u = await resolveUser(req);
+    if (u instanceof Response) return u;
+    if (!companionStore) return missingCompanionStore();
+    const existing = await companionStore.findByUserId(u.id);
+    if (!existing) return json({ ok: true });
+    if (existing.agentId) await el.deleteAgent(existing.agentId);
+    await companionStore.delete(u.id);
+    return json({ ok: true });
+  }
+  async function doAudioTags(req) {
+    if (req.method !== "GET") return json({ error: "Method Not Allowed" }, 405);
+    return json({
+      tags: AUDIO_TAGS,
+      groups: AUDIO_TAG_GROUPS,
+      expressivity: EXPRESSIVITY_OPTIONS,
+      defaults: {
+        allowedTags: DEFAULT_ALLOWED_TAGS,
+        voiceSettings: DEFAULT_VOICE_SETTINGS,
+        ttsModelId: CONVAI_TTS_MODEL_FALLBACK
+      }
+    });
+  }
+  return {
+    signedUrl: doSignedUrl,
+    tts: doTts,
+    music: doMusic,
+    agent: {
+      create: doAgentCreate,
+      patch: doAgentPatch,
+      delete: doAgentDelete
+    },
+    audioTags: doAudioTags,
+    op: doOp,
+    elevenLabs: el
+  };
+}
+
+// src/route/index.ts
+function defaultHandlers() {
+  return createVoiceHandlers({});
+}
+
+// src/route/op.ts
+var GET = (req) => defaultHandlers().op(req);
+var POST = (req) => defaultHandlers().op(req);
+var voiceOpRoutes = Object.fromEntries(
+  VOICE_OPS.map((op) => [
+    op.id,
+    {
+      GET: (req) => defaultHandlers().op(req, op.id),
+      POST: (req) => defaultHandlers().op(req, op.id)
+    }
+  ])
+);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GET,
+  POST,
+  voiceOpRoutes
+});
+//# sourceMappingURL=op.cjs.map