AbstractRuntime 0.12.0__tar.gz → 0.13.0__tar.gz

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-27
+
+Requires AbstractCore 2.30.0 or newer. Personal voice stores need AbstractVoice 0.19.0.
+
+### Added
+
+- The voice library runs on the capability registry the runtime's synthesis uses (same voice manager, settings and
+  stores); a model pool manages voices on its media host. `clone_voice(..., language=)` forwards the recording's language;
+  `clone_voice` answers the stored record, flat, with its `voice_id`, locally and remotely; a remote refusal keeps the
+  server's status (400, 401, 403, 404, 409, 413, 422, 429, 501, 503); an empty voice id is refused (422).
+- **Per-runtime voice stores**: `voice_store_dir` and `voice_library_dirs` in a runtime's AbstractCore client settings give
+  it a personal voice store in front of read-only libraries; its synthesis, voice catalog and voice library use the same
+  stores. `deploy_voice_to_library(voice_id)` on the voice library facade (local runtimes). See
+  [Voice library](docs/integrations/abstractcore.md#voice-library).
+
+- **Voice library facade**: `get_abstractcore_voice_facade(runtime)` (`AbstractCoreVoiceFacade`, `VoiceLibraryError`) lists the languages each voice engine accepts, lists cloned voices (designed and built-in ones included, optionally by language), reads, renames, replaces the reference transcript of and deletes a cloned voice, creates a voice from a recording (`clone_voice`) or from a written description (`design_voice`), and returns the capability catalog (which engine and model supports `speed`, `one_shot`, design... and how). Local runtimes run it in process; remote runtimes call the AbstractCore server's `/v1` voice routes. Refusals carry an HTTP-like `status_code`. See [Voice library](docs/integrations/abstractcore.md#voice-library).
+- **Voice catalog by language**: `get_voice_catalog(..., language=)` keeps the voices that can speak a language, native speakers first (local and remote).
+- **`one_shot` on remote TTS**: a remote runtime forwards `one_shot` on buffered speech, as local runtimes already did.
+
+### Changed
+
+- A voice request the voice plugin refuses (a plain `ValueError` or `KeyError` on a `modality: voice` output, such as
+  `one_shot` over an engine's length limit or an unknown voice id) and a missing capability
+  (`CapabilityUnavailableError`) fail the `LLM_CALL` effect at once instead of being retried: one engine call, the same
+  message. Other media lanes keep their retries.
+- A remote AbstractCore server's 4xx refusal (other than 408, 409, 425, 429) is no longer retried: the status is read from
+  the HTTP error's response.
+
 ## [0.12.0] - 2026-10-27
 
 Requires AbstractCore 2.30.0 or newer (`EmailClient` mailbox verbs; Gmail labels on message summaries) and AbstractMemory 0.3.2 or newer.

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.12.0
+Version: 0.13.0
 Summary: AbstractRuntime: a durable graph runner designed to pair with AbstractCore.
 Project-URL: AbstractCore (website), https://www.abstractcore.ai/
 Project-URL: AbstractRuntime (GitHub), https://github.com/lpalbou/abstractruntime

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/docs/api.md

@@ -338,12 +338,13 @@ Entry points:
 - `create_local_runtime(...)`, `create_remote_runtime(...)`, `create_hybrid_runtime(...)` (`src/abstractruntime/integrations/abstractcore/factory.py`)
 - public discovery facade: `AbstractCoreDiscoveryFacade`, `get_abstractcore_discovery_facade(...)` (`src/abstractruntime/integrations/abstractcore/discovery_facade.py`)
 - public host facade: `AbstractCoreHostFacade`, `get_abstractcore_host_facade(...)` (`src/abstractruntime/integrations/abstractcore/host_facade.py`)
+- public voice library facade: `AbstractCoreVoiceFacade`, `get_abstractcore_voice_facade(...)`, `VoiceLibraryError` (`src/abstractruntime/integrations/abstractcore/voice_facade.py`): languages, cloned voices (list by language, read, rename or replace the transcript, delete), cloning from a recording, voice design, the capability catalog; local in process, remote over the AbstractCore server's `/v1` voice routes (see [Voice library](integrations/abstractcore.md#voice-library))
 - email facade: `email_facade` (AbstractCore's mail library for hosts; see [Email](#email))
 - public Telegram host wrappers: `TelegramTdlibNotAvailable`, `bootstrap_telegram_auth_from_env(...)`, `get_global_telegram_client(...)`, `stop_global_telegram_client()`, `send_telegram_message(...)` (`src/abstractruntime/integrations/abstractcore/telegram_facade.py`)
 - public durable run facade: `AbstractCoreRunFacade`, `get_abstractcore_run_facade(...)` (`src/abstractruntime/integrations/abstractcore/run_facade.py`); `inline_run_active(run_id)` is true while the facade executes a child run in this process (its workflow exists only inside that call), so a host runner that scans `RUNNING` runs skips it
 - effect handler wiring: `build_effect_handlers(...)` (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`)
 - tool executors: `MappingToolExecutor`, `AbstractCoreToolExecutor`, `PassthroughToolExecutor`, `ApprovalToolExecutor`, `ToolApprovalPolicy` (`src/abstractruntime/integrations/abstractcore/tool_executor.py`)
-- discovery-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`list_providers`, `list_provider_models`, `get_voice_catalog`, `list_tts_models`, `list_stt_models`, `list_music_providers`, `list_music_models`, `list_vision_provider_models`, `list_cached_vision_models`, `list_vision_adapters`)
+- discovery-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`list_providers`, `list_provider_models`, `get_voice_catalog` (with `language=`), `list_tts_models`, `list_stt_models`, `list_music_providers`, `list_music_models`, `list_vision_provider_models`, `list_cached_vision_models`, `list_vision_adapters`)
 - the host's OpenAI credential for AbstractVoice's `openai` engines, `voice_openai_api_key`, travels two ways. For discovery, pass it to `get_voice_catalog`, `list_tts_models` or `list_stt_models`; the local clients hand it to the voice plugin's config, and a remote client never sends it (a remote AbstractCore server uses its own voice configuration). For execution, put it in `create_local_runtime(llm_kwargs={"voice_openai_api_key": ...})`. Constructor kwargs become the provider's `config`, which is also the capability-plugin config. Providers read only the keys they name, so a `voice_*` key changes no text request (tests `tests/test_voice_openai_api_key_path.py`)
 - host-facade client delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`get_prompt_cache_capabilities`, `get_prompt_cache_stats`, `prompt_cache_set`, `prompt_cache_update`, `prompt_cache_fork`, `prompt_cache_clear`, `prompt_cache_prepare_modules`, `upsert_text_bloc`, `get_bloc_record`, `list_blocs`, `get_bloc_kv_manifest`, `ensure_bloc_kv_artifact`, `load_bloc_kv_artifact`, `list_bloc_kv_artifacts`, `delete_bloc_kv_artifact`, `prune_bloc_kv_artifacts`, `delete_bloc`, `get_model_residency_capabilities`, `list_model_residency`, `load_model_residency`, `unload_model_residency`, `get_memory_snapshot`, `list_session_prompt_caches`, `clear_session_prompt_caches`, `lock_model_residency`, `unlock_model_residency`, `get_context_estimate`); the last six are optional in the client contract, and the facade returns `{"ok": false, "supported": false, ...}` when the configured client does not implement one
 - `integrations.abstractcore.llm_client.set_default_model_warmup(enabled)` (process-wide, no environment variable): whether a new `MultiLocalAbstractCoreLLMClient` builds (for a local model: loads) its default model at construction and on a default switch. Default on. A process that serves no model turns it off once at boot (the gateway's `serve --no-runner`); the default client is then built at its first call. `default_model_warmup()` reads the setting (see `integrations/abstractcore.md#unloading-and-switching-models`)

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/docs/backlog/README.md

@@ -14,7 +14,7 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 
 - Planned: 29
 - Proposed: 14
-- Completed: 35
+- Completed: 37
 - Deprecated: 13
 - Recurrent: 0
 
@@ -93,6 +93,8 @@ mtime). The anticipated ADR ("an automation is its controller root run") is not
 
 | ID | Item |
 |----|------|
+| 0851 | [Per-account voice stores](completed/0851_per_account_voice_stores.md): completed 2026-10-27 (0.13.0); the runtime's voice catalog and voice library use its `voice_store_dir` / `voice_library_dirs`; real-weights E2E 9/9. |
+| 0852 | [Capability refusals are not retried](completed/0852_capability_refusals_are_not_retried.md): completed 2026-10-27 (0.13.0); one engine call for a refused request. |
 | 0847 | [Automations v1: controller, contracts, occurrences, triggers](completed/0847_automations_v1_controller_contracts_occurrences_triggers.md): completed 2026-09-27, moved from planned; UNRELEASED; `79d9bf6`…`d02578a`, 2957 passed / 26 skipped; reviews GO after fixes; E2E 9/9. |
 | 0846 | [Existing MLX instance scheduling and execution controls](completed/0846_mlx_instance_scheduling_and_execution_controls.md): completed 2026-09-20; moved from planned, 237 Runtime tests + 616 Core tests and four real-model integration cases; independent review approved, unreleased. |
 | 001 | `completed/001_runtime_kernel.md` |

abstractruntime-0.13.0/docs/backlog/completed/0851_per_account_voice_stores.md

@@ -0,0 +1,51 @@
+# 0851 — Per-account voice stores: the voice settings of each account's runtime, and the scope in the voice facade
+
+**Status**: completed (2026-10-27, 0.13.0) · **Priority**: P1 · **Created**: 2026-10-27
+**Cross-package**: AbstractVoice backlog 0065 (personal stores and a shared library), AbstractGateway backlog 0942 (personal voices per account, admin library, an AI's voice in its profile).
+
+## Why
+Operator, 2026-10-27: each person registers the voices they want (clone, design) and they are
+personal, not shared by every account; an administrator can still deploy voices for everyone;
+an AI (assistant, coder, entity) gets its voice as part of its profile. Today AbstractVoice keeps
+one store per machine user, so every account of a gateway shares every cloned voice, and the
+gateway's voice changes are admin-only until this lands.
+
+## Current code reality (2026-10-27)
+- `integrations/abstractcore/voice_facade.py` / `voice_library.py` (0.12.1): the voice library
+  facade; local clients build a capability registry from `discovery_queries._runtime_capability_registry`
+  (owner config: discovery settings only), remote clients call the AbstractCore server's `/v1` routes.
+- Synthesis uses the LLM client's provider config (`create_local_runtime(llm_kwargs=...)` keys
+  become the capability-plugin config, see `voice_openai_api_key`).
+- No setting names a voice store; AbstractVoice reads its machine-user folder.
+
+## Scope
+- In: accept AbstractVoice's `voice_store_dir` and `voice_library_dirs` (0065) in the runtime's
+  AbstractCore config so synthesis and the voice facade of one runtime use the same stores; the
+  facade passes them to the local registry; records carry `scope: personal|library`; a
+  `deploy_to_library` facade call for hosts that allow it; remote mode forwards nothing (a remote
+  AbstractCore server keeps its own stores) and says so.
+- Out: who may deploy (the host's policy), the gateway routes (0942).
+
+## Validation
+Two runtimes with two store folders: a voice designed in one is spoken by it and not listed by the
+other; both list and speak a library voice; the library refuses changes from a personal runtime.
+
+## Report (completed 2026-10-27, 0.13.0)
+`discovery_queries._runtime_capability_owner_config` / `_runtime_capability_registry` / `local_get_voice_catalog` take
+`voice_store_dir` and `voice_library_dirs`; `voice_library.voice_store_settings(llm_kwargs)` reads them from the local
+clients' `_llm_kwargs` (the settings their synthesis already hands the voice plugin), so the voice catalog and the voice
+library facade use the runtime's own stores. `deploy_voice_to_library` op and facade method (local; 501 remote). Remote
+mode forwards nothing: the AbstractCore server keeps its stores.
+
+Validation: `tests/test_voice_library_facade.py` (settings reach the registry owner config for the library and the
+catalog; absent when unset; deploy 501 remote). Real weights, two local runtimes with personal stores and one library,
+9/9: design through the facade, listed by its runtime only (library and catalog), the other runtime cannot delete it
+(404), deploy, library voice listed by both and read-only (422).
+
+Adversarial review (2026-10-27), fixed before release: the voice library built its own registry from the discovery
+settings (a second voice manager, weights loaded twice, a 5 s remote timeout): it now runs on the client's own
+AbstractCore instance (`llm.capabilities`; a model pool on its media host), the registry synthesis uses. Also: one flat
+record shape for `clone_voice` on both sides, `language` forwarded, remote statuses passed through, `voice_library_dirs`
+as an `os.pathsep` string, empty voice ids refused (422), a created voice whose record cannot be read back is still
+reported created. Real weights rerun with real local clients: 9/9 and 14/14.
+

abstractruntime-0.13.0/docs/backlog/completed/0852_capability_refusals_are_not_retried.md

@@ -0,0 +1,44 @@
+# 0852 — A capability's refusal of the request is not retried and reaches the host as a refusal
+
+**Status**: completed (2026-10-27, 0.13.0) · **Priority**: P2 · **Created**: 2026-10-27
+
+## Why
+Measured 2026-10-27 through the gateway (`POST /runs/{id}/voice/tts`, Qwen3-TTS, `one_shot: true`
+with 2,399 characters): AbstractVoice refuses at once ("one_shot synthesis takes at most 1000
+characters in a single generation"), the media effect retries it three times, and the host
+answers HTTP 500 "Effect failed after 3 attempts". The refusal is the caller's input, not a
+transient failure: retrying wastes three engine calls and the host cannot answer 422.
+
+## Current code reality
+- The LLM_CALL media path (`llm_client.py` `_run_multimodal_spec` → AbstractCore
+  `providers/base.py` → plugin) raises `ValueError` for refused input; the effect's retry policy
+  treats every exception alike.
+- The voice library facade already maps `ValueError` to a 422 `VoiceLibraryError`
+  (`voice_library.py`), so the two surfaces disagree.
+
+## Scope
+- In: classify refused input (`ValueError`, AbstractCore `CapabilityUnavailableError`) as
+  non-retryable in the media effects; record it on the child run with a code (`invalid_request`,
+  `capability_unavailable`) the host maps to 422 / 501.
+- Out: engine limits themselves (AbstractVoice).
+
+## Validation
+A one_shot request over the limit makes one engine call and the child run records
+`invalid_request`; a transient error is still retried; mutants: drop the classification and the
+test sees three calls.
+
+## Report (completed 2026-10-27, 0.13.0)
+`effect_handlers._llm_error_is_retryable`: a plain `ValueError`, a `KeyError` and AbstractCore's
+`CapabilityUnavailableError` are non-retryable (one engine call). Subclasses of `ValueError` such as
+`json.JSONDecodeError` keep the retryable default. Not done here: an error code on the child run for the host to map to
+422/501 (the run failure record carries prose only); AbstractGateway backlog 0942 tracks the 422 answer of
+`/voice/tts`.
+
+Validation: `tests/test_llm_retry_classification.py::test_a_capability_refusal_is_not_retried` (refusals non-retryable;
+a JSON decode error and a connection error still retried).
+
+Adversarial review (2026-10-27): a plain ValueError is also how other media lanes report failures a retry can fix (a
+failed remote image job, an empty or black image, non-finite music audio), so the rule was narrowed before release:
+plain `ValueError` / `KeyError` are non-retryable only on a `modality: voice` output (`effect_handlers._is_voice_refusal`);
+`CapabilityUnavailableError` stays non-retryable everywhere.
+

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/docs/integrations/abstractcore.md

@@ -1024,6 +1024,64 @@ adapters = facade.list_vision_adapters(
 )
 ```
 
+## Voice library
+
+`get_abstractcore_voice_facade(runtime)` (`AbstractCoreVoiceFacade`) manages the voices AbstractCore can speak with:
+
+- `list_languages(kind=None, provider=None)`: `{"languages": {kind: {provider: {provider, languages, open, declared}}}}`
+  for `tts`, `stt` and `cloning`, read without loading a model;
+- `list_cloned_voices(provider=None, model=None, language=None)`: `{"voices": [...], "count": n}`, designed and
+  built-in voices included (`tags.designed`, `tags.builtin`); `language` keeps the voices that can speak it, native
+  speakers first;
+- `get_cloned_voice(voice_id)`, `update_cloned_voice(voice_id, name=None, reference_text=None)` (both fields checked
+  before either is applied) and `delete_cloned_voice(voice_id)`; built-in voices are read-only;
+- `clone_voice(audio_bytes, filename=None, content_type=None, name=None, reference_text=None, provider=None, model=None)`:
+  a voice from a reference recording (`provider` = the cloning engine, e.g. `qwen3-tts`, `omnivoice`);
+- `design_voice(description, name=None, language=None, text=None)`: a voice from a written description, stored as a
+  cloned voice (needs `abstractvoice[qwen3-tts]` and `abstractvoice[stt]` where the voice capability runs);
+- `deploy_voice_to_library(voice_id)`: copies one of the runtime's personal voices into its first library (see below);
+- `compatibility_catalog()`: per kind, provider, model and surface, the support level of each feature (`native`,
+  `emulated`, `conditional`, `unsupported`), e.g. which engines honour `speed` or `one_shot`.
+
+Local clients run these in process on the same AbstractCore capability registry their synthesis uses (same voice
+manager, settings and voice stores; a model pool uses its media host), AbstractCore 2.30.0+ and AbstractVoice 0.18.2+.
+`clone_voice` answers the stored record, flat, with its `voice_id`, on both sides; `clone_voice(..., language=)` records
+the recording's language in process (AbstractVoice 0.19.0). A remote AbstractCore 2.30.0 server does not take the
+language yet (its clone form has no such field), so a remotely cloned voice's language is identified from its transcript. The remote client calls the AbstractCore server's `/v1/audio/languages`, `/v1/voice/clones[/{id}]`
+(`GET`, `PATCH`, `DELETE`), `/v1/voice/clone` and `/v1/voice/design`, and reads the capability catalog from
+`/v1/audio/voices`; the server's changes need its operator token in the runtime's headers. Every refusal is a
+`VoiceLibraryError` with `status_code` (404 unknown voice, 422 refused input, 401 server token missing, 501 capability
+or engine runtime missing; a remote server's own 400, 403, 409, 413, 429 and 503 pass through; 502 for any other remote
+failure) and `detail`, so a host maps it to its own answer.
+
+Cloned voices live in AbstractVoice's store. By default that is one store per machine user, shared by every account a
+host serves. A runtime can instead have its own personal voice store in front of read-only libraries: put
+`voice_store_dir` (and optionally `voice_library_dirs`, a list of folders) in its AbstractCore client settings, e.g.
+`create_local_runtime(llm_kwargs={"voice_store_dir": "/data/alice/voices", "voice_library_dirs": ["/data/voice-library"]})`.
+Synthesis, the voice catalog and the voice library facade of that runtime then use the same stores: voices cloned or
+designed go to the personal store, library voices (built-in ones included) are listed and spoken but read-only (422), and
+`deploy_voice_to_library(voice_id)` copies a personal voice into the first library (local runtimes; 501 remote, where the
+AbstractCore server keeps its own store). Who may deploy is the host's decision. Needs AbstractVoice 0.19.0; with an older
+AbstractVoice, these settings are not honoured. Records carry `meta.scope` (`personal` | `library`).
+
+The voice catalog takes the same language filter: `get_abstractcore_discovery_facade(rt).get_voice_catalog(language="fr")`.
+A remote run's buffered TTS forwards `one_shot` (the whole text as one take, refused beyond an engine's limit); the
+streamed lane never sends it, as AbstractCore refuses `one_shot` on a stream.
+
+```python
+from abstractruntime.integrations.abstractcore import VoiceLibraryError, get_abstractcore_voice_facade
+
+voices = get_abstractcore_voice_facade(rt)
+french = voices.list_cloned_voices(language="fr")["voices"]
+designed = voices.design_voice("A calm, warm low female voice", name="Calm", language="en")
+voices.update_cloned_voice(designed["voice_id"], name="Calm narrator")
+voices.delete_cloned_voice(designed["voice_id"])
+try:
+    voices.get_cloned_voice(designed["voice_id"])
+except VoiceLibraryError as err:
+    print(err.status_code, err.detail)  # 404: the voice is gone
+```
+
 ## Durable run-scoped media and comms execution
 
 Hosts sometimes need to trigger image/TTS/music/STT work or outbound comms sends for an existing run. That work should still execute through Runtime so the child run ledger, artifact ownership, and replay surface remain Runtime-authored.

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/llms-full.txt

@@ -1307,12 +1307,13 @@ Entry points:
 - `create_local_runtime(...)`, `create_remote_runtime(...)`, `create_hybrid_runtime(...)` (`src/abstractruntime/integrations/abstractcore/factory.py`)
 - public discovery facade: `AbstractCoreDiscoveryFacade`, `get_abstractcore_discovery_facade(...)` (`src/abstractruntime/integrations/abstractcore/discovery_facade.py`)
 - public host facade: `AbstractCoreHostFacade`, `get_abstractcore_host_facade(...)` (`src/abstractruntime/integrations/abstractcore/host_facade.py`)
+- public voice library facade: `AbstractCoreVoiceFacade`, `get_abstractcore_voice_facade(...)`, `VoiceLibraryError` (`src/abstractruntime/integrations/abstractcore/voice_facade.py`): languages, cloned voices (list by language, read, rename or replace the transcript, delete), cloning from a recording, voice design, the capability catalog; local in process, remote over the AbstractCore server's `/v1` voice routes (see [Voice library](integrations/abstractcore.md#voice-library))
 - email facade: `email_facade` (AbstractCore's mail library for hosts; see [Email](#email))
 - public Telegram host wrappers: `TelegramTdlibNotAvailable`, `bootstrap_telegram_auth_from_env(...)`, `get_global_telegram_client(...)`, `stop_global_telegram_client()`, `send_telegram_message(...)` (`src/abstractruntime/integrations/abstractcore/telegram_facade.py`)
 - public durable run facade: `AbstractCoreRunFacade`, `get_abstractcore_run_facade(...)` (`src/abstractruntime/integrations/abstractcore/run_facade.py`); `inline_run_active(run_id)` is true while the facade executes a child run in this process (its workflow exists only inside that call), so a host runner that scans `RUNNING` runs skips it
 - effect handler wiring: `build_effect_handlers(...)` (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`)
 - tool executors: `MappingToolExecutor`, `AbstractCoreToolExecutor`, `PassthroughToolExecutor`, `ApprovalToolExecutor`, `ToolApprovalPolicy` (`src/abstractruntime/integrations/abstractcore/tool_executor.py`)
-- discovery-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`list_providers`, `list_provider_models`, `get_voice_catalog`, `list_tts_models`, `list_stt_models`, `list_music_providers`, `list_music_models`, `list_vision_provider_models`, `list_cached_vision_models`, `list_vision_adapters`)
+- discovery-facade delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`list_providers`, `list_provider_models`, `get_voice_catalog` (with `language=`), `list_tts_models`, `list_stt_models`, `list_music_providers`, `list_music_models`, `list_vision_provider_models`, `list_cached_vision_models`, `list_vision_adapters`)
 - the host's OpenAI credential for AbstractVoice's `openai` engines, `voice_openai_api_key`, travels two ways. For discovery, pass it to `get_voice_catalog`, `list_tts_models` or `list_stt_models`; the local clients hand it to the voice plugin's config, and a remote client never sends it (a remote AbstractCore server uses its own voice configuration). For execution, put it in `create_local_runtime(llm_kwargs={"voice_openai_api_key": ...})`. Constructor kwargs become the provider's `config`, which is also the capability-plugin config. Providers read only the keys they name, so a `voice_*` key changes no text request (tests `tests/test_voice_openai_api_key_path.py`)
 - host-facade client delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`get_prompt_cache_capabilities`, `get_prompt_cache_stats`, `prompt_cache_set`, `prompt_cache_update`, `prompt_cache_fork`, `prompt_cache_clear`, `prompt_cache_prepare_modules`, `upsert_text_bloc`, `get_bloc_record`, `list_blocs`, `get_bloc_kv_manifest`, `ensure_bloc_kv_artifact`, `load_bloc_kv_artifact`, `list_bloc_kv_artifacts`, `delete_bloc_kv_artifact`, `prune_bloc_kv_artifacts`, `delete_bloc`, `get_model_residency_capabilities`, `list_model_residency`, `load_model_residency`, `unload_model_residency`, `get_memory_snapshot`, `list_session_prompt_caches`, `clear_session_prompt_caches`, `lock_model_residency`, `unlock_model_residency`, `get_context_estimate`); the last six are optional in the client contract, and the facade returns `{"ok": false, "supported": false, ...}` when the configured client does not implement one
 - `integrations.abstractcore.llm_client.set_default_model_warmup(enabled)` (process-wide, no environment variable): whether a new `MultiLocalAbstractCoreLLMClient` builds (for a local model: loads) its default model at construction and on a default switch. Default on. A process that serves no model turns it off once at boot (the gateway's `serve --no-runner`); the default client is then built at its first call. `default_model_warmup()` reads the setting (see `integrations/abstractcore.md#unloading-and-switching-models`)
@@ -3232,6 +3233,64 @@ adapters = facade.list_vision_adapters(
 )
 ```
 
+## Voice library
+
+`get_abstractcore_voice_facade(runtime)` (`AbstractCoreVoiceFacade`) manages the voices AbstractCore can speak with:
+
+- `list_languages(kind=None, provider=None)`: `{"languages": {kind: {provider: {provider, languages, open, declared}}}}`
+  for `tts`, `stt` and `cloning`, read without loading a model;
+- `list_cloned_voices(provider=None, model=None, language=None)`: `{"voices": [...], "count": n}`, designed and
+  built-in voices included (`tags.designed`, `tags.builtin`); `language` keeps the voices that can speak it, native
+  speakers first;
+- `get_cloned_voice(voice_id)`, `update_cloned_voice(voice_id, name=None, reference_text=None)` (both fields checked
+  before either is applied) and `delete_cloned_voice(voice_id)`; built-in voices are read-only;
+- `clone_voice(audio_bytes, filename=None, content_type=None, name=None, reference_text=None, provider=None, model=None)`:
+  a voice from a reference recording (`provider` = the cloning engine, e.g. `qwen3-tts`, `omnivoice`);
+- `design_voice(description, name=None, language=None, text=None)`: a voice from a written description, stored as a
+  cloned voice (needs `abstractvoice[qwen3-tts]` and `abstractvoice[stt]` where the voice capability runs);
+- `deploy_voice_to_library(voice_id)`: copies one of the runtime's personal voices into its first library (see below);
+- `compatibility_catalog()`: per kind, provider, model and surface, the support level of each feature (`native`,
+  `emulated`, `conditional`, `unsupported`), e.g. which engines honour `speed` or `one_shot`.
+
+Local clients run these in process on the same AbstractCore capability registry their synthesis uses (same voice
+manager, settings and voice stores; a model pool uses its media host), AbstractCore 2.30.0+ and AbstractVoice 0.18.2+.
+`clone_voice` answers the stored record, flat, with its `voice_id`, on both sides; `clone_voice(..., language=)` records
+the recording's language in process (AbstractVoice 0.19.0). A remote AbstractCore 2.30.0 server does not take the
+language yet (its clone form has no such field), so a remotely cloned voice's language is identified from its transcript. The remote client calls the AbstractCore server's `/v1/audio/languages`, `/v1/voice/clones[/{id}]`
+(`GET`, `PATCH`, `DELETE`), `/v1/voice/clone` and `/v1/voice/design`, and reads the capability catalog from
+`/v1/audio/voices`; the server's changes need its operator token in the runtime's headers. Every refusal is a
+`VoiceLibraryError` with `status_code` (404 unknown voice, 422 refused input, 401 server token missing, 501 capability
+or engine runtime missing; a remote server's own 400, 403, 409, 413, 429 and 503 pass through; 502 for any other remote
+failure) and `detail`, so a host maps it to its own answer.
+
+Cloned voices live in AbstractVoice's store. By default that is one store per machine user, shared by every account a
+host serves. A runtime can instead have its own personal voice store in front of read-only libraries: put
+`voice_store_dir` (and optionally `voice_library_dirs`, a list of folders) in its AbstractCore client settings, e.g.
+`create_local_runtime(llm_kwargs={"voice_store_dir": "/data/alice/voices", "voice_library_dirs": ["/data/voice-library"]})`.
+Synthesis, the voice catalog and the voice library facade of that runtime then use the same stores: voices cloned or
+designed go to the personal store, library voices (built-in ones included) are listed and spoken but read-only (422), and
+`deploy_voice_to_library(voice_id)` copies a personal voice into the first library (local runtimes; 501 remote, where the
+AbstractCore server keeps its own store). Who may deploy is the host's decision. Needs AbstractVoice 0.19.0; with an older
+AbstractVoice, these settings are not honoured. Records carry `meta.scope` (`personal` | `library`).
+
+The voice catalog takes the same language filter: `get_abstractcore_discovery_facade(rt).get_voice_catalog(language="fr")`.
+A remote run's buffered TTS forwards `one_shot` (the whole text as one take, refused beyond an engine's limit); the
+streamed lane never sends it, as AbstractCore refuses `one_shot` on a stream.
+
+```python
+from abstractruntime.integrations.abstractcore import VoiceLibraryError, get_abstractcore_voice_facade
+
+voices = get_abstractcore_voice_facade(rt)
+french = voices.list_cloned_voices(language="fr")["voices"]
+designed = voices.design_voice("A calm, warm low female voice", name="Calm", language="en")
+voices.update_cloned_voice(designed["voice_id"], name="Calm narrator")
+voices.delete_cloned_voice(designed["voice_id"])
+try:
+    voices.get_cloned_voice(designed["voice_id"])
+except VoiceLibraryError as err:
+    print(err.status_code, err.detail)  # 404: the voice is gone
+```
+
 ## Durable run-scoped media and comms execution
 
 Hosts sometimes need to trigger image/TTS/music/STT work or outbound comms sends for an existing run. That work should still execute through Runtime so the child run ledger, artifact ownership, and replay surface remain Runtime-authored.

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/llms.txt

@@ -47,7 +47,7 @@
 - VisualFlow LLM Call and Agent nodes forward Core generation controls such as `thinking`; Provider Models nodes can apply Core `capability_route` filters during runtime discovery.
 - Prompt-cache tracks: use `LLM_CALL.params.prompt_cache_key`, `run.vars["_runtime"]["prompt_cache"]`, or `ABSTRACTRUNTIME_PROMPT_CACHE` for best-effort text/chat session reuse; use `LLM_CALL.params.prompt_cache_binding` for durable exact bloc-backed reuse; and use `get_abstractcore_host_facade(runtime).list_prompt_cache_exports(...)`, `prompt_cache_export(...)`, and `prompt_cache_import(...)` only for host-local operator/admin export-import workflows around live local provider caches. Runtime does not auto-derive prompt-cache keys for image/video/voice/music/STT output selectors. Derived session keys are stamped with session attribution after each generate so hosts can use `list_session_prompt_caches(...)` / `clear_session_prompt_caches(...)` per session; caller-owned keys are never stamped, and completing a run does not clear session caches. Local Runtime stores one content-addressed bloc per root plus provider/model-specific derived KV artifacts. Gateway prompt-cache env belongs in Gateway.
 - Durable bloc lifecycle: Runtime exposes `list_blocs(...)`, `list_bloc_kv_artifacts(...)`, `delete_bloc_kv_artifact(...)`, `prune_bloc_kv_artifacts(...)`, and `delete_bloc(...)`, with `dry_run`, `clear_loaded`, and `force` safety controls on the host facade.
-- Runtime-owned Core surfaces: `get_abstractcore_discovery_facade(...)`, `get_abstractcore_host_facade(...)`, and `get_abstractcore_run_facade(...)`
+- Runtime-owned Core surfaces: `get_abstractcore_discovery_facade(...)`, `get_abstractcore_host_facade(...)`, `get_abstractcore_voice_facade(...)` ([voice library](docs/integrations/abstractcore.md#voice-library): languages, cloned voices, cloning, voice design, the capability catalog) and `get_abstractcore_run_facade(...)`
 - Host-local operator wrappers: the host facade exposes single-user email helpers (`list_email_accounts`, `list_emails`, `read_email`, `send_email`), `abstractruntime.integrations.abstractcore.email_facade` re-exports AbstractCore's mail library for multi-user hosts, and `abstractruntime.integrations.abstractcore.telegram_facade` exposes Telegram bootstrap/global-client/send wrappers without requiring hosts to import AbstractCore directly.
 - Durable outbound comms: when an email or Telegram send belongs to a run, use `get_abstractcore_run_facade(...).send_email(...)` or `send_telegram_message(...)` so Runtime records the request and outcome in a child run; replay should show the recorded result, not resend the message. If the child run waits for approval or passthrough execution, resume it through `resume_tool_calls(...)`.
 - [Artifacts](docs/artifacts.md): Runtime artifact identity, JSON-safe refs, canonical descriptors, generated-media provenance, tool-output offload thresholds, catalog search/stats, access counters, and Gateway/Observer retrieval boundaries.

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "AbstractRuntime"
-version = "0.12.0"
+version = "0.13.0"
 description = "AbstractRuntime: a durable graph runner designed to pair with AbstractCore."
 readme = "README.md"
 requires-python = ">=3.10"

abstractruntime-0.13.0/release-notes.md

@@ -0,0 +1,25 @@
+Requires AbstractCore 2.30.0 or newer. Personal voice stores need AbstractVoice 0.19.0.
+
+### Added
+
+- The voice library runs on the capability registry the runtime's synthesis uses (same voice manager, settings and
+  stores); a model pool manages voices on its media host. `clone_voice(..., language=)` forwards the recording's language;
+  `clone_voice` answers the stored record, flat, with its `voice_id`, locally and remotely; a remote refusal keeps the
+  server's status (400, 401, 403, 404, 409, 413, 422, 429, 501, 503); an empty voice id is refused (422).
+- **Per-runtime voice stores**: `voice_store_dir` and `voice_library_dirs` in a runtime's AbstractCore client settings give
+  it a personal voice store in front of read-only libraries; its synthesis, voice catalog and voice library use the same
+  stores. `deploy_voice_to_library(voice_id)` on the voice library facade (local runtimes). See
+  [Voice library](docs/integrations/abstractcore.md#voice-library).
+
+- **Voice library facade**: `get_abstractcore_voice_facade(runtime)` (`AbstractCoreVoiceFacade`, `VoiceLibraryError`) lists the languages each voice engine accepts, lists cloned voices (designed and built-in ones included, optionally by language), reads, renames, replaces the reference transcript of and deletes a cloned voice, creates a voice from a recording (`clone_voice`) or from a written description (`design_voice`), and returns the capability catalog (which engine and model supports `speed`, `one_shot`, design... and how). Local runtimes run it in process; remote runtimes call the AbstractCore server's `/v1` voice routes. Refusals carry an HTTP-like `status_code`. See [Voice library](docs/integrations/abstractcore.md#voice-library).
+- **Voice catalog by language**: `get_voice_catalog(..., language=)` keeps the voices that can speak a language, native speakers first (local and remote).
+- **`one_shot` on remote TTS**: a remote runtime forwards `one_shot` on buffered speech, as local runtimes already did.
+
+### Changed
+
+- A voice request the voice plugin refuses (a plain `ValueError` or `KeyError` on a `modality: voice` output, such as
+  `one_shot` over an engine's length limit or an unknown voice id) and a missing capability
+  (`CapabilityUnavailableError`) fail the `LLM_CALL` effect at once instead of being retried: one engine call, the same
+  message. Other media lanes keep their retries.
+- A remote AbstractCore server's 4xx refusal (other than 408, 409, 425, 429) is no longer retried: the status is read from
+  the HTTP error's response.

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/src/abstractruntime/integrations/abstractcore/__init__.py

@@ -8,6 +8,7 @@ Provides:
 - Effect handlers wiring
 - Convenience runtime factories for local/remote/hybrid modes
 - Public discovery facade for provider/media/catalog snapshot queries
+- Public voice library facade (`voice_facade`): languages, cloned voices, voice design and cloning, the capability catalog
 - Public host facade for prompt-cache, durable bloc/KV, and model-residency control operations
 - Public config facade for AbstractCore capability-default routes and config API keys
 - Public structured-output facade (`structured_facade`): `parse_response_format` / `ResponseFormatError` for hosts
@@ -45,6 +46,11 @@ from .discovery_facade import (
     AbstractCoreDiscoveryFacade,
     get_abstractcore_discovery_facade,
 )
+from .voice_facade import (
+    AbstractCoreVoiceFacade,
+    VoiceLibraryError,
+    get_abstractcore_voice_facade,
+)
 from .run_facade import (
     LEGACY_VOICE_STREAM_WAIT_KEY_PREFIX,
     AbstractCoreRunFacade,
@@ -82,6 +88,8 @@ __all__ = [
     "AbstractCoreDiscoveryFacade",
     "AbstractCoreHostFacade",
     "AbstractCoreRunFacade",
+    "AbstractCoreVoiceFacade",
+    "VoiceLibraryError",
     "LocalAbstractCoreLLMClient",
     "MultiLocalAbstractCoreLLMClient",
     "RemoteAbstractCoreLLMClient",
@@ -100,6 +108,7 @@ __all__ = [
     "bootstrap_telegram_auth_from_env",
     "get_abstractcore_discovery_facade",
     "get_abstractcore_host_facade",
+    "get_abstractcore_voice_facade",
     "capability_default_config_file",
     "capability_default_specs",
     "clear_capability_default",

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/src/abstractruntime/integrations/abstractcore/discovery_facade.py

@@ -7,7 +7,7 @@ Scope:
 - provider discovery
 - provider model discovery
 - model capability lookup
-- audio/voice/TTS/STT catalogs
+- audio/voice/TTS/STT catalogs (voice library changes: `voice_facade.AbstractCoreVoiceFacade`)
 - music provider/model catalogs
 - vision provider catalogs
 - vision adapter catalogs
@@ -287,10 +287,14 @@ class AbstractCoreDiscoveryFacade:
         model: Optional[str] = None,
         providers_only: bool = False,
         voice_openai_api_key: Optional[str] = None,
+        language: Optional[str] = None,
         **kwargs: Any,
     ) -> Dict[str, Any]:
         """Voice catalog. `voice_openai_api_key` is the host's OpenAI credential for
-        AbstractVoice's `openai` engines (plugin setting of the same name)."""
+        AbstractVoice's `openai` engines (plugin setting of the same name). `language` keeps
+        the voices that can speak it, native speakers first (AbstractCore 2.30.0+)."""
+        if language is not None:
+            kwargs["language"] = language
         return self._client.get_voice_catalog(
             base_url=base_url,
             provider_api_key=provider_api_key,

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/src/abstractruntime/integrations/abstractcore/discovery_queries.py

@@ -624,8 +624,17 @@ def _runtime_capability_owner_config(
     vision_api_key: Optional[str] = None,
     music_base_url: Optional[str] = None,
     music_api_key: Optional[str] = None,
+    voice_store_dir: Optional[str] = None,
+    voice_library_dirs: Optional[list] = None,
 ) -> Dict[str, Any]:
     cfg: Dict[str, Any] = {}
+    # The runtime's voice stores (AbstractVoice 0.19.0 plugin settings; runtime backlog 0851):
+    # a personal store in front of read-only libraries, so this runtime lists and manages the
+    # voices its own synthesis speaks with.
+    if isinstance(voice_store_dir, str) and voice_store_dir.strip():
+        cfg["voice_store_dir"] = voice_store_dir.strip()
+    if voice_library_dirs:
+        cfg["voice_library_dirs"] = [str(d) for d in voice_library_dirs if str(d or "").strip()]
     if isinstance(voice_base_url, str) and voice_base_url.strip():
         cfg["voice_remote_base_url"] = voice_base_url.strip()
     if isinstance(voice_api_key, str) and voice_api_key.strip():
@@ -715,6 +724,8 @@ def _runtime_capability_registry(
     vision_api_key: Optional[str] = None,
     music_base_url: Optional[str] = None,
     music_api_key: Optional[str] = None,
+    voice_store_dir: Optional[str] = None,
+    voice_library_dirs: Optional[list] = None,
 ) -> Any:
     from abstractcore.capabilities import CapabilityRegistry
 
@@ -735,6 +746,8 @@ def _runtime_capability_registry(
                 vision_api_key=vision_api_key,
                 music_base_url=music_base_url,
                 music_api_key=music_api_key,
+                voice_store_dir=voice_store_dir,
+                voice_library_dirs=voice_library_dirs,
             )
         },
     )()
@@ -1074,15 +1087,25 @@ def local_get_voice_catalog(
     provider: Optional[str] = None,
     model: Optional[str] = None,
     providers_only: bool = False,
+    language: Optional[str] = None,
+    voice_store_dir: Optional[str] = None,
+    voice_library_dirs: Optional[list] = None,
 ) -> Dict[str, Any]:
     try:
         voice = _runtime_capability_registry(
             voice_base_url=base_url,
             voice_api_key=provider_api_key,
             voice_openai_api_key=voice_openai_api_key,
+            voice_store_dir=voice_store_dir,
+            voice_library_dirs=voice_library_dirs,
         ).voice
+        # `language` (AbstractCore 2.30.0+) keeps the voices that speak it, natives first; it is
+        # passed only when asked, and AbstractCore raises if its backend cannot filter.
+        lang = str(language or "").strip() or None
         catalog = (
-            voice.voice_catalog(provider=provider, model=model, providers_only=providers_only)
+            voice.voice_catalog(
+                provider=provider, model=model, providers_only=providers_only, **({"language": lang} if lang else {})
+            )
             if hasattr(voice, "voice_catalog")
             else {}
         )

{abstractruntime-0.12.0 → abstractruntime-0.13.0}/src/abstractruntime/integrations/abstractcore/effect_handlers.py

@@ -2542,6 +2542,8 @@ def make_llm_call_handler(*, llm: AbstractCoreLLMClient, artifact_store: Optiona
                 logger.info("LLM_CALL stopped by cancel", detail=str(e))
                 return EffectOutcome.failed(str(e), retryable=False)
             logger.error("LLM_CALL failed", error=str(e))
+            if _is_voice_refusal(e, params.get("output") if isinstance(params, dict) else None):
+                return EffectOutcome.failed(str(e), retryable=False)
             return EffectOutcome.failed(str(e), retryable=_llm_error_is_retryable(e))
 
     return _handler
@@ -2558,6 +2560,17 @@ _HARMONY_ARTIFACT_RE = re.compile(
 )
 
 
+def _is_voice_refusal(exc: Exception, output: Any) -> bool:
+    """A voice request the voice plugin refused (runtime backlog 0852): AbstractVoice raises a plain
+    ValueError for input it cannot honour (`one_shot` over an engine's limit, an unsupported
+    option) and KeyError for an unknown voice id; both answer the same on every attempt. Other
+    media lanes keep their retries (a failed remote job or an empty image can succeed again)."""
+    if not (type(exc) is ValueError or type(exc) is KeyError):
+        return False
+    specs = output if isinstance(output, list) else [output]
+    return any(isinstance(spec, dict) and str(spec.get("modality") or "").strip().lower() == "voice" for spec in specs)
+
+
 def _llm_error_is_retryable(exc: Exception) -> bool:
     """Classify LLM provider failures for the retry policy.
 
@@ -2620,11 +2633,24 @@ def _llm_error_is_retryable(exc: Exception) -> bool:
         pass
 
     status = getattr(exc, "status_code", None)
+    if not isinstance(status, int):
+        # An HTTP client error (httpx.HTTPStatusError from a remote AbstractCore server) carries
+        # the status on its response: a server's 4xx refusal is not retried either.
+        status = getattr(getattr(exc, "response", None), "status_code", None)
     if isinstance(status, int):
         if 400 <= status < 500 and status not in _TRANSIENT_4XX:
             return False
         return True
 
+    # A capability that is not installed answers the same on every attempt.
+    try:
+        from abstractcore.capabilities.errors import CapabilityUnavailableError  # type: ignore
+
+        if isinstance(exc, CapabilityUnavailableError):
+            return False
+    except ImportError:
+        pass
+
     try:
         from abstractcore.exceptions import (  # type: ignore
             AuthenticationError,