agent-core-voice 0.8.2__py3-none-any.whl

agent_core_voice/__init__.py

@@ -0,0 +1 @@
+"""agent-core-voice — Qwen3-TTS voice synthesis endpoint for agent_core."""

agent_core_voice/audit.py

@@ -0,0 +1,54 @@
+"""Append-only JSONL audit log for voice synthesis calls.
+
+One line per ``synthesize_speech`` call (success or failure). Schema is
+documented in the design spec. Audit-write failures are swallowed so an
+audit problem never breaks a synthesis call.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from agent_core.audit import JsonlAuditLog
+
+
+@dataclass(frozen=True)
+class AuditEvent:
+    """One line in the voice audit log."""
+
+    timestamp: datetime
+    agent: str
+    voice_id: str
+    text_len: int
+    seed: int
+    duration_s: float | None
+    generation_s: float | None
+    wav_path: str | None
+    error: str | None
+
+
+class AuditLog(JsonlAuditLog[AuditEvent]):
+    """Append-only JSONL audit log."""
+
+    def __init__(self, path: Path) -> None:
+        super().__init__(path)
+
+    def _serialize(self, event: AuditEvent) -> str:
+        payload = {
+            "ts": event.timestamp.isoformat(),
+            "agent": event.agent,
+            "voice_id": event.voice_id,
+            "text_len": event.text_len,
+            "seed": event.seed,
+            "duration_s": event.duration_s,
+            "generation_s": event.generation_s,
+            "wav_path": event.wav_path,
+            "error": event.error,
+        }
+        return json.dumps(payload, ensure_ascii=False)
+
+
+__all__ = ["AuditEvent", "AuditLog"]

agent_core_voice/endpoint.py

@@ -0,0 +1,699 @@
+"""VoiceEndpoint — bus endpoint exposing per-agent synthesis.
+
+Implements the standard Endpoint protocol. ``deliver`` accepts
+``Event`` envelopes whose ``payload.type == "SynthesisRequest"``,
+spawns a background task to run synthesis via ``madrigal.generate``,
+and publishes a correlated ``SynthesisReady`` or ``SynthesisFailed``
+envelope back to the caller. Non-synthesis envelopes are acked and
+ignored.
+
+The endpoint holds the warm TTS backend, the registry of configured
+voices, an agent → voice_id mapping (populated by plugin.py at wire
+time so callers cannot spoof voice ids on the wire), the output
+directory, and the audit log.
+
+Construction wiring:
+
+* Production: bus runner calls ``VoiceEndpoint(name=..., **yaml_params)``
+  which constructs ``madrigal.engine.QwenTTSBackend`` internally.
+* Tests: ``VoiceEndpoint.for_test(backend=fake, voices=..., ...)`` skips
+  the real backend and injects a fake (typically
+  ``madrigal.engine.FakeTTSBackend``).
+
+Synthesis routes through ``madrigal.generate()`` with chunked + parallel
+batching enabled. The endpoint does not call ``backend.synthesize``
+directly; the voice library owns chunking, batching, and wav
+concatenation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import io
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import soundfile as sf
+
+from agent_core.bus.protocol import EndpointUnavailable
+from agent_core_voice.audit import AuditEvent, AuditLog
+from agent_core_voice.lifecycle import transcode_audio
+from agent_core_voice.protocol import (
+    EmptyTextError,
+    GPUOOMError,
+    TextTooLongError,
+    TTSBackend,
+    VoiceError,
+    VoiceInfo,
+    VoiceNotPreparedError,
+)
+
+if TYPE_CHECKING:
+    from agent_core.bus.envelope import Envelope
+    from agent_core.bus.handle import BusHandle
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class SynthesisSuccess:
+    """Successful synthesis result."""
+
+    path: str
+    duration_s: float
+    generation_s: float
+    sample_rate: int
+
+
+@dataclass(frozen=True)
+class SynthesisError:
+    """Failed synthesis — message is the agent-readable string."""
+
+    message: str
+
+
+class _WavPhaseError(Exception):
+    """Internal marker for failures in the wav decode/write phase.
+
+    Wraps the underlying OSError/RuntimeError so ``_error_message`` can
+    distinguish wav-phase failures from arbitrary backend RuntimeErrors.
+    """
+
+    def __init__(self, wrapped: BaseException) -> None:
+        super().__init__(str(wrapped))
+        self.wrapped = wrapped
+
+
+class VoiceEndpoint:
+    """Tool-only bus endpoint backing the voice MCP tool surface."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        backend: TTSBackend | None = None,
+        voices: dict[str, VoiceInfo] | dict[str, dict] | None = None,
+        output_dir: Path | str,
+        audit_path: Path | str,
+        max_text_len: int = 2000,
+        # Real-backend params, only used when backend is None:
+        model_path: str | None = None,
+        device: str = "cuda:0",
+        attn_implementation: str = "sdpa",
+    ) -> None:
+        self._name = name
+        self._handle: BusHandle | None = None
+        self._max_text_len = max_text_len
+        # Plugin.py populates this at wire time; envelope handler uses it to
+        # resolve envelope.from_ → voice_id without trusting caller-supplied
+        # voice ids on the wire.
+        self._agent_to_voice: dict[str, str] = {}
+
+        # Fail-fast on misconfiguration: production path needs model_path.
+        if backend is None and model_path is None:
+            raise ValueError(
+                "VoiceEndpoint requires either backend=... (tests) or "
+                "model_path=... (production with QwenTTSBackend)"
+            )
+
+        # Store the pre-built backend (test path) or None (production path, built in start()).
+        self._backend: TTSBackend | None = backend
+
+        # Store production-path params for lazy use in start().
+        self._model_path = model_path
+        self._device = device
+        self._attn_implementation = attn_implementation
+
+        # Normalize voices: yaml gives dict[str, dict]; tests give dict[str, VoiceInfo].
+        # Expand ~ in all paths so yaml configs can use "~/.agent-core/..." cleanly.
+        normalized: dict[str, VoiceInfo] = {}
+        for vid, raw in (voices or {}).items():
+            if isinstance(raw, VoiceInfo):
+                normalized[vid] = raw
+            else:
+                normalized[vid] = VoiceInfo(
+                    voice_id=vid,
+                    ref_wav=Path(raw["ref_wav"]).expanduser(),
+                    ref_text=raw["ref_text"],
+                    blend=raw.get("blend"),
+                )
+        self._voices = normalized
+
+        self._output_dir = Path(output_dir).expanduser()
+        self._audit = AuditLog(Path(audit_path).expanduser())
+        self._output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Backend construction and voice warming are deferred to start().
+
+    @classmethod
+    def for_test(
+        cls,
+        *,
+        backend: TTSBackend,
+        voices: dict[str, VoiceInfo],
+        output_dir: Path | str,
+        audit_path: Path | str,
+        name: str = "voice_test",
+        max_text_len: int = 2000,
+    ) -> VoiceEndpoint:
+        """Test seam — same constructor, explicit name default."""
+        return cls(
+            name=name,
+            backend=backend,
+            voices=voices,
+            output_dir=output_dir,
+            audit_path=audit_path,
+            max_text_len=max_text_len,
+        )
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def voice_ids(self) -> set[str]:
+        return set(self._voices.keys())
+
+    def register_agent(self, agent_name: str, voice_id: str) -> None:
+        """Bind an agent name → voice_id mapping.
+
+        Plugin.py calls this at wire time (before bus.start). The envelope
+        handler uses the mapping to resolve which voice an inbound
+        ``envelope.from_`` is allowed to use — voice_id is endpoint-closed
+        and never trusted from the wire.
+        """
+        if voice_id not in self._voices:
+            raise ValueError(
+                f"voice_id={voice_id!r} not configured; "
+                f"available: {sorted(self._voices.keys())}"
+            )
+        self._agent_to_voice[agent_name] = voice_id
+
+    def voice_info(self, voice_id: str) -> dict[str, Any]:
+        info = self._voices[voice_id]
+        return {
+            "voice_id": info.voice_id,
+            "ref_clip": str(info.ref_wav),
+            "ref_text": info.ref_text,
+            "blend": info.blend,
+            "sample_rate": 24000,
+            "mode": "1.7B Base + ICL voice clone",
+        }
+
+    async def cleanup_tick(self) -> int:
+        """Sweep expired WAVs from the output directory. Returns count removed.
+
+        Called periodically (every 5 min by the scheduler endpoint) to enforce
+        the file lifecycle policy. Safe to call manually for tests or ops.
+
+        NOTE: Wire this in production by adding a scheduler job to
+        ``~/.agent-core/jobs.yaml`` that targets the voice endpoint and calls
+        ``cleanup_tick()`` every 5 minutes. Exact yaml shape depends on the
+        scheduler endpoint's job format — check
+        ``agent_core/endpoints/scheduler.py`` for the current schema.
+        """
+        from agent_core_voice.lifecycle import cleanup_expired
+
+        return await asyncio.to_thread(cleanup_expired, root=self._output_dir)
+
+    async def synthesize_safe(
+        self,
+        *,
+        agent_name: str,
+        voice_id: str,
+        text: str,
+        seed: int,
+    ) -> SynthesisSuccess | SynthesisError:
+        """Synthesize via ``madrigal.generate()`` (chunked + parallel-batched).
+
+        Never raises. All failures land as ``SynthesisError(message=...)``.
+        """
+        # Lazy-import to keep module import cheap and to honor the
+        # backend-swap boundary: madrigal is the runtime dep, not a hard
+        # import-time dep for tests that only touch protocol/audit code.
+        from madrigal import Spec, generate
+
+        now = datetime.now(UTC)
+
+        # Endpoint-level text validation. The chunker would also raise on
+        # empty input, but doing the pre-check here keeps the error path
+        # uniform (single error class, audited identically) regardless of
+        # whether chunking is enabled.
+        if not text or not text.strip():
+            return await self._record_error(
+                now, agent_name, voice_id, text, seed, EmptyTextError("text is empty")
+            )
+        if len(text) > self._max_text_len:
+            return await self._record_error(
+                now,
+                agent_name,
+                voice_id,
+                text,
+                seed,
+                TextTooLongError(
+                    f"text length {len(text)} exceeds endpoint budget {self._max_text_len}"
+                ),
+            )
+
+        try:
+            result = await asyncio.to_thread(
+                generate,
+                text,
+                Spec(
+                    voice_id=voice_id,
+                    seed=seed,
+                    chunk_strategy="sentence",
+                    parallel=True,
+                ),
+                backend=self._backend,
+            )
+        except VoiceError as exc:
+            return await self._record_error(now, agent_name, voice_id, text, seed, exc)
+        except Exception as exc:  # defensive — unknown backend/library failure
+            log.exception("madrigal.generate raised unexpected exception")
+            return await self._record_error(now, agent_name, voice_id, text, seed, exc)
+
+        wav_bytes = result.audio
+        if wav_bytes is None:
+            return await self._record_error(
+                now,
+                agent_name,
+                voice_id,
+                text,
+                seed,
+                _WavPhaseError(RuntimeError("madrigal returned no audio bytes")),
+            )
+
+        try:
+            duration_s, sample_rate = self._wav_duration(wav_bytes)
+            path = self._next_output_path(agent_name, seed, text, now)
+            await asyncio.to_thread(path.write_bytes, wav_bytes)
+        except (OSError, RuntimeError) as exc:
+            return await self._record_error(
+                now, agent_name, voice_id, text, seed, _WavPhaseError(exc)
+            )
+
+        # generation_s = sum of per-chunk wall times reported by the
+        # backend (madrigal exposes these in result.timings). When timings
+        # are absent (cache hit, sequential single-call path on some
+        # backends) we fall back to 0.0; callers should treat
+        # generation_s as a hint, not a guarantee.
+        generation_s = float(sum(result.timings)) if result.timings else 0.0
+
+        await self._audit.write(
+            AuditEvent(
+                timestamp=now,
+                agent=agent_name,
+                voice_id=voice_id,
+                text_len=len(text),
+                seed=seed,
+                duration_s=duration_s,
+                generation_s=generation_s,
+                wav_path=str(path),
+                error=None,
+            )
+        )
+        return SynthesisSuccess(
+            path=str(path),
+            duration_s=duration_s,
+            generation_s=generation_s,
+            sample_rate=sample_rate,
+        )
+
+    async def _record_error(
+        self,
+        now: datetime,
+        agent_name: str,
+        voice_id: str,
+        text: str,
+        seed: int,
+        exc: BaseException,
+    ) -> SynthesisError:
+        message = self._error_message(exc)
+        await self._audit.write(
+            AuditEvent(
+                timestamp=now,
+                agent=agent_name,
+                voice_id=voice_id,
+                text_len=len(text),
+                seed=seed,
+                duration_s=None,
+                generation_s=None,
+                wav_path=None,
+                error=message,
+            )
+        )
+        return SynthesisError(message=message)
+
+    @staticmethod
+    def _error_message(exc: BaseException) -> str:
+        if isinstance(exc, EmptyTextError):
+            return "text is empty"
+        if isinstance(exc, TextTooLongError):
+            return f"text exceeds model budget ({exc})"
+        if isinstance(exc, GPUOOMError):
+            return "GPU is out of memory; try again in a moment"
+        if isinstance(exc, VoiceNotPreparedError):
+            return str(exc)
+        if isinstance(exc, _WavPhaseError):
+            wrapped = exc.wrapped
+            if isinstance(wrapped, OSError):
+                return f"output directory is not writable: {wrapped}"
+            return f"wav decode/write failed: {wrapped}"
+        if isinstance(exc, OSError):
+            return f"output directory is not writable: {exc}"
+        return f"{type(exc).__name__}: {exc}"
+
+    def _next_output_path(self, agent_name: str, seed: int, text: str, now: datetime) -> Path:
+        day = now.strftime("%Y-%m-%d")
+        ts = now.strftime("%Y%m%dT%H%M%S_%f")
+        text_hash = hashlib.sha256(text.encode("utf-8")).hexdigest()[:8]
+        dir_ = self._output_dir / agent_name / day
+        dir_.mkdir(parents=True, exist_ok=True)
+        return dir_ / f"{ts}-{seed}-{text_hash}.wav"
+
+    @staticmethod
+    def _wav_duration(wav_bytes: bytes) -> tuple[float, int]:
+        with sf.SoundFile(io.BytesIO(wav_bytes)) as f:
+            return f.frames / float(f.samplerate), int(f.samplerate)
+
+    # Endpoint protocol implementation.
+    async def start(self, bus: BusHandle) -> None:
+        self._handle = bus
+        if self._backend is None:
+            # Production path: build the GPU/CPU backend off the event loop thread.
+            # asyncio.to_thread keeps the loop responsive during the (potentially
+            # multi-second) model load.
+            from madrigal.engine import QwenTTSBackend
+
+            self._backend = await asyncio.to_thread(
+                QwenTTSBackend,
+                model_path=self._model_path,
+                device=self._device,
+                attn_implementation=self._attn_implementation,
+            )
+        # Warm all configured voices (no-op cost for fake backends; off-thread
+        # for real backends so WAV encoding doesn't block the loop).
+        for voice_id, info in self._voices.items():
+            await asyncio.to_thread(
+                self._backend.prepare_voice, voice_id, Path(info.ref_wav), info.ref_text
+            )
+            log.info("voice %r prepared (ref_wav=%s)", voice_id, info.ref_wav)
+        log.info("VoiceEndpoint(name=%s) started; output_dir=%s", self._name, self._output_dir)
+
+    async def deliver(self, envelope: Envelope) -> None:
+        """Route SynthesisRequest envelopes to a background task; ack others.
+
+        We return from ``deliver`` promptly (per Endpoint protocol contract)
+        and let the synthesis run in an asyncio task. The bus is then free
+        to dispatch to other endpoints while the GPU is busy.
+        """
+        if self._backend is None:
+            # start() has not yet completed. This should not happen in production
+            # (bus awaits start() before draining mail), but fail safe rather than crash.
+            raise EndpointUnavailable(
+                f"VoiceEndpoint(name={self._name!r}): backend not ready — start() not yet complete"
+            )
+        if (
+            envelope.kind != "Event"
+            or not hasattr(envelope.payload, "type")
+            or envelope.payload.type != "SynthesisRequest"
+        ):
+            log.debug(
+                "VoiceEndpoint(name=%s) ignoring envelope %s (kind=%s, payload_type=%s)",
+                self._name,
+                envelope.id,
+                envelope.kind,
+                getattr(envelope.payload, "type", None),
+            )
+            if self._handle is not None:
+                await self._handle.ack(envelope.id)
+            return
+
+        from agent_core_voice.envelopes import SynthesisRequestPayload
+
+        try:
+            req = SynthesisRequestPayload.model_validate(envelope.payload.data)
+        except Exception as exc:
+            log.warning(
+                "VoiceEndpoint(name=%s) rejected malformed SynthesisRequest %s: %s",
+                self._name,
+                envelope.id,
+                exc,
+            )
+            await self._publish_failed(
+                envelope,
+                reason="INTERNAL_ERROR",
+                message=f"invalid SynthesisRequest payload: {exc}",
+                retryable=False,
+            )
+            if self._handle is not None:
+                await self._handle.ack(envelope.id)
+            return
+
+        # Ack the request envelope NOW (before spawning the worker) so the
+        # bus doesn't treat synthesis-wall-time as an in-flight timeout.
+        # The Ready/Failed envelopes we emit later are separate envelopes
+        # correlated via in_reply_to=<request.id>, not the same envelope.
+        if self._handle is not None:
+            await self._handle.ack(envelope.id)
+
+        # Spawn-and-forget — synthesis can take ~60s; the bus must not block.
+        self._handle.spawn(
+            self._handle_synthesis_request(envelope, req),
+            name=f"voice-synthesis-{envelope.id}",
+        )
+
+    async def stop(self) -> None:
+        self._handle = None
+        log.info("VoiceEndpoint(name=%s) stopped", self._name)
+
+    async def _handle_synthesis_request(
+        self,
+        envelope: Envelope,
+        req: Any,  # SynthesisRequestPayload — typed via local import to avoid module-level cycle
+    ) -> None:
+        """Run synthesis in a thread, publish Ready/Failed, then ack."""
+        from madrigal import Spec, generate
+
+        from agent_core_voice.envelopes import SynthesisReadyPayload
+        from agent_core_voice.lifecycle import retain_until_iso, write_addressed
+
+        agent_name = envelope.from_
+        voice_id = self._agent_to_voice.get(agent_name)
+        if voice_id is None:
+            await self._publish_failed(
+                envelope,
+                reason="VOICE_NOT_PREPARED",
+                message=(
+                    f"no voice configured for agent {agent_name!r}; "
+                    f"call VoiceEndpoint.register_agent at wire time"
+                ),
+                retryable=False,
+            )
+            return
+
+        timeout_s = req.timeout_s if req.timeout_s is not None else 300.0
+        retain_s = req.retain_s if req.retain_s is not None else 3600.0
+        options = req.options or {}
+        spec = Spec(
+            voice_id=voice_id,
+            seed=int(options.get("seed", 42)),
+            chunk_strategy=options.get("chunk_strategy", "sentence"),
+            parallel=bool(options.get("parallel", True)),
+        )
+
+        try:
+            result = await asyncio.wait_for(
+                asyncio.to_thread(generate, req.text, spec, backend=self._backend),
+                timeout=timeout_s,
+            )
+        except TimeoutError:
+            await self._publish_failed(
+                envelope,
+                reason="TIMEOUT",
+                message=f"synthesis exceeded timeout_s={timeout_s}",
+                retryable=True,
+            )
+            return
+        except VoiceError as exc:
+            await self._publish_failed_from_voiceerror(envelope, exc)
+            return
+        except Exception as exc:
+            log.exception("madrigal.generate raised unexpected exception")
+            await self._publish_failed(
+                envelope,
+                reason="INTERNAL_ERROR",
+                message=f"{type(exc).__name__}: {exc}",
+                retryable=False,
+            )
+            return
+
+        wav_bytes = result.audio
+        if wav_bytes is None:
+            await self._publish_failed(
+                envelope,
+                reason="INTERNAL_ERROR",
+                message="madrigal.generate returned no audio bytes",
+                retryable=False,
+            )
+            return
+
+        audio_format = getattr(req, "format", "wav") or "wav"
+
+        try:
+            # Measure duration on the original WAV bytes (soundfile reads WAV reliably).
+            duration_s, _sr_from_wav = self._wav_duration(wav_bytes)
+            # Transcode to the requested format (no-op for wav).
+            audio_bytes = await asyncio.to_thread(
+                transcode_audio, wav_bytes, target_format=audio_format
+            )
+            wav_path, _sha = await asyncio.to_thread(
+                write_addressed,
+                audio_bytes,
+                root=self._output_dir,
+                retain_s=retain_s,
+                ext=audio_format,
+            )
+        except (OSError, RuntimeError, ValueError) as exc:
+            await self._publish_failed(
+                envelope,
+                reason="INTERNAL_ERROR",
+                message=f"audio write/transcode failed: {exc}",
+                retryable=False,
+            )
+            return
+
+        # Reply-emitting tail. Everything here — stat(), model_dump(), envelope
+        # construction, publish — must still yield a terminal reply on failure:
+        # this runs in a spawned task, so an unhandled exception dies silently
+        # and the requesting agent waits forever. Route any failure through
+        # _publish_failed, and guard (don't assert) a torn-down handle.
+        try:
+            # Derive metadata from the madrigal Result. Timings list gives us
+            # per-chunk wall times — sum for elapsed_s, count for chunks.
+            timings = result.timings or []
+            elapsed_s = float(sum(timings))
+            sample_rate = int(result.sample_rate_hz)
+            chunks = max(1, len(timings))  # at least one chunk even on cache hit
+
+            ready_payload = SynthesisReadyPayload(
+                wav_path=str(wav_path),
+                file_size_bytes=wav_path.stat().st_size,
+                duration_s=duration_s,
+                elapsed_s=elapsed_s,
+                sample_rate_hz=sample_rate,
+                cache_hit=bool(result.cache_hit),
+                chunks=chunks,
+                retain_until=retain_until_iso(retain_s=retain_s),
+            )
+
+            import uuid as _uuid
+
+            from agent_core.bus.envelope import Envelope as BusEnvelope
+            from agent_core.bus.envelope import EventPayload
+
+            ready = BusEnvelope(
+                id=_uuid.uuid4().hex,
+                correlation_id=envelope.correlation_id,
+                in_reply_to=envelope.id,
+                to=envelope.from_,
+                kind="Event",
+                payload=EventPayload(
+                    type="SynthesisReady",
+                    data=ready_payload.model_dump(),
+                ),
+                created_at=datetime.now(UTC),
+            )
+
+            if self._handle is None:
+                # The endpoint was stopped before we could reply; there is no
+                # channel left to publish on. Log rather than raise.
+                log.warning(
+                    "voice handle torn down before SynthesisReady for %s; cannot reply",
+                    envelope.id,
+                )
+                return
+            await self._handle.publish(ready)
+        except Exception as exc:
+            log.exception("failed to emit SynthesisReady")
+            await self._publish_failed(
+                envelope,
+                reason="INTERNAL_ERROR",
+                message=f"failed to emit SynthesisReady: {type(exc).__name__}: {exc}",
+                retryable=False,
+            )
+
+    async def _publish_failed(
+        self,
+        request_env: Envelope,
+        *,
+        reason: str,
+        message: str,
+        retryable: bool,
+    ) -> None:
+        """Build + publish a SynthesisFailed envelope correlated with the request."""
+        from agent_core.bus.envelope import Envelope as BusEnvelope
+        from agent_core.bus.envelope import EventPayload
+        from agent_core_voice.envelopes import SynthesisFailedPayload
+
+        if self._handle is None:
+            log.error(
+                "VoiceEndpoint(name=%s) cannot publish failure (handle unset) "
+                "for request %s: %s",
+                self._name,
+                request_env.id,
+                message,
+            )
+            return
+
+        import uuid as _uuid
+
+        failed = BusEnvelope(
+            id=_uuid.uuid4().hex,
+            correlation_id=request_env.correlation_id,
+            in_reply_to=request_env.id,
+            to=request_env.from_,
+            kind="Event",
+            payload=EventPayload(
+                type="SynthesisFailed",
+                data=SynthesisFailedPayload(
+                    reason=reason,  # type: ignore[arg-type]
+                    message=message,
+                    retryable=retryable,
+                ).model_dump(),
+            ),
+            created_at=datetime.now(UTC),
+        )
+        await self._handle.publish(failed)
+
+    async def _publish_failed_from_voiceerror(
+        self,
+        request_env: Envelope,
+        exc: VoiceError,
+    ) -> None:
+        """Map a VoiceError subclass onto the failure-reason taxonomy."""
+        reason = "INTERNAL_ERROR"
+        retryable = False
+        if isinstance(exc, GPUOOMError):
+            reason, retryable = "GPU_OOM", True
+        elif isinstance(exc, TextTooLongError):
+            reason = "TEXT_TOO_LONG"
+        elif isinstance(exc, VoiceNotPreparedError):
+            reason = "VOICE_NOT_PREPARED"
+        await self._publish_failed(
+            request_env,
+            reason=reason,
+            message=str(exc),
+            retryable=retryable,
+        )
+
+
+__all__ = [
+    "SynthesisError",
+    "SynthesisSuccess",
+    "VoiceEndpoint",
+]

agent_core_voice/envelopes.py

@@ -0,0 +1,85 @@
+"""Pydantic payload models for voice endpoint envelopes.
+
+Three event types ride on top of agent_core's Event kind:
+
+- SynthesisRequest (caller → voice)
+- SynthesisReady (voice → caller, success)
+- SynthesisFailed (voice → caller, failure)
+
+Validation runs at envelope publish/parse time so malformed requests
+surface as ValidationError to the publisher rather than as opaque
+runtime failures downstream.
+
+See spec §4 for the wire-level contract.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+_TIMEOUT_S_CAP = 600.0
+_RETAIN_S_CAP = 86400.0
+
+AudioFormat = Literal["wav", "mp3", "ogg"]
+
+
+class SynthesisRequestPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    text: str = Field(min_length=1)
+    timeout_s: float | None = Field(default=None, gt=0)
+    retain_s: float | None = Field(default=None, gt=0)
+    options: dict[str, Any] | None = None
+    format: AudioFormat = "wav"
+
+    @field_validator("timeout_s")
+    @classmethod
+    def _cap_timeout(cls, v: float | None) -> float | None:
+        if v is not None and v > _TIMEOUT_S_CAP:
+            raise ValueError(f"timeout_s exceeds 600s cap (got {v})")
+        return v
+
+    @field_validator("retain_s")
+    @classmethod
+    def _cap_retain(cls, v: float | None) -> float | None:
+        if v is not None and v > _RETAIN_S_CAP:
+            raise ValueError(f"retain_s exceeds 86400s cap (got {v})")
+        return v
+
+
+class SynthesisReadyPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    wav_path: str = Field(min_length=1)
+    file_size_bytes: int = Field(ge=0)
+    duration_s: float = Field(ge=0)
+    elapsed_s: float = Field(ge=0)
+    sample_rate_hz: int = Field(gt=0)
+    cache_hit: bool
+    chunks: int = Field(ge=1)
+    retain_until: str = Field(min_length=1)
+
+
+FailureReason = Literal[
+    "GPU_OOM",
+    "TEXT_TOO_LONG",
+    "VOICE_NOT_PREPARED",
+    "INTERNAL_ERROR",
+    "TIMEOUT",
+]
+
+
+class SynthesisFailedPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    reason: FailureReason
+    message: str = Field(min_length=1)
+    retryable: bool
+
+
+__all__ = [
+    "AudioFormat",
+    "FailureReason",
+    "SynthesisFailedPayload",
+    "SynthesisReadyPayload",
+    "SynthesisRequestPayload",
+]

