HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
feat(media): music can be made at last, and a line of speech is read rather than answered
richard-epsillaa206d2b8f9c0
diff --git a/gateway/app.py b/gateway/app.pyindex 3e72294c..2ba85f13 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -7587,7 +7587,7 @@ def _media_client() -> httpx.AsyncClient:async def _media_providers() -> dict[str, dict]:- """{provider: {api_key, base_url}} for every catalog provider this deployment can reach.+ """{provider: {api_key, base_url, auth}} for every catalog provider this deployment can reach.Read HERE, at the moment of use, from the integrations document — the same document the modelbroker reads. The key is returned to this process and to nothing else: it is never written into@@ -7607,7 +7607,10 @@ async def _media_providers() -> dict[str, dict]:base = str(cfg.get("base_url") or (pmeta or {}).get("base_url") or "").rstrip("/")if not base:continue- out[pname] = {"api_key": key, "base_url": base}+ # `auth` travels with the key, from the same entry that says where to send it. The+ # call site then has one thing to hold and no reason to ask which provider this is.+ out[pname] = {"api_key": key, "base_url": base,+ "auth": (pmeta or {}).get("auth")}# The one place the key is resolved is the one place that can say what must never be# relayed back. Every provider sentence this process produces is scrubbed of it —# a 401 quotes the key it rejected, and that sentence reaches an agent, a vertex and@@ -7632,11 +7635,13 @@ class _MediaNoModel(Exception):self.text, self.attempts, self.billed_usd = text, attempts, billed_usd-def _media_json(body: bytes):- try:- return json.loads(body or b"{}")- except Exception: # noqa: BLE001- return None+def _media_doc(r: httpx.Response, body: bytes):+ """One provider response, classified before it is read — the document, or the media itself.++ The classification is `media_plane.response_doc`, beside the readers that consume it, because+ "what did the provider send" and "what does it mean" are one question asked twice otherwise.+ """+ return media_plane.response_doc(r.headers.get("content-type", ""), body)# How many times ONE REQUEST may fall down its chain after a candidate has already billed. One.@@ -7831,7 +7836,12 @@ async def _media_call(cand: dict, prov: dict, params: dict,each kind of failure MEANS is `_media_unusable`'s job."""sub = media_plane.build_submit(cand, prov["base_url"], params)- headers = {"authorization": f"Bearer {prov['api_key']}", "content-type": "application/json"}+ # SIGNED IN THIS PROVIDER'S OWN STYLE, and the style came off the provider entry beside its+ # base url — see media_plane.auth_of. There is no branch here on WHICH provider this is, and+ # that is deliberate: this function is the one place every outbound submit passes through, and+ # everything it has learnt to special-case has cost a round of the budget bug. It builds one+ # header out of one dict; a provider with a third auth style is a catalog edit.+ headers = {**media_plane.auth_headers(prov), "content-type": "application/json"}cl = _media_client()stopped = budget.claim()if stopped:@@ -7845,13 +7855,14 @@ async def _media_call(cand: dict, prov: dict, params: dict,timeout=sub.timeout) as r:if r.status_code >= 400:raise media_plane.MediaRefused(- media_plane.provider_message(_media_json(await r.aread()), r.status_code))+ media_plane.provider_message(_media_doc(r, await r.aread()),+ r.status_code))async for line in r.aiter_lines():chunks.append(line)return "", media_plane.read_stream_audio(cand, chunks), {}r = await cl.request(sub.method, sub.url, json=sub.body, headers=headers,timeout=sub.timeout)- doc = _media_json(r.content)+ doc = _media_doc(r, r.content)task_id, payload = media_plane.read_submit(cand, r.status_code, doc)except HTTPException:raise@@ -8402,10 +8413,10 @@ async def _media_job_poll(job: dict, budget: _MediaBudget) -> dict:method, url = media_plane.build_poll(cand, prov["base_url"], str(job["provider_task_id"]))try:r = await _media_client().request(- method, url, headers={"authorization": f"Bearer {prov['api_key']}"},+ method, url, headers=media_plane.auth_headers(prov),timeout=media_plane.POLL_TIMEOUT_S)status, payload, err, progress = media_plane.read_poll(cand, r.status_code,- _media_json(r.content))+ _media_doc(r, r.content))except Exception: # noqa: BLE001 — a poll that did not answer is unknown, never failedstatus, payload, err, progress = "unknown", None, "", ""@@ -8797,11 +8808,17 @@ _MEDIA_MCP_TOOLS = ["shot": {"type": "string", "maxLength": 60}}}},{"name": "generate_speech",- "description": ("Speak a line. The models available here ANSWER a prompt rather than reading "- "it, so check_jobs returns what was actually said."),+ "description": ("Speak a line. The result names the model and the voice that read it — and "+ "if the model that ran answers prompts instead of reading them, it says so "+ "and returns what was actually said."),"inputSchema": {"type": "object", "required": ["text"], "additionalProperties": False,"properties": {"text": {"type": "string", "maxLength": 4000},- "voice": {"type": "string", "default": "alloy"},+ "voice": {"type": "string",+ "description": ("A voice name from "+ "list_capabilities. Leave it out "+ "and the model that runs uses its "+ "own default; naming one picks the "+ "model that has it.")},"shot": {"type": "string", "maxLength": 60}}}},{"name": "generate_music",@@ -9106,10 +9123,18 @@ async def _media_tool_call(name: str, args: dict, hid: str, sid: str, org: str,params["seconds"] = float(args["seconds"])cap = "text_to_music"else:- text = str(args.get("text") or "")- params = {"prompt": ("Read this aloud exactly as written, and say nothing else: "- + text),- "voice": str(args.get("voice") or "alloy"), "text": text}+ # THE LINE, AS ASKED FOR. What each model has to be TOLD to make it read that line is+ # the model's own business and is applied per candidate in `build_submit` — this used+ # to wrap it in "Read this aloud exactly as written…" here, before any model had been+ # chosen, which is an instruction about gpt-audio handed to whatever ran. A real+ # reader reads it out.+ params = {"prompt": str(args.get("text") or "")}+ if args.get("voice"):+ # ONLY WHEN THE CALLER NAMED ONE. A default written here would be one provider's+ # voice name applied to every provider — `alloy` was, and it skipped the model+ # that reads on every call that named no voice, because it has no voice by that+ # name and `can_serve` correctly said so.+ params["voice"] = str(args["voice"])cap = "text_to_speech"if args.get("from_image"):try:@@ -9174,13 +9199,24 @@ async def _media_tool_call(name: str, args: dict, hid: str, sid: str, org: str,if job.get("media_id"):out["media_id"] = job["media_id"]if name == "generate_speech":- out["warning"] = ("This model answers prompts rather than reading them. check_jobs "- "returns spoken_text — compare it with what you asked for before "- "you use the audio.")+ # THE VOICE THAT WAS ACTUALLY SENT, on the same footing as the model — computed by the+ # one function the submit is built from, so the two cannot disagree. Absent where the+ # model has no voices to be told about.+ told = media_plane.voice_for(cand, params)+ if told:+ out["voice"] = told+ if cand.get("answers_prompts"):+ # ABOUT THE MODEL THAT RAN, not about the capability. This sentence used to be on+ # every result, including the ones from a model that reads what it is given —+ # where it is a warning about a defect the caller does not have, and an+ # instruction to compare a transcript that does not exist.+ out["warning"] = ("This model answers prompts rather than reading them. check_jobs "+ "returns spoken_text — compare it with what you asked for before "+ "you use the audio.")if job.get("spoken_text"):out["spoken_text"] = job["spoken_text"]out["verbatim"] = media_plane.levenshtein_ratio(- params.get("text") or "", str(job["spoken_text"])) >= 0.9+ params.get("prompt") or "", str(job["spoken_text"])) >= 0.9if notes:out["note"] = " ".join(notes)return _media_json_text(out)@@ -9225,7 +9261,7 @@ async def _media_tool_call(name: str, args: dict, hid: str, sid: str, org: str,if job.get("spoken_text"):row["spoken_text"] = job["spoken_text"]row["verbatim"] = media_plane.levenshtein_ratio(- (job.get("params") or {}).get("text") or "",+ (job.get("params") or {}).get("prompt") or "",str(job["spoken_text"])) >= 0.9elif job.get("status") == "failed":row["error"] = job.get("error") or "the render failed"diff --git a/gateway/media_catalog.json b/gateway/media_catalog.jsonindex 3ca12707..2b8bdb75 100644--- a/gateway/media_catalog.json+++ b/gateway/media_catalog.json@@ -9,9 +9,18 @@"run to learn it. A correction and a first measurement are not the same kind of fact, and the","difference has to survive in the file or the next person cannot tell which they are reading."],+ "$auth": [+ "`auth` says how a provider is signed, beside the url that says where to send it — the same",+ "kind of fact, learnt in the same measurement. Absent means `authorization: Bearer <key>`, and",+ "both entries below state theirs anyway: a provider that omits it should be a provider nobody",+ "had to think about, not one whose style was never checked. `prefix` of \"\" means the key bare.",+ "Measured 2026-08-15: api.elevenlabs.io answers 401 to a bearer and 200 to xi-api-key."+ ],"providers": {- "tokenrouter": { "integration_provider": "tokenrouter", "base_url": "https://api.tokenrouter.com/v1" },- "elevenlabs": { "integration_provider": "elevenlabs", "base_url": "https://api.elevenlabs.io/v1" }+ "tokenrouter": { "integration_provider": "tokenrouter", "base_url": "https://api.tokenrouter.com/v1",+ "auth": { "header": "authorization", "prefix": "Bearer " } },+ "elevenlabs": { "integration_provider": "elevenlabs", "base_url": "https://api.elevenlabs.io",+ "auth": { "header": "xi-api-key", "prefix": "" } }},"capabilities": {@@ -180,15 +189,37 @@"text_to_speech": {"unit": "line",- "$warning": "These are CONVERSATIONAL models: they ANSWER the prompt rather than reading it. 'Say: hello.' returned 'Hello! It's great to talk with you.' No SSML, no voice cloning, no word timing.",+ "$order": "A READER FIRST, then the two that answer. The gpt-audio pair are conversational models doing narration: 'Say: hello.' returned 'Hello! It's great to talk with you.' They stay in the chain because they are a real fallback for a line of speech, and they carry `answers_prompts` so the code sends them the read-aloud instruction they need and warns the agent about the one defect they have. Ranking them first was never a preference — it was the only option there was. Neither does SSML, voice cloning or word timing.","candidates": [+ { "model": "eleven_multilingual_v2", "provider": "elevenlabs", "shape": "elevenlabs-speech",+ "params": ["prompt", "voice"], "in": ["text"], "out": ["audio"],+ "format": "mp3", "output_mime": "audio/mpeg", "latency_s": 1.88,+ "default_voice": "George",+ "$voices": "The account's own library, read from GET /v1/voices on 2026-08-15 — 22 voices, keyed by the short name a caller would say and mapped to the id the URL carries. The provider's `name` field also carries a descriptor ('George - Warm, Captivating Storyteller'); the descriptor is characterisation, not identity, and a name with a trailing space in it is not something to make an agent type. `default_voice` is George because that descriptor names the job this tool does; it is a choice, written down here so it can be argued with rather than discovered.",+ "voices": {+ "Roger": "CwhRBWXzGAHq8TQ4Fs17", "Sarah": "EXAVITQu4vr4xnSDxMaL",+ "Laura": "FGY2WhTYpPnrIDTdsKH5", "Charlie": "IKne3meq5aSn9XLyUdCD",+ "George": "JBFqnCBsd6RMkjVDRZzb", "Callum": "N2lVS1w4EtoT3dr4eOWO",+ "River": "SAz9YHcvj6GT2YYXdXww", "Harry": "SOYHLrjzK2X1ezoPC6cr",+ "Liam": "TX3LPaxmHKxFdv7VOQHJ", "Alice": "Xb7hH8MSUJpSbSDYk0k2",+ "Matilda": "XrExE9yKIg1WjnnlVkGX", "Will": "bIHbv24MWmeRgasZH58o",+ "Jessica": "cgSgspJ2msm6clMCkdW9", "Eric": "cjVigY5qzO86Huf0OWal",+ "Bella": "hpp4J3VqNfWAUOO0d1Us", "Chris": "iP95p4xoKVk53GoZ742B",+ "Brian": "nPczCjzI2devNBz1zQrb", "Daniel": "onwK4e9ZLuTAKqWW03F9",+ "Lily": "pFZP5JQG7iQjIQuC4Bku", "Adam": "pNInz6obpgDQGcFmaJgB",+ "Bill": "pqHfZKP75CvOlQylNhV4", "Anna Su": "9lHjugDhwqoxA5MhX0az" },+ "note": "Reads what it is given, verbatim, and returns no transcript — there is nothing to compare, because nothing was paraphrased. `model_id` is this entry's own name; the VOICE is the path segment. It is NOT marked answers_prompts, which is the whole reason it is ranked above the two below.",+ "measured": "e2e run 2026-08-15 against the live account, through the ordinary chain: POST /v1/text-to-speech/{voice_id} answered 200 with 23449 raw bytes of audio/mpeg — a 1.437 s mp3 in 1.880 s — for the 23-character line 'Hello from the gateway.' in George's voice. It READ the line; nothing was answered. Listed in GET /v1/models. Cost 6 characters of the 64945 budget (provider's own /v1/usage/character-stats), which is LESS than the line is long — so the budget is not one-character-per-character on this tier and nothing here pretends to know the rate. No `usd` for the same reason as the music entry.",+ "verification": "verified" },{ "model": "openai/gpt-audio-mini", "provider": "tokenrouter", "shape": "audio-chat","params": ["messages", "modalities", "audio"], "in": ["text"], "out": ["audio", "text"],"voices": ["alloy"], "format": "wav", "latency_s": 3.03, "stream_required": false,+ "answers_prompts": true,"verification": "verified" },{ "model": "openai/gpt-audio", "provider": "tokenrouter", "shape": "audio-chat","params": ["messages", "modalities", "audio", "stream"], "in": ["text"], "out": ["audio", "text"],"voices": ["alloy"], "format": "wav", "latency_s": 2.6, "stream_required": true,+ "answers_prompts": true,"note": "400 'Audio output requires stream: true' without it; audio arrives at choices[0].delta.audio and must be concatenated.","verification": "verified" }]@@ -197,13 +228,13 @@"text_to_music": {"unit": "track","instead": "Do not use generate_speech instead — it produces conversation, not music.",- "$comment": "All 125 TokenRouter entries were searched by name (suno|udio|lyria|musicgen|music|song|melody) and by tag: the only audio-capable models there are the two conversational speech ones. The owner chose ElevenLabs Music direct. ONE candidate, stood down with the reason it is stood down for — an empty list produces 'no music model is connected', which is true and tells nobody what to do. No key is stored here: when the owner supplies a working one it goes in the integrations document as an ordinary provider entry, like every other.",+ "$comment": "All 125 TokenRouter entries were searched by name (suno|udio|lyria|musicgen|music|song|melody) and by tag: the only audio-capable models there are the two conversational speech ones. The owner chose ElevenLabs Music direct. ONE candidate, and no key is stored here: it lives in the integrations document as an ordinary provider entry, like every other. This candidate spent a day stood down with `paid_plan_required` and no adapter behind it; both facts are gone because both were fixed, and the entry is otherwise the same entry — which is the point of leaving a preferred-but-blocked model ranked in place.","candidates": [{ "model": "elevenlabs/music-v1", "provider": "elevenlabs", "shape": "elevenlabs-music",- "in": ["text"], "out": ["audio"],- "status": "unavailable", "reason_code": "paid_plan_required",- "reason": "Background music needs a paid ElevenLabs plan — the key measured on this account authenticates, but Music is not included in the free tier",- "measured": "e2e run 2026-08-15: POST /v1/music answered 402 Payment Required, NOT 401 — so the key is valid and the account is free-tier. The same key is scoped and cannot do speech either: GET /v1/voices answered 401 'missing the permission'. No adapter is written for this shape (see build_submit), so marking it available without writing one raises rather than silently sending nothing.",+ "params": ["prompt", "duration"], "in": ["text"], "out": ["audio"],+ "format": "mp3", "output_mime": "audio/mpeg", "latency_s": 5.59,+ "note": "The endpoint takes NO model id — `elevenlabs/music-v1` is our name for the candidate, which is what the chain reports, quarantines and prices on. Length is `music_length_ms`, in MILLISECONDS, where every other duration in this file is seconds.",+ "measured": "e2e run 2026-08-15 against the live account, through the ordinary chain: the earlier 402 paid_plan_required is gone (tier `payg`) and POST /v1/music answered 200 with 160541 raw bytes of audio/mpeg — a 10.031 s mp3 in 5.588 s, for music_length_ms 10000. It HONOURS the length asked for; 10.031 against 10.000 is the encoder's frame alignment, not a model ignoring an argument, so no duration_ignored here. Cost 69 characters of the 64945 budget (provider's own /v1/usage/character-stats, breakdown_type=product_type). Only a 10 s render was measured, so no floor and no ceiling are recorded — a duration nobody asked for is worse than no duration, and this endpoint bills. No `usd`: this account is metered in characters and a dollar figure would be one somebody invented.","verification": "verified" }]},diff --git a/gateway/media_plane.py b/gateway/media_plane.pyindex 0e529885..9c9bf3c2 100644--- a/gateway/media_plane.py+++ b/gateway/media_plane.py@@ -17,13 +17,31 @@ parameters honourable, not watermarked unless asked, not quarantined by a recentand the caller reports which one it was. Four video models are listed and two of them are broken;that is the whole reason this exists rather than a model id in a tool argument.-FIVE ENDPOINT SHAPES, all measured against the live account on 2026-08-15:+SEVEN ENDPOINT SHAPES, all measured against the live accounts on 2026-08-15:video-generation POST /video/generations -> task id; GET /video/generations/{id} to pollimage-generation POST /images/generations -> b64_json OR url (both occur)openai POST /chat/completions -> choices[0].message.images[0].image_url.urlgemini POST /v1beta/models/{id}:generateContent -> inlineData partsaudio-chat POST /chat/completions with modalities -> message.audio.data (+ transcript)+ elevenlabs-music POST /music -> RAW AUDIO BYTES+ elevenlabs-speech POST /text-to-speech/{voice_id} -> RAW AUDIO BYTES++THE LAST TWO BREAK WHAT THE FIRST FIVE SHARE, and each break is a place a special case could have+gone. The auth header is not a bearer, and which header a provider wants is declared BESIDE ITS+BASE URL in the catalog — see `auth_of` — rather than branched on its name where the socket is.+The answer is not JSON, and the same endpoint answers audio when it worked and JSON when it did+not, so a response is CLASSIFIED before it is read — see `response_doc`. And the model is a PATH+SEGMENT, not a body field, which is why `voice_for` computes the answer in one place: what the URL+carries and what the tool reports afterwards cannot be allowed to disagree.++They are TWO shapes and not one because a shape IS an endpoint's identity here, and these are two+endpoints: different path, different body, different tunables. `_SHAPE_TUNABLES` is the whitelist a+candidate is held to when it declares no `params` of its own, and each of these lists is exactly+what its builder emits — merge them and the whitelist permits four fields where the endpoint has+two, which is a whitelist that has stopped describing what it guards. Merging would also need the+one branch to pick a path from some new catalog field, which is two shapes wearing one name. What+they genuinely share is shared rather than copied: one auth entry, one raw-response branch."200 OK" IS NOT SUCCESS. A candidate has only run once its response carries an actual mediapayload. google/gemini-3-pro-image-preview answers 200 with `parts: []` and bills ~1356 tokens;@@ -110,8 +128,17 @@ _SHAPE_TUNABLES = {"openai": ("prompt", "image"),"gemini": ("prompt", "image"),"audio-chat": ("messages", "modalities", "audio", "stream"),+ # Two endpoints, two lists, neither a subset of the other — and each is EXACTLY what its+ # builder below emits. A permitted field the endpoint has no slot for is dead permission, and+ # the union of these two is four of them.+ "elevenlabs-music": ("prompt", "duration"),+ "elevenlabs-speech": ("prompt", "voice"),}+# The shapes whose 200 IS THE MEDIA. Every other shape answers with a document that says where the+# media is or carries it base64'd inside; these answer with the file. See `response_doc`.+_RAW_SHAPES = frozenset({"elevenlabs-music", "elevenlabs-speech"})+@functools.lru_cache(maxsize=1)def catalog() -> dict:@@ -146,6 +173,41 @@ def provider_meta(provider: str) -> dict:return p if isinstance(p, dict) else {}+# ── how a provider is signed ──────────────────────────────────────────────────────+# TWO STYLES SO FAR, and which one a provider uses is that PROVIDER'S OWN FACT — declared in the+# catalog beside its base_url, because "where to send it" and "how to sign it" are the same kind of+# fact and are learnt in the same measurement. Five providers wanted `authorization: Bearer <key>`;+# ElevenLabs wants `xi-api-key: <key>` and answers 401 to a bearer.+#+# NOT A BRANCH ON THE PROVIDER'S NAME. `if provider == "elevenlabs"` at the socket would be a+# second place that has to know this provider exists — after the catalog, which is the place — and+# the next provider with its own header would make a third. A deployment can add one by editing+# the file, which is the whole reason the file is read from disk.+_AUTH_DEFAULT = ("authorization", "Bearer ")+++def auth_of(pmeta: dict) -> tuple[str, str]:+ """(header, prefix) this provider signs with.++ The default is the bearer every OpenAI-shaped relay wants, so a provider entry that says+ nothing about auth keeps working — and a `prefix` of "" is a real answer, not an absent one:+ ElevenLabs wants the key bare.+ """+ a = pmeta.get("auth") if isinstance(pmeta, dict) else None+ if not isinstance(a, dict):+ return _AUTH_DEFAULT+ header = str(a.get("header") or _AUTH_DEFAULT[0]).strip().lower()+ prefix = _AUTH_DEFAULT[1] if a.get("prefix") is None else str(a.get("prefix"))+ return header, prefix+++def auth_headers(prov: dict) -> dict:+ """The credential header for one outbound call, in this provider's own style. ONE header, so+ a key can never be sent in two places and only one of them noticed."""+ header, prefix = auth_of(prov)+ return {header: f"{prefix}{prov.get('api_key') or ''}"}++def declared_params(cand: dict) -> set[str]:"""The tunables this candidate accepts. Its own list when it names one, the shape's otherwise —never "everything the caller sent"."""@@ -163,15 +225,83 @@ def estimated_usd(cand: dict) -> float | None:return float(usd) if isinstance(usd, (int, float)) else None+# ── voices ────────────────────────────────────────────────────────────────────────+# A VOICE HAS A NAME AND AN ID, and they belong to different halves of this. The NAME is what the+# agent asks for and what `can_serve` filters the chain on; the ID is what the request carries.+# One candidate holds both, as a {name: id} map, because two fields would be two things to keep in+# step. A candidate whose provider names its voices (`alloy`) declares a plain list instead, and+# both answer `in`.++def voice_names(cand: dict) -> list[str]:+ """The voices this candidate offers, by name, in its own declaration order — never the ids.+ An id is a routing detail; an agent picks a narrator."""+ v = cand.get("voices")+ return [str(k) for k in v] if isinstance(v, (dict, list)) else []+++def default_voice(cand: dict) -> str:+ """The voice used when the caller names none: this candidate's declared default, or the first+ it lists.++ FROM THE CANDIDATE, never from the calling code. `alloy` used to be the tool's default for+ every model in the capability — one provider's voice name standing in for all of them — which+ meant every call that named no voice carried a voice only OpenAI has, and skipped anything+ else in the chain before it could run.+ """+ named = str(cand.get("default_voice") or "")+ return named or next(iter(voice_names(cand)), "")+++def voice_for(cand: dict, params: dict) -> str:+ """The voice this candidate will be ASKED for — "" when it has no voices at all.++ THE ONE PLACE that answer is computed, for the same reason `size_for` is: what the submit+ carries and what the tool reports back afterwards cannot be allowed to disagree.+ """+ if not cand.get("voices"):+ return ""+ return str(params.get("voice") or default_voice(cand))+++def voice_id(cand: dict, voice: str) -> str:+ """The provider's own id for a named voice, or "" when this candidate does not offer it. Only+ a candidate whose voices are addressed BY ID has a map to answer from."""+ voices = cand.get("voices")+ return str((voices or {}).get(voice) or "") if isinstance(voices, dict) else ""+++# What a model that ANSWERS a prompt has to be told, to make it read one instead. A workaround for+# the wrong kind of model doing narration — measured: "Say: hello." came back as "Hello! It's great+# to talk with you." — so it is applied PER CANDIDATE, to the ones that need it.+#+# It used to be built by the tool, before any model had been chosen, which is a sentence about+# gpt-audio applied to whatever ran. A real reader would have READ IT OUT: "Read this aloud exactly+# as written, and say nothing else: the tide went out."+_READ_ALOUD = "Read this aloud exactly as written, and say nothing else: "+++def spoken_prompt(cand: dict, text: str) -> str:+ """The line as this candidate must be given it."""+ return (_READ_ALOUD + text) if cand.get("answers_prompts") else text++def limits_of(cand: dict) -> dict:"""What list_capabilities tells the agent about the model it would get. Only keys thecandidate actually declares — an absent limit is absent, not a default someone invented."""out: dict = {}for k in ("durations_s", "duration_min_s", "duration_max_s", "durations_rejected_s","duration_ignored", "duration_observed_s", "resolution", "min_pixels",- "sizes_verified", "voices", "format", "latency_s", "output_mime"):+ "sizes_verified", "format", "latency_s", "output_mime"):if cand.get(k) is not None:out[k] = cand[k]+ if cand.get("voices"):+ # NAMES, whichever way this candidate stores them. The agent chooses by name and passes a+ # name back; an id in this dict would be a second spelling of the same choice.+ out["voices"] = voice_names(cand)+ if cand.get("answers_prompts"):+ # A measured property of the MODEL, and the one an agent planning narration most needs+ # before it spends: this one will answer the line instead of reading it.+ out["answers_prompts"] = Trueif "accepts_input_image" in cand:out["accepts_input_image"] = bool(cand["accepts_input_image"])if cand.get("watermark"):@@ -487,10 +617,21 @@ def _timeout_for(cand: dict) -> float:def _api_root(base: str) -> str:- """The provider's API root, for the one shape whose path is not `/v1` relative.-- The configured base carries the `/v1` every other shape needs, so it is right to keep it there- and strip it HERE rather than store a second base_url that could drift out of step with it.+ """The provider's API root: the configured base with a trailing `/v1` taken off it.++ Two shapes need this, for opposite reasons, and both reasons are the same fact — a base_url is+ typed by a person and the version segment is the part they disagree about.++ gemini posts under `/v1beta`, which hangs off the ROOT. TokenRouter's base carries+ `/v1` for the four shapes that need it, so it is stripped here rather than+ stored twice where the two copies could drift.+ the two elevenlabs+ shapes build their own `/v1/…` on top of what this returns, so the SAME+ url is produced whether the connected integration was saved as+ `https://api.elevenlabs.io` or `https://api.elevenlabs.io/v1`. Measured:+ the live integration is stored the first way and the catalog's default is+ too; a shape that simply concatenated would 404 on the other spelling, and+ a 404 here reads as "the provider is down"."""return base[:-3].rstrip("/") if base.endswith("/v1") else base@@ -587,14 +728,15 @@ def build_submit(cand: dict, base_url: str, params: dict) -> Submit:timeout=_timeout_for(cand))if shape == "audio-chat":- text = params.get("prompt") or ""+ # The read-aloud instruction is THIS candidate's, not the tool's — see `spoken_prompt`.+ text = spoken_prompt(cand, str(params.get("prompt") or ""))body = {"model": model,"messages": [{"role": "user", "content": text}]}if "modalities" in allow:tun["modalities"] = ["text", "audio"]body["modalities"] = ["text", "audio"]if "audio" in allow:- aud = {"voice": params.get("voice") or "alloy",+ aud = {"voice": voice_for(cand, params) or "alloy","format": str(cand.get("format") or "wav")}tun["audio"] = audbody["audio"] = aud@@ -606,6 +748,39 @@ def build_submit(cand: dict, base_url: str, params: dict) -> Submit:return Submit("POST", f"{base}/chat/completions", body, tun, stream=stream,timeout=_timeout_for(cand))+ if shape == "elevenlabs-music":+ body = {}+ prompt = take("prompt", params.get("prompt"))+ if prompt is not None:+ body["prompt"] = prompt+ secs = take("duration", params.get("seconds"))+ if secs is not None:+ # MILLISECONDS, where every other duration in this catalog is seconds. Measured: 10000+ # returned a 10.031 s track.+ body["music_length_ms"] = int(round(float(secs) * 1000))+ # NO MODEL FIELD ANYWHERE: this endpoint takes none. `elevenlabs/music-v1` is our name for+ # the candidate — what the chain reports, quarantines and prices on — and it stays here.+ return Submit("POST", f"{_api_root(base)}/v1/music", body, tun,+ timeout=_timeout_for(cand))++ if shape == "elevenlabs-speech":+ # THE MODEL THIS ADDRESSES IS A PATH SEGMENT. A voice id in the body would be accepted,+ # ignored, and billed as a default voice — the same class of failure as MiniMax ignoring an+ # input image, one layer up, and just as invisible in a 200.+ name = take("voice", voice_for(cand, params))+ vid = voice_id(cand, str(name or ""))+ if not vid:+ raise MediaError(f"{model} has no voice called {name!r}.")+ # Through `spoken_prompt` like the other speech shape, and not around it: "how must this+ # candidate be given the line" is ONE question, and a shape that answers it by not asking+ # is a shape that will be given the wrong answer the day a reader is added to the other+ # branch. This candidate does not declare `answers_prompts`, so the line comes back+ # untouched — which is the whole point, and is now asserted rather than arranged.+ line = take("prompt", spoken_prompt(cand, str(params.get("prompt") or "")))+ body = {"text": line or "", "model_id": model}+ return Submit("POST", f"{_api_root(base)}/v1/text-to-speech/{vid}", body, tun,+ timeout=_timeout_for(cand))+raise MediaError(f"No adapter for endpoint shape {shape!r}.")@@ -616,6 +791,48 @@ def build_poll(cand: dict, base_url: str, task_id: str) -> tuple[str, str]:# ── the five adapters: reading a response ─────────────────────────────────────────+class Raw:+ """A response body that IS the media, rather than a document describing where it is."""++ __slots__ = ("data", "mime")++ def __init__(self, data: bytes, mime: str):+ self.data, self.mime = data, mime+++# What a provider CLAIMS it sent, when the claim is that it sent media. Used for exactly one+# decision — parse or do not parse — and for nothing else.+_MEDIA_CT = re.compile(r"^\s*(?:audio|image|video)/", re.I)+++def response_doc(content_type: str, body: bytes):+ """What the readers below are handed for one response: the parsed document, or the BYTES+ THEMSELVES when the provider answered with media instead of with a description of one.++ THE CONTENT TYPE DECIDES, because nothing else can. ElevenLabs answers the SAME endpoint with+ audio when it worked and with JSON when it did not, and those two answers mean opposite things+ about money — a 4xx is free and stays in the chain, a 200 billed. "Parse it and see" reads a+ 402 as a corrupt track and pushes 160 KB of mp3 through `json.loads` on every call that+ succeeded. A parser is not a classifier.++ THIS IS NOT THE SNIFFING RULE BEING RELAXED. What the provider claims decides only whether to+ parse. What the bytes ARE still decides whether they are media, in `sniff`/`verify`, which+ every payload goes through before it is stored — an HTML error page labelled `audio/mpeg` gets+ this far and is refused there, exactly as it always was. The two questions are different and+ only one of them is answerable from a header.++ Anything not claimed as media is a document, INCLUDING a body with no content type at all: the+ five older shapes answer JSON and some relays say so and some do not, and defaulting the other+ way would break every one of them on a header nobody sends.+ """+ if _MEDIA_CT.match(content_type or ""):+ return Raw(bytes(body or b""), str(content_type).split(";")[0].strip().lower())+ try:+ return json.loads(body or b"{}")+ except Exception: # noqa: BLE001+ return None++class Payload:"""Media that actually arrived: bytes in hand, or a URL to fetch them from."""@@ -665,9 +882,23 @@ def _read_submit(cand: dict, status: int, doc) -> tuple[str, Payload | None]:"""if status >= 400:raise MediaRefused(provider_message(doc, status))+ shape = str(cand.get("shape") or "")++ if shape in _RAW_SHAPES:+ # A 200 from these IS the audio. Asked BEFORE the object check below, which would+ # otherwise read the track itself as "not an object" and stand the model down for+ # delivering.+ if isinstance(doc, Raw):+ if doc.data:+ return "", Payload(data=doc.data, mime=doc.mime)+ raise MediaEmpty("the provider answered 200 with an empty audio file")+ # A DOCUMENT where the audio should be: this provider talking, in a body that parsed. It+ # answered, so it billed, and it gets what every other 200 with no media in it gets — with+ # its own sentence, which is the only one that says what actually went wrong.+ raise MediaEmpty(provider_message(doc, status))+if not isinstance(doc, dict):raise MediaEmpty("the provider answered with a body that is not an object")- shape = str(cand.get("shape") or "")if shape == "video-generation":tid = str(doc.get("task_id") or doc.get("id") or "")diff --git a/gateway/tests/test_media_mcp.py b/gateway/tests/test_media_mcp.pyindex c733cb90..71328f4f 100644--- a/gateway/tests/test_media_mcp.py+++ b/gateway/tests/test_media_mcp.py@@ -17,6 +17,7 @@ ids rather than resubmitting. No generation is ever looped."""from __future__ import annotations+import astimport asyncioimport base64import json@@ -61,6 +62,10 @@ from fastapi.testclient import TestClient # noqa: E402# The sentinel. Every assertion about "the key never comes out" is about this exact string.PROVIDER_KEY = "sk-tr-SENTINEL-do-not-leak-4f7a9b21"+# The SECOND deployment credential. A separate sentinel on purpose: with one string for both+# providers, "the ElevenLabs key was not sent to TokenRouter" is unprovable, and that is precisely+# the mistake a second auth style makes possible.+ELEVEN_KEY = "sk_el-SENTINEL-do-not-leak-90c3ad12"ORG = "testorg"HEADERS = {"x-harness-internal": "test-internal-key", "x-harness-org": ORG,@@ -69,6 +74,7 @@ HEADERS = {"x-harness-internal": "test-internal-key", "x-harness-org": ORG,MCP_URL = "https://gateway.example/v1/mcp/media"ENTRY_ID = "mcp.media"TR = "https://api.tokenrouter.com/v1"+EL = "https://api.elevenlabs.io/v1"# The kit that provisions the media server. Attaching it is something the kit that uses it drives,# so every attach in this file goes through launch — there is no other way in.@@ -96,6 +102,10 @@ PNG_1PX = base64.b64decode("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==")WAV_SILENCE = (b"RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00\x40\x1f\x00\x00"b"\x80>\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00")+# One MPEG-1 Layer III frame header and its payload. ElevenLabs answers with mp3 BYTES and no JSON+# at all, so what the raw shapes are fed here has to be bytes that `sniff` genuinely identifies —+# a JSON stub would let the raw path pass a test the product fails on the first real call.+MP3_SILENCE = b"\xff\xfb\x90\x00" + bytes(414)def _mp4(seconds: float = 1.0, size: str = "128x72") -> bytes:@@ -113,8 +123,13 @@ def _mp4(seconds: float = 1.0, size: str = "128x72") -> bytes:# ── the provider, mocked at the transport ────────────────────────────────────────class Provider:- """A stand-in for TokenRouter that answers per model, records every request, and can be told- to fail a specific one. The adapters run for real against it."""+ """A stand-in for the two connected providers that answers per model, records every request,+ and can be told to fail a specific one. The adapters run for real against it.++ TokenRouter and ElevenLabs are both here because they are both connected in this deployment,+ and because the interesting failures are the ones that only exist once there are two: a key+ sent in the wrong header, or to the wrong host.+ """def __init__(self):self.fail: dict[str, tuple[int, dict]] = {} # model -> (status, body)@@ -125,17 +140,37 @@ class Provider:# PROVIDER's to choose, which is the whole reason they are knobs here.self.result_url = "https://cdn.provider.example/out.mp4"self.cdn_status = 200+ # What the raw shapes answer with, and how they label it. Both are knobs because the whole+ # point of those two adapters is that the SAME endpoint answers audio or JSON.+ self.audio_bytes = MP3_SILENCE+ self.audio_ctype = "audio/mpeg"def queue_poll(self, task_id: str, *answers) -> None:self.polls.setdefault(task_id, []).extend(answers)def handle(self, req: httpx.Request) -> httpx.Response:- body = json.loads(req.content or b"{}") if req.content else {}- call = {"method": req.method, "url": str(req.url), "body": body,- "auth": req.headers.get("authorization", "")}+ url = str(req.url)+ # A JSON body where there is one. ElevenLabs is asked in JSON like everything else — it is+ # the ANSWER that is binary — but a request body is never assumed to parse.+ try:+ body = json.loads(req.content or b"{}") if req.content else {}+ except ValueError:+ body = {}+ call = {"method": req.method, "url": url, "body": body,+ "auth": req.headers.get("authorization", ""),+ "xi": req.headers.get("xi-api-key", "")}_calls.append(call)_all_calls.append(call)- url = str(req.url)++ # ── ElevenLabs: raw audio out, JSON only when it goes wrong ──────────────+ if url.startswith(EL):+ model = ("elevenlabs/music-v1" if url.endswith("/music")+ else str(body.get("model_id") or ""))+ if model in self.fail:+ st, b = self.fail[model]+ return httpx.Response(st, json=b)+ return httpx.Response(200, content=self.audio_bytes,+ headers={"content-type": self.audio_ctype})if url.endswith("/video/generations") and req.method == "POST":model = body.get("model") or ""@@ -287,17 +322,24 @@ def api(client):return Rec(client)-def _connect_provider(key: str = PROVIDER_KEY) -> None:- """One TokenRouter integration holding the key — the deployment's own credential, which is- what every media call resolves and what nothing may ever return.+def _connect_provider(key: str = PROVIDER_KEY, eleven: str = ELEVEN_KEY) -> None:+ """The deployment's own credentials — one per provider, which is what every media call+ resolves and what nothing may ever return.++ TWO entries, because this deployment has two connected providers and the difference between+ them is the point: they are signed in different headers, and an integration document with one+ provider in it cannot show that the right key went to the right host.Written straight into the document the media server reads, rather than through the adminroute: how a key got connected is another surface's business, and going through that routewould make this file depend on the identity mode whichever test module imported `app` firsthappened to set."""- asyncio.run(app._vault_put(app.GLOBAL_TENANT, app._INTEGRATIONS_KEY, json.dumps(- [{"name": "tr", "provider": "tokenrouter",- "config": {"api_key": key, "base_url": TR}}])))+ doc = [{"name": "tr", "provider": "tokenrouter",+ "config": {"api_key": key, "base_url": TR}}]+ if eleven:+ doc.append({"name": "el", "provider": "elevenlabs",+ "config": {"api_key": eleven, "base_url": EL}})+ asyncio.run(app._vault_put(app.GLOBAL_TENANT, app._INTEGRATIONS_KEY, json.dumps(doc)))@pytest.fixture(scope="module", autouse=True)@@ -404,6 +446,13 @@ def _err(res: dict) -> str:return res["content"][0]["text"]+def _el(cap: str) -> dict:+ """The ElevenLabs candidate in a capability's chain, found by PROVIDER — so a test says what it+ means ("the one that is not TokenRouter's") instead of repeating a model id the catalog owns."""+ return next(c for c in media_plane.capability(cap)["candidates"]+ if c.get("provider") == "elevenlabs")++def _save_config(api, hid: str, servers: list, name="Videos"):return api.put(f"/v1/harnesses/{hid}",json={"name": name, "base": "claude-code", "mcp_servers": servers})@@ -810,8 +859,9 @@ def test_every_refusal_ends_with_you_cannot_connect_it_yourself(client, harness,"""Invariant 25, over every no-model path there is."""for m in [c["model"] for c in media_plane.capability("text_to_video")["candidates"]]:app._media_quarantine[m] = time.time() + 900- for m in [c["model"] for c in media_plane.capability("text_to_speech")["candidates"]]:- app._media_quarantine[m] = time.time() + 900+ for cap in ("text_to_speech", "text_to_music"):+ for m in [c["model"] for c in media_plane.capability(cap)["candidates"]]:+ app._media_quarantine[m] = time.time() + 900tok = _cred(harness, session)for name, args in (("generate_video", {"prompt": "a", "seconds": 6}),("generate_speech", {"text": "hello"}),@@ -819,23 +869,25 @@ def test_every_refusal_ends_with_you_cannot_connect_it_yourself(client, harness,assert "you cannot connect" in _err(_call(client, tok, name, args)).lower(), name-def test_music_never_becomes_speech(client, harness, session, provider):- """Invariant 10: with text_to_speech fully available, generate_music still refuses, and no- provider call is made.+def test_music_never_becomes_speech(client, harness, session, provider, monkeypatch):+ """Invariant 10: when no music model can run, generate_music REFUSES and reaches for no speech+ model on the way — and the refusal names the fix rather than leaving the reader nowhere.- And the refusal NAMES THE FIX. One candidate stood down with the reason it is stood down for- beats an empty list: "no music model is connected" is true and leaves the reader nowhere,- while "needs a paid ElevenLabs plan" is a thing a person can go and do.+ Driven here by standing the music model down, because the capability is available in this+ deployment now. The invariant was never about the model being broken; it is about what happens+ when it is, and a chain that could fall through to `text_to_speech` would be a silent+ substitution of conversation for a score."""_calls.clear()+ app._media_quarantine["elevenlabs/music-v1"] = time.time() + 900text = _err(_call(client, _cred(harness, session), "generate_music",- {"prompt": "a warm orchestral score"}))- assert "paid ElevenLabs plan" in text, text- assert "not music" in text+ {"prompt": "a warm orchestral score", "seconds": 10}))+ assert "not music" in text, text+ assert "you cannot connect" in text.lower()assert _calls == []# And speech is genuinely available right now, so this is not passing on an empty deployment.assert _ok(_call(client, _cred(harness, session), "generate_speech",- {"text": "hello"}))["model"].startswith("openai/gpt-audio")+ {"text": "hello"}))["status"] == "succeeded"def test_list_capabilities_is_free_and_names_what_is_broken(client, harness, session, provider):@@ -857,8 +909,8 @@ def test_list_capabilities_is_free_and_names_what_is_broken(client, harness, ses"resolution": "1280x720","accepts_input_image": False,"aspects": ["16:9"]}- assert by["text_to_music"]["available"] is False- assert "paid ElevenLabs plan" in by["text_to_music"]["reason"]+ assert by["text_to_music"]["available"] is True+ assert by["text_to_music"]["model"] == "elevenlabs/music-v1"assert by["export"]["available"] is media_plane.have_ffmpeg()# A cost is present only where it was measured.assert "estimated_usd_per_unit" not in by["text_to_video"]@@ -1079,7 +1131,12 @@ def test_a_size_below_a_models_floor_skips_it(client, harness, session, providerdef test_speech_reports_what_the_model_actually_said(client, harness, session, provider):"""These models ANSWER the prompt rather than reading it, and the transcript the provider- returns is real data — so `verbatim` is measured, not assumed."""+ returns is real data — so `verbatim` is measured, not assumed.++ The reader that now outranks them is stood down first, which is the only way to reach them:+ they are the FALLBACK for this capability, and the warning below is the reason they are.+ """+ app._media_quarantine[_el("text_to_speech")["model"]] = time.time() + 900out = _ok(_call(client, _cred(harness, session), "generate_speech", {"text": "Say: hello."}))assert out["model"] == "openai/gpt-audio-mini"assert "answers prompts rather than reading them" in out["warning"]@@ -1091,6 +1148,7 @@ def test_the_streaming_audio_model_is_driven_the_way_it_demands(client, harness,provider):"""gpt-audio answers 400 without stream:true and then delivers audio in deltas that have to beconcatenated."""+ app._media_quarantine[_el("text_to_speech")["model"]] = time.time() + 900app._media_quarantine["openai/gpt-audio-mini"] = time.time() + 900out = _ok(_call(client, _cred(harness, session), "generate_speech", {"text": "hello"}))assert out["model"] == "openai/gpt-audio" and out["status"] == "succeeded"@@ -1409,22 +1467,355 @@ def test_a_duration_a_model_measurably_refuses_is_not_offered_to_it(cap):assert media_plane.can_serve(cand, {"seconds": 6}) == ""-def test_music_is_one_stood_down_candidate_and_not_an_empty_list():- """A capability with no candidates can only say "nothing is connected". One candidate carrying- the reason it is stood down says what to do instead — and holds no credential to say it."""+def test_music_is_one_candidate_that_holds_no_credential_to_be_one():+ """The music chain is ONE candidate — the model the owner chose — and the key that reaches it+ is not in this file. It never was: when this candidate was stood down for a free-tier plan the+ same assertion held, and it is the one that must survive the candidate becoming available."""cap = media_plane.capability("text_to_music")- cand, skipped = media_plane.resolve("text_to_music", {}, {"tokenrouter"}, {})- assert cand is Noneassert len(cap["candidates"]) == 1only = cap["candidates"][0]- assert only["model"] == "elevenlabs/music-v1" and only["status"] == "unavailable"- assert only["reason_code"] == "paid_plan_required"- # The measured reason is what the agent is told — NOT "nobody has connected that provider",- # which is the sentence an unconnected provider would otherwise produce first.- assert skipped == [only["reason"]]- assert "paid ElevenLabs plan" in media_plane.refusal("text_to_music", skipped)- assert not [k for k in json.dumps(cap).lower().split('"') if k.startswith("sk_")], \+ assert only["model"] == "elevenlabs/music-v1" and only["provider"] == "elevenlabs"+ assert not only.get("status"), "the music candidate is stood down again"+ # Nothing that looks like a credential, for EITHER provider's key shape.+ blob = json.dumps(media_plane.catalog()).lower()+ assert "sk_" not in blob and "sk-" not in blob, \"a key was written into the catalog; it belongs in the integration document"+ # And with the provider not connected, the refusal is the ordinary one and still names the fix.+ _, skipped = media_plane.resolve("text_to_music", {}, {"tokenrouter"}, {})+ assert "you cannot connect one yourself" in media_plane.refusal("text_to_music", skipped)+++# ══ a sixth provider, shaped like none of the five ═══════════════════════════════+# ElevenLabs breaks all three assumptions the five TokenRouter shapes share: it is signed in its+# own header, it answers a submit with RAW AUDIO instead of a document, and its model is a PATH+# SEGMENT. Each of those is a place a special case could have gone; these pin that none of them+# did.++def test_the_two_elevenlabs_shapes_are_two_because_their_whitelists_differ():+ """One shape or two is a real choice, and this is the fact that decides it.++ Music takes a length and no voice; speech takes a voice and no length. A single shape's+ whitelist would have to be the UNION of those, which would forward `voice` to the music+ endpoint and `music_length_ms` to the speech one — the exact defect "never forward an+ unrecognised parameter" exists to stop, reintroduced by tidying two adapters into one.++ What the two DO share — the auth header and the raw-audio answer — is expressed once each and+ outside the shape branch, so two shapes cost nothing in duplication.+ """+ music, speech = _el("text_to_music"), _el("text_to_speech")+ assert music["shape"] != speech["shape"]+ assert media_plane.declared_params(music) == {"prompt", "duration"}+ assert media_plane.declared_params(speech) == {"prompt", "voice"}+ # Asserted on the SHAPE and not only on these two entries, because the shape's list is what a+ # candidate added later WITHOUT its own `params` is held to — and because a whitelist is only+ # a whitelist while it still describes its endpoint. Each of these shapes permits EXACTLY what+ # its builder emits when it is offered everything: a permitted field the endpoint has no slot+ # for is dead permission, and the union of the two is four of them.+ bare = {"model": "x", "provider": "elevenlabs"}+ loose = {"prompt": "p", "seconds": 10, "voice": "George"}+ for cand, extra, want in (+ (music, {}, {"prompt", "duration"}),+ (speech, {"voices": speech["voices"]}, {"prompt", "voice"})):+ shape = cand["shape"]+ sent = media_plane.build_submit({**bare, "shape": shape, **extra}, EL, loose)+ assert set(sent.tunables) == set(media_plane._SHAPE_TUNABLES[shape]) == want, (+ shape, sorted(sent.tunables), sorted(media_plane._SHAPE_TUNABLES[shape]))+ # And nothing crossed over: no voice in a music body, no length in a speech one.+ assert "George" not in json.dumps(media_plane.build_submit(music, EL, loose).body)+ assert "10000" not in json.dumps(media_plane.build_submit(speech, EL, loose).body)+ # The shared halves are shared, not copied.+ assert media_plane.provider_meta("elevenlabs")["auth"]["header"] == "xi-api-key"+ for cand in (music, speech):+ _, payload = media_plane.read_submit(+ cand, 200, media_plane.response_doc("audio/mpeg", MP3_SILENCE))+ assert payload.data == MP3_SILENCE and payload.mime == "audio/mpeg"+++def test_the_music_request_is_the_one_that_was_measured():+ """POST /v1/music {prompt, music_length_ms} — measured 2026-08-15, and the length is in+ MILLISECONDS while every other duration in this catalog is in seconds."""+ sub = media_plane.build_submit(_el("text_to_music"), EL,+ {"prompt": "a warm score", "seconds": 10,+ "voice": "Sarah", "not_a_real_param": "boom"})+ assert sub.url == f"{EL}/music"+ assert sub.body == {"prompt": "a warm score", "music_length_ms": 10000}+ assert set(sub.tunables) <= media_plane.declared_params(_el("text_to_music"))+ assert "Sarah" not in json.dumps(sub.body) and "boom" not in json.dumps(sub.body)+++def test_the_voice_is_a_path_segment_and_never_a_body_field():+ """The third broken assumption: the model this shape addresses is chosen by the URL.++ A voice id in the body would be silently ignored and a default voice would be billed for —+ the same class of failure as MiniMax ignoring an input image, one layer up.+ """+ cand = _el("text_to_speech")+ sub = media_plane.build_submit(cand, EL, {"prompt": "Hello there.", "voice": "Sarah"})+ vid = cand["voices"]["Sarah"]+ assert sub.url == f"{EL}/text-to-speech/{vid}"+ assert sub.body == {"text": "Hello there.", "model_id": cand["model"]}+ assert vid not in json.dumps(sub.body)+++def test_a_model_that_reads_the_line_is_not_told_to_read_it_aloud():+ """The wrapper is a WORKAROUND for a conversational model doing narration, so it belongs to+ the models that need it and to nothing else.++ Measured: gpt-audio answers "Say: hello." with "Hello! It's great to talk with you." — so it+ is sent an instruction. ElevenLabs reads what it is given, so sending it the same instruction+ would make it SAY "Read this aloud exactly as written" out loud. The tool used to build that+ sentence itself, before any model was chosen, which is why it reached both.+ """+ line = "The tide went out and never came back."+ speech = media_plane.build_submit(_el("text_to_speech"), EL, {"prompt": line})+ assert speech.body["text"] == line, "a real reader was handed the workaround"++ chat = next(c for c in media_plane.capability("text_to_speech")["candidates"]+ if c.get("shape") == "audio-chat")+ said = media_plane.build_submit(chat, TR, {"prompt": line})+ assert said.body["messages"][0]["content"].endswith(line)+ assert said.body["messages"][0]["content"] != line, "the model that answers lost its wrapper"+ assert chat["answers_prompts"] is True+++def test_audio_and_an_error_arrive_at_the_same_endpoint_and_are_told_apart_by_content_type():+ """The second broken assumption. ONE endpoint answers either, so the code cannot decide by+ hoping — and the two answers mean opposite things about money.++ audio/mpeg + 200 -> the track, and nothing is stood down+ application/json -> the provider talking. 4xx is a refusal (free, stays in the chain);+ a 200 that carried a document billed and delivered nothing.+ """+ cand = _el("text_to_music")+ doc = media_plane.response_doc("audio/mpeg", MP3_SILENCE)+ assert media_plane.read_submit(cand, 200, doc)[1].data == MP3_SILENCE++ err = media_plane.response_doc(+ "application/json", b'{"detail":{"message":"Music API is not available for free users."}}')+ with pytest.raises(media_plane.MediaRefused) as refused:+ media_plane.read_submit(cand, 402, err)+ assert "not available for free users" in str(refused.value)+ # The same document at 200 is the expensive one: it answered, so it billed.+ with pytest.raises(media_plane.MediaEmpty):+ media_plane.read_submit(cand, 200, err)+ # And an empty body labelled as audio is not a track either.+ with pytest.raises(media_plane.MediaEmpty):+ media_plane.read_submit(cand, 200, media_plane.response_doc("audio/mpeg", b""))+++def test_no_binary_body_is_ever_handed_to_a_json_parser(monkeypatch):+ """160 KB of mp3 through json.loads is waste on every successful call, and the exception it+ raises is indistinguishable from a relay renaming a field. The classification happens first."""+ seen: list[bytes] = []+ real = json.loads++ def watched(s, *a, **kw):+ seen.append(s if isinstance(s, bytes) else str(s).encode())+ return real(s, *a, **kw)++ monkeypatch.setattr(media_plane.json, "loads", watched)+ doc = media_plane.response_doc("audio/mpeg", MP3_SILENCE)+ assert isinstance(doc, media_plane.Raw)+ assert seen == [], f"a binary body reached a JSON parser: {seen}"+ # A document still parses — this is a classifier, not a blanket refusal to read anything.+ assert media_plane.response_doc("application/json; charset=utf-8", b'{"a":1}') == {"a": 1}+ assert seen, "nothing was parsed at all; the classifier swallowed the JSON path too"+++def test_the_content_type_only_chooses_the_parser_and_never_vouches_for_the_bytes():+ """`sniff` deliberately never trusts a provider's label. Routing on it here does not soften+ that: an HTML error page labelled audio/mpeg gets through the reader and is refused by+ `verify`, exactly as it always was."""+ lie = b"<!doctype html><html><body>502 Bad Gateway</body></html>"+ _, payload = media_plane.read_submit(_el("text_to_music"), 200,+ media_plane.response_doc("audio/mpeg", lie))+ assert payload.data == lie+ with pytest.raises(media_plane.MediaEmpty):+ media_plane.verify("audio", payload.data)+++def test_the_auth_style_is_declared_in_the_catalog_and_not_branched_on_a_provider_name():+ """Invariant: the catalog is where a provider's facts live, and "how it is signed" is one.++ A `if provider == "elevenlabs"` beside the socket would be a second place that has to know+ this provider exists, and the next provider would add a third.+ """+ assert media_plane.auth_headers({"api_key": "K", **media_plane.provider_meta("elevenlabs")}) \+ == {"xi-api-key": "K"}+ assert media_plane.auth_headers({"api_key": "K", **media_plane.provider_meta("tokenrouter")}) \+ == {"authorization": "Bearer K"}+ # A provider entry that says nothing about auth still gets the bearer every relay wants.+ assert media_plane.auth_headers({"api_key": "K"}) == {"authorization": "Bearer K"}++ # And no PROVIDER NAME is compared against anywhere in either module. Read out of the syntax+ # tree rather than grepped for, so the rule survives being explained in a comment that has to+ # spell the thing it forbids — and so it catches every spelling instead of the six somebody+ # thought of.+ names = set((media_plane.catalog().get("providers") or {}))+ assert names, "no providers in the catalog; this would pass on an empty file"+ for mod in (app, media_plane):+ for node in ast.walk(ast.parse(Path(mod.__file__).read_text())):+ if not isinstance(node, ast.Compare):+ continue+ for side in [node.left, *node.comparators]:+ assert not (isinstance(side, ast.Constant) and side.value in names), (+ f"{Path(mod.__file__).name}:{node.lineno} branches on the provider name "+ f"{side.value!r}; that fact belongs in the catalog")+++def test_each_provider_is_signed_in_its_own_header_and_never_in_the_others(client, harness,+ session, provider):+ """The one that matters once there are two keys: the wrong key in the right header is a+ credential handed to a third party."""+ _calls.clear()+ tok = _cred(harness, session)+ assert _ok(_call(client, tok, "generate_image", {"prompt": "a"}))["media_id"]+ assert _ok(_call(client, tok, "generate_music", {"prompt": "a warm score", "seconds": 10}))+ tr = [c for c in _calls if c["url"].startswith(TR)]+ el = [c for c in _calls if c["url"].startswith(EL)]+ assert tr and el, f"one of the two providers was never called: {[c['url'] for c in _calls]}"+ for c in tr:+ assert c["auth"] == f"Bearer {PROVIDER_KEY}" and c["xi"] == ""+ for c in el:+ assert c["xi"] == ELEVEN_KEY and c["auth"] == ""+ assert ELEVEN_KEY not in json.dumps(tr) and PROVIDER_KEY not in json.dumps(el)+++def test_music_is_made_by_a_music_model_and_never_by_a_speech_one(client, harness, session,+ provider):+ """Invariant 10, now that the capability is available rather than refused: generate_music+ reaches the music endpoint, and no speech model is touched on the way."""+ _calls.clear()+ out = _ok(_call(client, _cred(harness, session), "generate_music",+ {"prompt": "a warm orchestral score", "seconds": 10}))+ assert out["model"] == "elevenlabs/music-v1" and out["status"] == "succeeded"+ assert [c["url"] for c in _calls] == [f"{EL}/music"]+ assert media_plane.capability("text_to_music")["instead"], \+ "the substitution warning was deleted with the refusal it used to be attached to"+++def test_speech_reads_the_line_it_was_given_and_says_so(client, harness, session, provider):+ """The upgrade, end to end: a real reader outranks the two conversational models, the line+ reaches it verbatim, and the tool stops warning about a limitation the model that ran does not+ have."""+ _calls.clear()+ line = "Say: hello."+ out = _ok(_call(client, _cred(harness, session), "generate_speech", {"text": line}))+ assert out["model"] == _el("text_to_speech")["model"]+ assert out["status"] == "succeeded"+ assert "warning" not in out, out.get("warning")+ assert "spoken_text" not in out, "a reader was asked what it said"+ assert out["voice"] == _el("text_to_speech")["default_voice"]+ body = next(c["body"] for c in _calls if "/text-to-speech/" in c["url"])+ assert body["text"] == line+++def test_a_voice_a_model_does_not_have_picks_the_model_that_does(client, harness, session,+ provider):+ """A voice is the caller's, and the chain is filtered by it — so naming `alloy` still reaches+ the model that has one. This is why the tool no longer defaults to `alloy` itself: a default+ written into the tool is a default written for ONE provider, and it skipped the other on every+ call that named no voice."""+ tok = _cred(harness, session)+ assert _ok(_call(client, tok, "generate_speech",+ {"text": "hello", "voice": "alloy"}))["model"] == "openai/gpt-audio-mini"+ named = _el("text_to_speech")["default_voice"]+ assert _ok(_call(client, tok, "generate_speech",+ {"text": "hello", "voice": named}))["model"] == _el("text_to_speech")["model"]+ tool = next(t for t in app._MEDIA_MCP_TOOLS if t["name"] == "generate_speech")+ assert "default" not in tool["inputSchema"]["properties"]["voice"], \+ "the tool names one provider's voice as the default for every provider"+++def test_the_elevenlabs_key_never_comes_back_out_of_its_own_401(client, harness, session,+ provider):+ """A 401 is the answer guaranteed to quote the key back at you, and this provider's key is a+ different string in a different header — so the scrub has to have been told about it."""+ provider.fail[_el("text_to_speech")["model"]] = (+ 401, {"detail": {"message": f"Invalid API key provided: {ELEVEN_KEY}"}})+ provider.fail["elevenlabs/music-v1"] = (+ 401, {"detail": {"message": f"Invalid API key provided: {ELEVEN_KEY}"}})+ tok = _cred(harness, session)+ out = _ok(_call(client, tok, "generate_speech", {"text": "hello"}))+ assert out["model"].startswith("openai/gpt-audio"), "the chain did not fall through a 401"+ assert ELEVEN_KEY not in json.dumps(out)+ assert ELEVEN_KEY not in _err(_call(client, tok, "generate_music", {"prompt": "a"}))+++def test_a_raw_shape_that_answers_200_with_a_document_is_billed_and_stood_down(client, harness,+ session, provider):+ """The gemini-3-pro rule, on a shape that has no JSON in it when it works. A 200 carrying a+ document is the provider ANSWERING, which is the only evidence there is that it billed."""+ provider.audio_ctype, provider.audio_bytes = "application/json", b'{"detail":"nope"}'+ tok = _cred(harness, session)+ assert "nothing was charged" not in _err(_call(client, tok, "generate_music",+ {"prompt": "a", "seconds": 10})).lower()+ assert app._media_quarantine.get("elevenlabs/music-v1", 0) > time.time()+++def test_the_submit_ceiling_still_holds_when_the_answer_is_binary(client, harness, session,+ provider, monkeypatch):+ """The auth style and the response mode are new; the ceiling in `_media_call` is not, and+ adding a second of either must not have moved it off the socket."""+ monkeypatch.setattr(app, "_MEDIA_MAX_ADVANCES", 0)+ provider.audio_ctype, provider.audio_bytes = "application/json", b'{"detail":"nope"}'+ _calls.clear()+ _call(client, _cred(harness, session), "generate_speech", {"text": "hello"})+ submits = [c for c in _calls if c["method"] == "POST"]+ assert len(submits) <= 1, f"one generate_speech bought {len(submits)} renders: {submits}"++[email protected]("base", ["https://api.elevenlabs.io", "https://api.elevenlabs.io/v1"])+def test_both_spellings_of_the_base_url_reach_the_same_endpoint(base):+ """MEASURED, and it cost a round: the connected integration stores this base WITHOUT `/v1`,+ the catalog's default matches it, and both adapters build `/v1/…` on top — so a shape that+ concatenated onto whatever was stored would 404 on one of the two spellings. A 404 from a+ provider reads as "it is down", which is the worst kind of wrong answer to have here.++ Pinned both ways round, because the bug is only visible from the spelling nobody used.+ """+ assert media_plane.build_submit(_el("text_to_music"), base,+ {"prompt": "p", "seconds": 10}).url == f"{EL}/music"+ cand = _el("text_to_speech")+ assert media_plane.build_submit(cand, base, {"prompt": "p"}).url \+ == f"{EL}/text-to-speech/{cand['voices'][cand['default_voice']]}"+++def test_a_capability_reports_voice_names_and_not_voice_ids(client, harness, session, provider):+ """`list_capabilities` is how an agent learns what to pass to `voice`, so it has to report the+ thing that is passable. An id is a routing detail and a second spelling of the same choice."""+ by = {c["name"]: c for c in _ok(_call(client, _cred(harness, session),+ "list_capabilities"))["capabilities"]}+ limits = by["text_to_speech"]["limits"]+ cand = _el("text_to_speech")+ assert limits["voices"] == list(cand["voices"]), limits["voices"]+ assert "answers_prompts" not in limits, "the reader was described as a model that answers"+ assert not any(vid in json.dumps(limits) for vid in cand["voices"].values())+ # And the fallback's own row says the thing an agent most needs before it spends.+ app._media_quarantine[cand["model"]] = time.time() + 900+ again = {c["name"]: c for c in _ok(_call(client, _cred(harness, session),+ "list_capabilities"))["capabilities"]}+ assert again["text_to_speech"]["limits"]["answers_prompts"] is True+ assert again["text_to_speech"]["limits"]["voices"] == ["alloy"]+++def test_a_model_that_answers_the_prompt_is_never_the_first_choice_for_speech():+ """Declaration order is the preference, and the preference is a MEASURED one — so it is+ asserted against the MEASUREMENT rather than against the entry that happens to be first.++ "The top entry is the ElevenLabs one" would be satisfied by any entry with that name on it,+ including the same conversational model moved up. What actually matters is the property: the+ model this capability reaches for first must be one that READS the line it is given, and the+ ones that answer it are a fallback.+ """+ cands = media_plane.capability("text_to_speech")["candidates"]+ assert not cands[0].get("answers_prompts"), \+ f"{cands[0]['model']} answers prompts and is ranked first for narration"+ assert any(c.get("answers_prompts") for c in cands[1:]), \+ "the conversational models were deleted rather than demoted; they are a real fallback"+ # And the reason they are a fallback and not a substitute is written down where an agent reads+ # it, not only in a comment here.+ assert "answers_prompts" in media_plane.limits_of(cands[-1])# ══ the canvas ═══════════════════════════════════════════════════════════════════@@ -1769,7 +2160,7 @@ def test_the_app_reads_the_scene_and_the_server_describes_itself(api, harness, sassert desc["id"] == ENTRY_ID and desc["name"] == "media"by = {c["name"]: c for c in desc["capabilities"]}assert by["text_to_video"]["available"] is True- assert by["text_to_music"]["available"] is False+ assert by["text_to_music"]["available"] is Trueassert desc["export"]["available"] is media_plane.have_ffmpeg()assert "connection" not in desc@@ -2220,17 +2611,26 @@ def test_the_provider_key_appears_in_no_response_this_file_produced():"""Every body recorded above, in one assertion. A new route that leaks the key fails here evenif nobody thought to test that route."""assert _seen, "nothing was recorded — the recording client stopped being used"- leaked = [t for t in _seen if PROVIDER_KEY in t]- assert not leaked, f"{len(leaked)} response(s) contained the provider key: {leaked[:1]}"+ leaked = [t for t in _seen if PROVIDER_KEY in t or ELEVEN_KEY in t]+ assert not leaked, f"{len(leaked)} response(s) contained a provider key: {leaked[:1]}"-def test_the_provider_key_reaches_the_provider_and_nothing_else():- """The other half: it DID go out on the wire to the provider, so this is not passing because- nothing was ever called."""+def test_each_provider_key_reaches_its_own_provider_and_nothing_else():+ """The other half: they DID go out on the wire, so this is not passing because nothing was+ ever called — and each went to ONE host, in ONE header, over the whole file.++ Two keys is what makes this worth asserting globally. A single sentinel could not tell "signed+ correctly" from "signed with whatever key was lying around", and a second auth style is+ exactly the change that makes the second thing possible.+ """assert _all_calls, "no provider call was made — this file would pass on an empty mock"outbound = [c for c in _all_calls if "cdn.provider.example" not in c["url"]]- assert outbound and all(c["auth"] == f"Bearer {PROVIDER_KEY}" for c in outbound)- assert all(c["url"].startswith(TR) for c in outbound), "a call went somewhere unexpected"+ tr = [c for c in outbound if c["url"].startswith(TR)]+ el = [c for c in outbound if c["url"].startswith(EL)]+ assert tr and el, "one of the two providers was never called"+ assert len(tr) + len(el) == len(outbound), "a call went somewhere unexpected"+ assert all(c["auth"] == f"Bearer {PROVIDER_KEY}" and not c["xi"] for c in tr)+ assert all(c["xi"] == ELEVEN_KEY and not c["auth"] for c in el)def test_the_provider_key_appears_in_nothing_the_gateway_printed(api, kit, client, provider,@@ -2248,7 +2648,8 @@ def test_the_provider_key_appears_in_nothing_the_gateway_printed(api, kit, clienasyncio.run(app._media_sweep())api.delete(f"/v1/traces/{sid}")out = capsys.readouterr()- assert PROVIDER_KEY not in out.out and PROVIDER_KEY not in out.err+ for key in (PROVIDER_KEY, ELEVEN_KEY):+ assert key not in out.out and key not in out.err# And it did log something identifying, so this is not passing on an empty string.assert "[media]" in out.out@@ -2259,12 +2660,12 @@ def test_the_provider_key_is_on_no_vertex_and_in_no_scene(api, kit, client, prov_ok(_call(client, tok, "generate_image", {"prompt": "a"}))dump = json.dumps(_vertex(hid)) + json.dumps(asyncio.run(app._media_jobs_of(session)))dump += json.dumps(asyncio.run(app._media_scene_read(session)))- assert PROVIDER_KEY not in dump+ assert PROVIDER_KEY not in dump and ELEVEN_KEY not in dump# The secret store holds the integration document, and only the integration document.root = Path(app.BACKING.secrets._root)hits = [p for p in root.rglob("*")- if p.is_file() and PROVIDER_KEY in p.read_text(errors="ignore")- and app._INTEGRATIONS_KEY not in p.name]+ if p.is_file() and app._INTEGRATIONS_KEY not in p.name+ and any(k in p.read_text(errors="ignore") for k in (PROVIDER_KEY, ELEVEN_KEY))]assert hits == [], f"the key was written somewhere it should not be: {hits}"