@shogo-ai/voice 1.10.0 → 2.4.1

package/dist/route/index.cjs

@@ -192,19 +192,74 @@ function composeAgentPrompt(basePrompt, options = {}) {
 
 // src/elevenlabs.ts
 var DEFAULT_ELEVENLABS_BASE_URL = "https://api.elevenlabs.io";
-var CONVAI_SUPPORTED_TTS_MODELS = /* @__PURE__ */ new Set([
-  "eleven_turbo_v2",
-  "eleven_turbo_v2_5",
-  "eleven_flash_v2",
-  "eleven_flash_v2_5",
-  "eleven_multilingual_v2"
-]);
-var CONVAI_TTS_MODEL_FALLBACK = "eleven_turbo_v2_5";
+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) {
-  if (requested && CONVAI_SUPPORTED_TTS_MODELS.has(requested)) return requested;
-  return CONVAI_TTS_MODEL_FALLBACK;
+  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);
@@ -369,12 +424,18 @@ var ElevenLabsClient = class {
     return data.signed_url;
   }
   /**
-   * One-shot TTS. Returns the raw audio bytes plus the model id that was
-   * actually used (some models aren't available for every account, so we
-   * fall back to `eleven_turbo_v2_5` on the first failure).
+   * 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 modelId = params.modelId && params.modelId.length > 0 ? params.modelId : "eleven_v3";
+    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(
@@ -391,19 +452,39 @@ var ElevenLabsClient = class {
       );
       return res2;
     };
-    let res = await attempt(modelId);
-    let used = modelId;
-    if (!res.ok && modelId !== "eleven_turbo_v2_5") {
-      res = await attempt("eleven_turbo_v2_5");
-      used = "eleven_turbo_v2_5";
-    }
+    let res = await attempt(requestedModel);
+    let used = requestedModel;
+    let fellBack = false;
+    let fallbackReason;
     if (!res.ok) {
-      const text = await res.text();
-      throw new ElevenLabsApiError(`textToSpeech failed: ${res.status}`, res.status, text);
+      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, contentType };
+    return {
+      audio,
+      modelId: used,
+      requestedModel,
+      fellBack,
+      ...fallbackReason ? { fallbackReason } : {},
+      contentType
+    };
   }
   /**
    * Low-level escape hatch for any ElevenLabs endpoint not covered by a
@@ -509,6 +590,119 @@ var ElevenLabsClient = class {
     }
     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(
@@ -672,6 +866,312 @@ var MEMORY_CLIENT_TOOLS = [
   }
 ];
 
+// 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/server.ts
 function json(data, status = 200, extraHeaders = {}) {
   return new Response(JSON.stringify(data), {
@@ -712,26 +1212,112 @@ function parseMusicBody(raw) {
   }
   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 = process.env.RUNTIME_AUTH_SECRET;
+    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 (typeof process === "undefined" || !process.env) return null;
-  const runtimeToken = process.env.RUNTIME_AUTH_SECRET;
-  const projectId = process.env.PROJECT_ID;
-  if (!runtimeToken || !projectId) return null;
-  const apiUrl = process.env.SHOGO_API_URL ?? process.env.SHOGO_CLOUD_URL ?? "http://localhost:8002";
-  return {
-    runtimeToken,
-    projectId,
-    apiUrl,
-    ...config.fetch ? { fetch: config.fetch } : {}
-  };
+  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;
@@ -740,8 +1326,12 @@ function createProxyHandlers(proxy, log) {
       "createVoiceHandlers proxy: global fetch is unavailable; pass proxy.fetch"
     );
   }
-  const apiBase = proxy.apiUrl.replace(/\/+$/, "");
-  function proxyUrl(path, forward) {
+  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) {
@@ -749,11 +1339,12 @@ function createProxyHandlers(proxy, log) {
       }
     }
     const sep = path.includes("?") ? "&" : "?";
-    return `${apiBase}${path}${sep}${tail.join("&")}`;
+    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 {
@@ -767,7 +1358,7 @@ function createProxyHandlers(proxy, log) {
           if (v != null) forward[key] = v;
         }
       }
-      const upstream = await fetchImpl(proxyUrl("/api/voice/signed-url", forward), {
+      const upstream = await fetchImpl(proxyUrl(base, "/api/voice/signed-url", forward), {
         method: "GET",
         headers: { "x-runtime-token": proxy.runtimeToken },
         credentials: "omit"
@@ -797,34 +1388,80 @@ function createProxyHandlers(proxy, log) {
       }
     });
   }
-  async function doMusic(req) {
-    if (req.method !== "POST") return json({ error: "Method Not Allowed" }, 405);
-    const raw = await readJson(req);
-    const parsed = parseMusicBody(raw);
-    if ("error" in parsed) return json({ error: parsed.error }, 400);
+  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 {
-      const upstream = await fetchImpl(proxyUrl("/api/voice/music", {}), {
-        method: "POST",
-        headers: {
-          "x-runtime-token": proxy.runtimeToken,
-          "content-type": "application/json",
-          accept: "audio/mpeg"
-        },
-        body: JSON.stringify(parsed.params),
+      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 headers = {};
+      const responseHeaders = {};
       const ct = upstream.headers.get("content-type");
-      if (ct) headers["content-type"] = ct;
-      return new Response(buf, { status: upstream.status, headers });
+      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 music failed", {
+      log("error", `proxy ${op.id} failed`, {
         error: err instanceof Error ? err.message : String(err)
       });
-      return json({ error: "music proxy failed" }, 502);
+      return json({ error: `${op.id} proxy failed` }, 502);
     }
   }
+  const doMusic = (req) => doOp(req, "music");
   function notImplemented(label) {
     return async () => json(
       {
@@ -834,9 +1471,204 @@ function createProxyHandlers(proxy, log) {
       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: notImplemented("tts"),
+    tts: doTts,
     music: doMusic,
     agent: {
       create: notImplemented("agent.create"),
@@ -844,30 +1676,23 @@ function createProxyHandlers(proxy, log) {
       delete: notImplemented("agent.delete")
     },
     audioTags: doAudioTags,
-    // In proxy mode we don't own an EL client. Expose a throwing stub so
-    // accidental use is loud instead of silently passing around a
-    // half-configured client.
-    elevenLabs: new Proxy({}, {
-      get(_t, prop) {
-        throw new Error(
-          `createVoiceHandlers: elevenLabs.${String(prop)} is not available in runtime-token proxy mode`
-        );
-      }
-    })
+    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) {
-    if (config.apiKey) {
-      log("warn", "createVoiceHandlers: apiKey provided but runtime-token proxy mode is active; apiKey is ignored");
-    }
     return createProxyHandlers(proxy, log);
   }
-  if (!config.apiKey) throw new Error("createVoiceHandlers: apiKey is required");
-  if (!config.getUser) throw new Error("createVoiceHandlers: getUser is required");
-  if (!config.companionStore) throw new Error("createVoiceHandlers: companionStore is required");
+  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;
@@ -879,10 +1704,28 @@ function createVoiceHandlers(config) {
   };
   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 });
@@ -896,6 +1739,7 @@ function createVoiceHandlers(config) {
     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 || "");
@@ -945,8 +1789,10 @@ function createVoiceHandlers(config) {
   }
   async function doTts(req) {
     if (req.method !== "POST") return json({ error: "Method Not Allowed" }, 405);
-    const u = await resolveUser(req);
-    if (u instanceof Response) return u;
+    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;
@@ -961,27 +1807,37 @@ function createVoiceHandlers(config) {
       text = buildPreviewLine(tags, body.characterName ?? "your companion").slice(0, 400);
     }
     try {
-      const { audio, modelId, contentType } = await el.textToSpeech({
+      const result = await el.textToSpeech({
         voiceId,
         text,
         ...body.modelId ? { modelId: body.modelId } : {},
         voiceSettings
       });
-      return new Response(audio, {
-        headers: {
-          "content-type": contentType,
-          "cache-control": "private, max-age=3600",
-          "x-tts-model-used": modelId
-        }
-      });
+      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);
-    const u = await resolveUser(req);
-    if (u instanceof Response) return u;
+    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);
@@ -997,10 +1853,104 @@ function createVoiceHandlers(config) {
       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);
@@ -1051,6 +2001,7 @@ function createVoiceHandlers(config) {
     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);
@@ -1105,6 +2056,7 @@ function createVoiceHandlers(config) {
     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);
@@ -1134,6 +2086,7 @@ function createVoiceHandlers(config) {
       delete: doAgentDelete
     },
     audioTags: doAudioTags,
+    op: doOp,
     elevenLabs: el
   };
 }
@@ -1148,6 +2101,10 @@ function createVoiceRoute(config) {
     signedUrl: { GET: (req) => v.signedUrl(req) },
     ttsPreview: { POST: (req) => v.tts(req) },
     music: { POST: (req) => v.music(req) },
+    op: {
+      GET: (req, opId) => v.op(req, opId),
+      POST: (req, opId) => v.op(req, opId)
+    },
     agent: {
       POST: (req) => v.agent.create(req),
       PATCH: (req) => v.agent.patch(req),