agent_core_voice/lifecycle.py

@@ -0,0 +1,144 @@
+"""File lifecycle for voice WAVs: content-addressed write + TTL cleanup."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import logging
+import subprocess
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+
+def transcode_audio(wav_bytes: bytes, *, target_format: str) -> bytes:
+    """Transcode WAV bytes to the requested format.
+
+    Returns ``wav_bytes`` unchanged for ``"wav"``. Encodes to OGG Vorbis
+    using ``soundfile`` for ``"ogg"``. Shells out to ``ffmpeg`` for ``"mp3"``.
+
+    Raises:
+        ValueError: if ``target_format`` is not ``"wav"``, ``"mp3"``, or ``"ogg"``.
+        RuntimeError: if ffmpeg is not on PATH or exits non-zero.
+    """
+    if target_format == "wav":
+        return wav_bytes
+
+    if target_format == "ogg":
+        import soundfile as sf
+
+        import numpy as np
+
+        with sf.SoundFile(io.BytesIO(wav_bytes)) as f:
+            audio_data = f.read(dtype="float32")
+            sample_rate = f.samplerate
+        buf = io.BytesIO()
+        sf.write(buf, audio_data, sample_rate, format="OGG", subtype="VORBIS")
+        return buf.getvalue()
+
+    if target_format == "mp3":
+        try:
+            result = subprocess.run(
+                [
+                    "ffmpeg",
+                    "-f", "wav",
+                    "-i", "pipe:0",
+                    "-f", "mp3",
+                    "-b:a", "128k",
+                    "pipe:1",
+                ],
+                input=wav_bytes,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            raise RuntimeError(f"ffmpeg not found on PATH: {exc}") from exc
+
+        if result.returncode != 0:
+            stderr_fragment = (result.stderr or b"")[:500].decode("utf-8", errors="replace")
+            raise RuntimeError(
+                f"ffmpeg exited with code {result.returncode}: {stderr_fragment}"
+            )
+        return result.stdout
+
+    raise ValueError(f"unknown target_format {target_format!r}; expected 'wav', 'mp3', or 'ogg'")
+
+
+def write_addressed(
+    audio: bytes,
+    *,
+    root: Path,
+    retain_s: float,
+    ext: str = "wav",
+) -> tuple[Path, str]:
+    """Write ``audio`` to ``<root>/<sha256>.<ext>`` with a meta sidecar.
+
+    Returns (path, sha256_hex). The audio body is content-addressed and
+    only written if not already present (so identical audio dedupes).
+    The meta sidecar IS rewritten on every call, refreshing
+    ``written_at_utc`` and effectively resetting the TTL window —
+    LRU-ish semantics: actively-touched files stay alive longer.
+
+    The meta JSON includes an ``"ext"`` key so ``cleanup_expired()`` can
+    locate the companion audio file regardless of format.
+    """
+    sha = hashlib.sha256(audio).hexdigest()
+    root.mkdir(parents=True, exist_ok=True)
+    audio_path = root / f"{sha}.{ext}"
+    meta_path = root / f"{sha}.meta.json"
+
+    if not audio_path.exists():
+        audio_path.write_bytes(audio)
+
+    meta = {
+        "sha256": sha,
+        "retain_s": retain_s,
+        "written_at_utc": datetime.now(UTC).isoformat(),
+        "ext": ext,
+    }
+    meta_path.write_text(json.dumps(meta))
+    return audio_path, sha
+
+
+def retain_until_iso(*, retain_s: float, now: datetime | None = None) -> str:
+    """Compute ISO 8601 UTC timestamp of ``now + retain_s``."""
+    base = now or datetime.now(UTC)
+    return (base + timedelta(seconds=retain_s)).isoformat()
+
+
+def cleanup_expired(*, root: Path) -> int:
+    """Walk ``root``, delete WAVs whose ``written_at_utc + retain_s < now``.
+
+    The deadline is read from the meta sidecar (``written_at_utc`` field),
+    not the filesystem mtime, so it survives backup/restore. Returns
+    count removed. Safe to call on a nonexistent root.
+    """
+    if not root.exists():
+        return 0
+    now = datetime.now(UTC)
+    removed = 0
+    for meta_path in root.glob("*.meta.json"):
+        try:
+            meta = json.loads(meta_path.read_text())
+            written = datetime.fromisoformat(meta["written_at_utc"])
+            retain_s = float(meta["retain_s"])
+        except (OSError, ValueError, KeyError) as exc:
+            log.warning("skipping malformed meta %s: %s", meta_path, exc)
+            continue
+        if written + timedelta(seconds=retain_s) < now:
+            ext = meta.get("ext", "wav")
+            audio_path = meta_path.with_suffix("").with_suffix(f".{ext}")
+            try:
+                if audio_path.exists():
+                    audio_path.unlink()
+                meta_path.unlink()
+                removed += 1
+            except OSError as exc:
+                log.warning("failed to remove %s: %s", audio_path, exc)
+    return removed
+
+
+__all__ = ["cleanup_expired", "retain_until_iso", "transcode_audio", "write_addressed"]

agent_core_voice/mcp.py

@@ -0,0 +1,121 @@
+"""Agent-facing MCP tool surface for the voice endpoint (async-via-bus).
+
+Two tools: ``synthesize_speech`` and ``voice_info``. Both close ``voice_id``
+and ``agent_name`` into their callable at mount time. The agent's tool
+surface has no ``voice_id`` parameter — by construction, an agent cannot
+request another agent's voice.
+
+``synthesize_speech`` is **publish-and-return**: it builds a
+``SynthesisRequest`` envelope, publishes it to the voice endpoint via the
+caller's ``BusHandle``, and returns ``{"request_id", "status": "queued"}``
+immediately. The caller's inbox wakes when a correlated
+``SynthesisReady`` (success) or ``SynthesisFailed`` (failure) arrives.
+
+Returns a list of MCP TextContent blocks. No exceptions escape the tool —
+client-side validation errors surface as ``{"error", "detail"}`` JSON.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from mcp.types import TextContent
+
+from agent_core_voice.envelopes import SynthesisRequestPayload
+
+if TYPE_CHECKING:
+    from agent_core.bus.handle import BusHandle
+    from fastmcp import FastMCP
+
+
+def register_voice_tools(
+    *,
+    mcp: FastMCP,
+    bus_handle: BusHandle,
+    voice_endpoint_name: str,
+    voice_id: str,
+    agent_name: str,
+    voice_info: dict[str, Any],
+) -> None:
+    """Mount ``synthesize_speech`` (envelope-fire) + ``voice_info`` on ``mcp``.
+
+    ``voice_id``, ``agent_name``, and the target voice endpoint name are
+    closed at mount time. Synthesis is async-via-bus: the tool publishes a
+    ``SynthesisRequest`` envelope and returns the envelope id immediately.
+    The caller's inbox wakes when a ``SynthesisReady`` (or
+    ``SynthesisFailed``) arrives.
+    """
+    # ``agent_name`` and ``voice_id`` are accepted for closure parity with the
+    # pre-bus-async signature (callers in plugin.py thread them through), but
+    # they're not used by the bus path: bus stamps ``from_`` on publish, and
+    # the voice endpoint resolves voice_id by looking up the agent it
+    # registered at wire time.
+    del agent_name, voice_id
+
+    @mcp.tool(
+        name="synthesize_speech",
+        description=(
+            "Synthesize text in your assigned voice. Returns {request_id, status} "
+            "immediately; the synthesized audio arrives on your inbox as a "
+            "SynthesisReady event with `wav_path`. SynthesisFailed arrives on the "
+            "same inbox if synthesis fails. "
+            "``format`` selects the output container: \"wav\" (default), \"mp3\", or \"ogg\"."
+        ),
+    )
+    async def _synthesize(
+        text: str,
+        timeout_s: float | None = None,
+        retain_s: float | None = None,
+        options: dict | None = None,
+        format: str = "wav",
+    ) -> list[Any]:
+        from agent_core.bus.envelope import Envelope, EventPayload
+
+        try:
+            payload = SynthesisRequestPayload(
+                text=text,
+                timeout_s=timeout_s,
+                retain_s=retain_s,
+                options=options,
+                format=format,  # type: ignore[arg-type]
+            )
+        except Exception as exc:  # pydantic ValidationError or anything else
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps({"error": "invalid_request", "detail": str(exc)}),
+                )
+            ]
+
+        env_id = str(uuid.uuid4())
+        env = Envelope(
+            id=env_id,
+            correlation_id=env_id,
+            to=voice_endpoint_name,
+            kind="Event",
+            payload=EventPayload(
+                type="SynthesisRequest",
+                data=payload.model_dump(exclude_none=True),
+            ),
+            created_at=datetime.now(UTC),
+        )
+        await bus_handle.publish(env)
+        return [
+            TextContent(
+                type="text",
+                text=json.dumps({"request_id": env_id, "status": "queued"}),
+            )
+        ]
+
+    @mcp.tool(
+        name="voice_info",
+        description="Return metadata about your assigned voice.",
+    )
+    async def _voice_info() -> list[Any]:
+        return [TextContent(type="text", text=json.dumps(voice_info, ensure_ascii=False))]
+
+
+__all__ = ["register_voice_tools"]

agent_core_voice/plugin.py

@@ -0,0 +1,123 @@
+"""Agent_core entry-point hook surface for the voice service.
+
+Three hookimpls:
+
+* ``register_endpoint_types`` — exposes ``builtin.voice`` so the bus
+  runner can construct a ``VoiceEndpoint`` from a yaml entry.
+* ``reserved_endpoint_params`` — declares ``voice`` and ``voice_id`` so
+  the runner pops them from claude_code_mcp's params before constructing.
+* ``wire_endpoints_after_registration`` — added in Task 10. For each
+  ``ClaudeCodeMCPEndpoint`` whose yaml params name a voice, validate
+  and append a deferred mounter that registers the voice tools on the
+  MCP server with ``voice_id`` closed in.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pluggy
+
+if TYPE_CHECKING:
+    from agent_core.bus.protocol import Endpoint
+    from agent_core.plugins.specs import RunnerServices
+
+hookimpl = pluggy.HookimplMarker("agent_core")
+
+
+@hookimpl
+def register_endpoint_types() -> dict[str, type[Any]]:
+    """Register ``builtin.voice`` as a bus endpoint type."""
+    from agent_core_voice.endpoint import VoiceEndpoint
+
+    return {"builtin.voice": VoiceEndpoint}
+
+
+@hookimpl
+def reserved_endpoint_params() -> list[str]:
+    """The runner pops these keys from each endpoint's params before constructing."""
+    return ["voice", "voice_id"]
+
+
+def _resolve_claude_code_mcp_cls() -> type[Any]:
+    """Lazy import; overridable by tests via monkeypatch."""
+    from agent_core.endpoints.claude_code_mcp import ClaudeCodeMCPEndpoint
+
+    return ClaudeCodeMCPEndpoint
+
+
+@hookimpl
+def wire_endpoints_after_registration(
+    endpoints: dict[str, Endpoint],
+    raw_endpoint_configs: dict[str, dict[str, Any]],
+    services: RunnerServices,
+) -> None:
+    """Mount voice tools on every MCP endpoint that names a voice + voice_id."""
+    del services  # unused — kept for hookspec parity
+
+    from agent_core_voice.endpoint import VoiceEndpoint
+    from agent_core_voice.mcp import register_voice_tools
+
+    claude_code_mcp_cls = _resolve_claude_code_mcp_cls()
+
+    for name, endpoint in endpoints.items():
+        if not isinstance(endpoint, claude_code_mcp_cls):
+            continue
+        raw = raw_endpoint_configs.get(name) or {}
+        params = raw.get("params") or {}
+        voice_name = params.get("voice")
+        voice_id = params.get("voice_id")
+
+        if not voice_name and not voice_id:
+            continue
+        if not voice_name or not voice_id:
+            raise ValueError(
+                f"endpoint {name!r} sets one of 'voice'/'voice_id' but not both; "
+                f"got voice={voice_name!r}, voice_id={voice_id!r}"
+            )
+
+        voice_ep = endpoints.get(voice_name)
+        if voice_ep is None:
+            available = sorted(n for n, e in endpoints.items() if isinstance(e, VoiceEndpoint))
+            raise ValueError(
+                f"endpoint {name!r} names voice={voice_name!r} but no endpoint with that "
+                f"name is registered. Available VoiceEndpoint names: {available}"
+            )
+        if not isinstance(voice_ep, VoiceEndpoint):
+            available = sorted(n for n, e in endpoints.items() if isinstance(e, VoiceEndpoint))
+            raise ValueError(
+                f"endpoint {name!r} names voice={voice_name!r}, but that endpoint is a "
+                f"{type(voice_ep).__name__}, not a VoiceEndpoint. "
+                f"Available VoiceEndpoint names: {available}"
+            )
+        if voice_id not in voice_ep.voice_ids():
+            available = sorted(voice_ep.voice_ids())
+            raise ValueError(
+                f"endpoint {name!r} requests voice_id={voice_id!r} but voice endpoint "
+                f"{voice_name!r} has no such voice. Available voice ids: {available}"
+            )
+
+        # Bind agent → voice_id at wire time so the voice endpoint's
+        # envelope handler can resolve envelope.from_ to a voice without
+        # trusting caller-supplied voice ids on the wire.
+        voice_ep.register_agent(name, voice_id)
+
+        def _mounter(
+            bus_handle,
+            *,
+            voice_ep: VoiceEndpoint = voice_ep,
+            voice_endpoint_name: str = voice_name,
+            mcp_endpoint=endpoint,
+            voice_id: str = voice_id,
+            agent_name: str = name,
+        ) -> None:
+            register_voice_tools(
+                mcp=mcp_endpoint._mcp,
+                bus_handle=bus_handle,
+                voice_endpoint_name=voice_endpoint_name,
+                voice_id=voice_id,
+                agent_name=agent_name,
+                voice_info=voice_ep.voice_info(voice_id),
+            )
+
+        endpoint.deferred_tool_mounters.append(_mounter)

agent_core_voice/protocol.py

@@ -0,0 +1,46 @@
+"""TTSBackend protocol + error taxonomy.
+
+Single-source-of-truth for the voice-backend error taxonomy is now
+``madrigal.engine.protocol`` (the upstream voice library). This module
+re-exports those symbols so existing call sites continue to work
+unchanged after the Phase 1 backend swap.
+
+The ``TTSBackend`` Protocol and the ``VoiceError`` hierarchy come from
+madrigal; ``VoiceInfo`` (the agent-core-voice registry record) stays
+local because it's our wiring layer's concern, not madrigal's.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from madrigal.engine.protocol import (
+    EmptyTextError,
+    GPUOOMError,
+    TextTooLongError,
+    TTSBackend,
+    VoiceError,
+    VoiceNotPreparedError,
+)
+
+
+@dataclass(frozen=True)
+class VoiceInfo:
+    """One configured voice in the registry."""
+
+    voice_id: str
+    ref_wav: Path
+    ref_text: str
+    blend: str | None = None
+
+
+__all__ = [
+    "EmptyTextError",
+    "GPUOOMError",
+    "TextTooLongError",
+    "TTSBackend",
+    "VoiceError",
+    "VoiceInfo",
+    "VoiceNotPreparedError",
+]

agent_core_voice-0.8.2.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: agent-core-voice
+Version: 0.8.2
+Summary: Voice synthesis endpoint for agent_core — per-agent Qwen3-TTS via ICL voice cloning
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: agent-core-bus<0.9,>=0.8
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: madrigal>=0.2.0
+Requires-Dist: pluggy>=1.6
+Requires-Dist: soundfile>=0.13
+Provides-Extra: cpu
+Requires-Dist: torch>=2.11; extra == 'cpu'
+Requires-Dist: torchaudio>=2.11; extra == 'cpu'
+Provides-Extra: cu130
+Requires-Dist: torch>=2.11; extra == 'cu130'
+Requires-Dist: torchaudio>=2.11; extra == 'cu130'

agent_core_voice-0.8.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+agent_core_voice/__init__.py,sha256=CxY0N9G164KA4clICj_o8OOprcL6I01VrzeUB-OzvQU,78
+agent_core_voice/audit.py,sha256=sBIfgQMtnkLnWeuzDGHRbNhANpPikPHiGKiyDPxcd9s,1414
+agent_core_voice/endpoint.py,sha256=KoEUaZZVC6n7SiNmYOaYErackLlIbX2Kmy3FgN8C-c0,25825
+agent_core_voice/envelopes.py,sha256=2ywCm0YvRIm8KDsTe8zpYE54Q7Ebvoa_aeXlVaNoIXA,2310
+agent_core_voice/lifecycle.py,sha256=DJxe8fc3jU12BZdDU8VS1RhDFKEAOSbclxX9pWOPsO4,4863
+agent_core_voice/mcp.py,sha256=gLPWOZRilW7fNIdRFa151vdoexYudSS2sfAOjQ8z9OI,4286
+agent_core_voice/plugin.py,sha256=ogNYZfNUIdGS0HBp8ySgTMLdQIZawPXuqNCx_gbGALU,4632
+agent_core_voice/protocol.py,sha256=FX6nVg23o5OGReOPD9pR4g6wQ4iyMrYdpEqBJ2q4_g4,1089
+agent_core_voice-0.8.2.dist-info/METADATA,sha256=g6jLTkZ3Y3VfrvXIGZ2L8f4hVG1UWA3-CzYS-8Shbog,588
+agent_core_voice-0.8.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agent_core_voice-0.8.2.dist-info/entry_points.txt,sha256=64PP6ZcPSDlZLDQWBhWimKvHKRdTmdOH9KLQL1Mba90,53
+agent_core_voice-0.8.2.dist-info/RECORD,,

agent_core_voice-0.8.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_core_voice-0.8.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[agent_core]
+voice_aliases = agent_core_voice.plugin