AbstractRuntime 0.4.16__tar.gz → 0.4.17__tar.gz

{abstractruntime-0.4.16 → abstractruntime-0.4.17}/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.17] - 2026-05-21
+
+### Added
+- Runtime now surfaces AbstractCore-backed music through the same durable boundary as other generated artifacts:
+  - host discovery snapshot methods for music providers/models
+  - durable run-scoped `generate_music(...)`
+  - artifact-backed normalized music outputs for local and remote Runtime paths
+
+### Changed
+- Minimum optional AbstractCore dependency floor is now `abstractcore>=2.13.24`.
+- The `multimodal` extra now installs `abstractcore[remote,vision,voice,audio,music]>=2.13.24`, which includes AbstractMusic's lightweight remote ACE backend path via `abstractmusic>=0.1.4`.
+- Runtime docs and AI-readable `llms.txt` / `llms-full.txt` now describe the shipped music boundary and the current `0030` Gateway cleanup scope more accurately.
+
 ## [0.4.16] - 2026-05-21
 
 ### Added
@@ -448,7 +461,8 @@ AbstractRuntime is the durable execution substrate designed to pair with Abstrac
 
 Initial development version with basic proof-of-concept features.
 
-[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.16...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.17...HEAD
+[0.4.17]: https://github.com/lpalbou/abstractruntime/compare/v0.4.16...v0.4.17
 [0.4.16]: https://github.com/lpalbou/abstractruntime/compare/v0.4.15...v0.4.16
 [0.4.15]: https://github.com/lpalbou/abstractruntime/compare/v0.4.14...v0.4.15
 [0.4.14]: https://github.com/lpalbou/abstractruntime/compare/v0.4.13...v0.4.14

{abstractruntime-0.4.16 → abstractruntime-0.4.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.16
+Version: 0.4.17
 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
@@ -23,24 +23,24 @@ Requires-Python: >=3.10
 Requires-Dist: abstractmemory>=0.2.6
 Requires-Dist: abstractsemantics>=0.0.3
 Provides-Extra: abstractcore
-Requires-Dist: abstractcore>=2.13.23; extra == 'abstractcore'
+Requires-Dist: abstractcore>=2.13.24; extra == 'abstractcore'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'abstractcore'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'abstractcore'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'abstractcore'
 Provides-Extra: all-apple
-Requires-Dist: abstractcore[all-apple]>=2.13.23; extra == 'all-apple'
+Requires-Dist: abstractcore[all-apple]>=2.13.24; extra == 'all-apple'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'all-apple'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'all-apple'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'all-apple'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'all-apple'
 Provides-Extra: all-gpu
-Requires-Dist: abstractcore[all-gpu]>=2.13.23; extra == 'all-gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.13.24; extra == 'all-gpu'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'all-gpu'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'all-gpu'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'all-gpu'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'all-gpu'
 Provides-Extra: apple
-Requires-Dist: abstractcore[apple]>=2.13.23; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.13.24; extra == 'apple'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'apple'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'apple'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'apple'
@@ -50,18 +50,18 @@ Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
 Provides-Extra: gpu
-Requires-Dist: abstractcore[gpu]>=2.13.23; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.13.24; extra == 'gpu'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'gpu'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'gpu'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'gpu'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'gpu'
 Provides-Extra: mcp-worker
-Requires-Dist: abstractcore[tools]>=2.13.23; extra == 'mcp-worker'
+Requires-Dist: abstractcore[tools]>=2.13.24; extra == 'mcp-worker'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'mcp-worker'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'mcp-worker'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'mcp-worker'
 Provides-Extra: multimodal
-Requires-Dist: abstractcore[audio,remote,vision,voice]>=2.13.23; extra == 'multimodal'
+Requires-Dist: abstractcore[audio,music,remote,vision,voice]>=2.13.24; extra == 'multimodal'
 Requires-Dist: anyio<5.0.0,>=4.12.1; extra == 'multimodal'
 Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'multimodal'
 Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'multimodal'
@@ -81,7 +81,7 @@ Description-Content-Type: text/markdown
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.4.16 • **Python:** 3.10+
+**Version:** 0.4.17 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -115,7 +115,7 @@ AbstractCore integration (LLM + tools):
 pip install "abstractruntime[abstractcore]"
 ```
 
-The `abstractcore` extra installs AbstractCore 2.13.23 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, durable bloc prompt-cache helpers, bindings, and lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, and the public local vision-cache catalog helper used by Runtime discovery are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
+The `abstractcore` extra installs AbstractCore 2.13.24 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, durable bloc prompt-cache helpers, bindings, and lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, the public local vision-cache catalog helper used by Runtime discovery, and the lightweight `abstractmusic>=0.1.4` ACE-remote path used by Runtime music generation are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, audio, and music dependencies.
 
 Hardware profile cascades are available for native Python installs:
 `abstractruntime[apple]`, `abstractruntime[gpu]`, `abstractruntime[all-apple]`,
@@ -169,7 +169,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.16)
+## What’s included (v0.4.17)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -193,7 +193,7 @@ Drivers + distribution:
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Optional integrations:
-- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, durable bloc prompt-cache controls, bindings, and lifecycle operations, media inputs, generated media, tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, durable bloc prompt-cache controls, bindings, and lifecycle operations, media inputs, generated image/voice/music outputs, tool approval waits): `docs/integrations/abstractcore.md`
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
   depends on the light AbstractMemory contract; hosts choose storage backends
   such as LanceDB, SQLite, or in-memory stores.

{abstractruntime-0.4.16 → abstractruntime-0.4.17}/README.md

@@ -4,7 +4,7 @@
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.4.16 • **Python:** 3.10+
+**Version:** 0.4.17 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -38,7 +38,7 @@ AbstractCore integration (LLM + tools):
 pip install "abstractruntime[abstractcore]"
 ```
 
-The `abstractcore` extra installs AbstractCore 2.13.23 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, durable bloc prompt-cache helpers, bindings, and lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, and the public local vision-cache catalog helper used by Runtime discovery are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
+The `abstractcore` extra installs AbstractCore 2.13.24 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, durable bloc prompt-cache helpers, bindings, and lifecycle operations, public output-selector contract, async/sync text-generation output-selector parity, the public local vision-cache catalog helper used by Runtime discovery, and the lightweight `abstractmusic>=0.1.4` ACE-remote path used by Runtime music generation are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, audio, and music dependencies.
 
 Hardware profile cascades are available for native Python installs:
 `abstractruntime[apple]`, `abstractruntime[gpu]`, `abstractruntime[all-apple]`,
@@ -92,7 +92,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.16)
+## What’s included (v0.4.17)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -116,7 +116,7 @@ Drivers + distribution:
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Optional integrations:
-- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, durable bloc prompt-cache controls, bindings, and lifecycle operations, media inputs, generated media, tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, durable bloc prompt-cache controls, bindings, and lifecycle operations, media inputs, generated image/voice/music outputs, tool approval waits): `docs/integrations/abstractcore.md`
 - AbstractMemory TripleStore integration for `MEMORY_KG_*` effects. Runtime
   depends on the light AbstractMemory contract; hosts choose storage backends
   such as LanceDB, SQLite, or in-memory stores.

{abstractruntime-0.4.16 → abstractruntime-0.4.17}/docs/api.md

@@ -125,7 +125,7 @@ Key types:
 Artifacts are used by:
 - offloading wrappers (`src/abstractruntime/storage/offloading.py`)
 - evidence capture (`docs/evidence.md`, `src/abstractruntime/evidence/recorder.py`)
-- AbstractCore media integration: input artifact refs can be materialized for LLM calls, and generated image/voice/audio outputs are stored as artifact refs
+- AbstractCore media integration: input artifact refs can be materialized for LLM calls, and generated image/voice/music/audio outputs are stored as artifact refs
 
 ## Snapshots / bookmarks
 
@@ -176,7 +176,7 @@ This produces a portable record of a run’s state + ledger + artifacts suitable
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.23 or newer).
+Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.24 or newer).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -187,9 +187,9 @@ Entry points:
 - public durable run facade: `AbstractCoreRunFacade`, `get_abstractcore_run_facade(...)` (`src/abstractruntime/integrations/abstractcore/run_facade.py`)
 - 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_vision_provider_models`, `list_cached_vision_models`)
+- 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`)
 - host-facade 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`, `list_model_residency`, `load_model_residency`, `unload_model_residency`)
-- run-facade helpers create durable child runs for existing runs (`execute_llm_call`, `generate_image`, `generate_voice`, `transcribe_audio`)
+- run-facade helpers create durable child runs for existing runs (`execute_llm_call`, `generate_image`, `generate_voice`, `generate_music`, `transcribe_audio`)
 
 `LLM_CALL` payloads are JSON-safe effect payloads. Common fields:
 - `prompt`, `messages`, `system_prompt`, and convenience `text`
@@ -198,11 +198,11 @@ Entry points:
 - `params`: provider/model routing, generation controls, prompt-cache keys or `prompt_cache_binding`, structured-output schema options, and tracing metadata
 
 Multimodal support:
-- install `abstractruntime[multimodal]` for common AbstractCore media, vision, voice, and audio dependencies
+- install `abstractruntime[multimodal]` for common AbstractCore media, vision, voice, audio, and music dependencies
 - local clients call AbstractCore's unified `generate(..., media=..., output=...)`
-- remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, speech, and transcription endpoints; pass an output-specific `model` for remote media provider routing, otherwise the server endpoint can use its configured capability default
+- remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, speech, music generation, and transcription endpoints; pass an output-specific `model` for remote media provider routing, otherwise the server endpoint can use its configured capability default
 - remote transcription requires one audio media item that resolves to a local file path or artifact-backed temporary file
-- generated image/voice/audio bytes require a runtime `ArtifactStore`; the result contains `artifact_id` / `artifact_ref` instead of inline bytes
+- generated image/voice/music/audio bytes require a runtime `ArtifactStore`; the result contains `artifact_id` / `artifact_ref` instead of inline bytes
 - media-only normalized results expose `runtime_provider` / `runtime_model` separately from `media_provider` / `media_model`
 - optional local media residency failures complete with `status_hint="warning"` and `degraded=true`, while unsupported local media warmup also reports `execution_mode="local_one_shot_subprocess"` and `requires_long_lived_server=true`
 - Gateway/hosts remain responsible for explicit Core server URLs, Core server auth headers, provider/model defaults, selected Core/capability install profiles, and translation of Gateway-owned env/config into explicit Runtime inputs; Runtime persists only JSON-safe routing metadata and artifact refs

{abstractruntime-0.4.16 → abstractruntime-0.4.17}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-05-20
-> Version: 0.4.16
+> Updated: 2026-05-21
+> Version: 0.4.17
 > Scope: this describes **what is implemented in this repository**.
 
 AbstractRuntime is a **durable workflow runtime**: it executes workflow graphs as a persisted state machine with explicit waits (user, time, events, jobs, subworkflows). A run can pause for hours/days and resume **without** keeping Python stacks/coroutines alive.
@@ -28,7 +28,7 @@ Key invariants (enforced by code, not convention):
 
 ## AbstractCore capability boundary
 
-AbstractRuntime's job is persistence and orchestration. AbstractCore owns model/provider capability execution: chat, structured output, cached sessions/prompt cache, media input analysis, image generation, voice/audio generation, transcription, and future modalities such as music or video.
+AbstractRuntime's job is persistence and orchestration. AbstractCore owns model/provider capability execution: chat, structured output, cached sessions/prompt cache, media input analysis, image generation, voice/audio generation, music generation, transcription, and future modalities such as video.
 
 The boundary is intentionally narrow:
 - Workflow nodes request model work with `EffectType.LLM_CALL`; the runtime persists the request/result and delegates execution to the configured AbstractCore client.

{abstractruntime-0.4.16 → abstractruntime-0.4.17}/docs/backlog/README.md

@@ -10,6 +10,19 @@ This folder contains a structured backlog used during development. Items are gro
 
 If you are new to the project, start with `../README.md` and `../architecture.md` instead.
 
+## Next recommended work
+
+1. `planned/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md`
+   This is the narrow Runtime work that unblocks the last high-pressure direct
+   `abstractcore` imports in Gateway for comms/email and Telegram without
+   reopening the already-completed media/discovery boundary work.
+2. `planned/018_workspace_access_policy_for_media_and_tools.md`
+   Keep workspace and tool policy explicit while Gateway extracts its local
+   workspace helpers.
+3. `planned/014_remote_tool_worker_executor.md`
+   The public ToolExecutor path is still the larger follow-on after the current
+   Gateway boundary cleanup.
+
 ## Completed
 
 | ID | Item |
@@ -36,6 +49,7 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 | 026 | `completed/026_runtime_host_discovery_facade_for_core_catalogs.md` |
 | 027 | `completed/027_runtime_durable_bloc_prompt_cache_facade.md` |
 | 028 | `completed/028_runtime_bloc_kv_lifecycle_and_pruning.md` |
+| 029 | `completed/029_runtime_music_generation_and_discovery_via_abstractcore.md` |
 
 ## Planned
 
@@ -46,13 +60,15 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 | 017 | `planned/017_limit_warnings_and_observability.md` |
 | 018 | `planned/018_workspace_access_policy_for_media_and_tools.md` |
 | 025 | `planned/025_runtime_retention_and_purge_contract.md` |
+| 0030 | `planned/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md` |
 
 ## Proposed
 
-| Date | Item |
-|------|------|
+| ID | Item |
+|----|------|
 | 2026-05-20 | `proposed/2026-05-20_agent_runtime_convenience_constructor.md` |
 | 2026-05-20 | `proposed/2026-05-20_runtime_local_admin_prompt_cache_save_load.md` |
+| 0031 | `proposed/0031_runtime_tool_spec_adapters_for_gateway_and_mcp.md` |
 
 ## Deprecated
 

abstractruntime-0.4.17/docs/backlog/completed/029_runtime_music_generation_and_discovery_via_abstractcore.md

@@ -0,0 +1,178 @@
+# 029 Runtime Music Generation And Discovery Via AbstractCore
+
+## Metadata
+- Created: 2026-05-21
+- Status: Completed
+- Completed: 2026-05-21
+- Origin: direct implementation from repository backlog/user request
+
+## Goal
+
+Surface AbstractCore-backed music capabilities through Runtime without breaking
+the existing boundary rule that Runtime integrates only with AbstractCore, not
+directly with `abstractmusic` or other modality packages.
+
+## What Shipped
+
+- Extended the public Runtime-owned discovery facade with music snapshot
+  methods:
+  - `list_music_providers(...)`
+  - `list_music_models(...)`
+- Extended the public durable run facade with:
+  - `generate_music(...)`
+- Extended remote AbstractCore multimodal routing so Runtime can execute music
+  generation through AbstractCore Server's `/v1/audio/music` contract and store
+  the returned bytes as normal Runtime artifacts.
+- Extended local discovery helpers so local runtimes can surface music provider
+  and model catalogs through AbstractCore capability registries when the
+  configured Core stack exposes them.
+- Normalized `music` generated outputs into the same JSON-safe artifact-backed
+  result shape used for image and voice outputs.
+- Kept the package boundary clean:
+  - no direct Runtime import of `abstractmusic`
+  - no direct Runtime import of `abstractvoice`
+  - no direct Runtime import of `abstractvision`
+- Updated the `multimodal` extra to include `abstractcore[music]` so the common
+  Runtime media install matches the public surface.
+- Updated docs and LLM indexes so the repo no longer describes music support as
+  future-only work.
+
+## Current Code Pointers
+
+- `src/abstractruntime/integrations/abstractcore/discovery_queries.py`
+- `src/abstractruntime/integrations/abstractcore/discovery_facade.py`
+- `src/abstractruntime/integrations/abstractcore/llm_client.py`
+- `src/abstractruntime/integrations/abstractcore/run_facade.py`
+- `tests/test_abstractcore_discovery_facade.py`
+- `tests/test_multimodal_abstractcore_integration.py`
+- `tests/test_abstractcore_run_facade.py`
+- `tests/test_packaging_extras.py`
+- `docs/integrations/abstractcore.md`
+- `docs/api.md`
+- `docs/faq.md`
+
+Related ADRs already covered the boundary and ownership rules:
+- `docs/adr/0004_runtime_owns_run_scoped_media_execution_truth.md`
+- `docs/adr/0005_runtime_owns_abstractcore_host_discovery_queries.md`
+
+## Validation
+
+Focused validation run on 2026-05-21:
+
+- `pytest -q tests/test_abstractcore_discovery_facade.py tests/test_multimodal_abstractcore_integration.py tests/test_abstractcore_run_facade.py`
+- Result: `58 passed in 0.30s`
+
+Broader regression and packaging validation:
+
+- `PYTHONPATH="/Users/albou/tmp/abstractframework/abstractcore:src" pytest -q tests/test_abstractcore_discovery_facade.py tests/test_multimodal_abstractcore_integration.py tests/test_abstractcore_run_facade.py tests/test_remote_llm_client.py tests/test_packaging_extras.py tests/test_runtime_install_boundary.py tests/test_abstractcore_host_facade.py`
+- Result: `84 passed in 0.51s`
+
+Syntax/import sanity:
+
+- `python -m compileall src/abstractruntime/integrations/abstractcore`
+- Result: clean
+
+Documentation build sanity:
+
+- `mkdocs build -q --site-dir /tmp/abstractruntime-music-docs`
+- Result: build passed; upstream Material for MkDocs emitted a non-blocking
+  roadmap warning about future MkDocs 2.0 compatibility
+
+Practical proof points from the shipped tests:
+
+- Remote Runtime now proxies music discovery through:
+  - `GET /v1/audio/music/providers`
+  - `GET /v1/audio/music/models`
+- Remote Runtime now executes music generation through:
+  - `POST /v1/audio/music`
+- Durable run-scoped music execution now works through
+  `get_abstractcore_run_facade(runtime).generate_music(...)`, producing a child
+  run with artifact-backed output.
+- Live ACE Music smoke proof against AbstractCore `2.13.24` plus
+  `abstractmusic>=0.1.4`:
+  - direct Runtime local client call returned `audio/mp3` output with
+    `media_provider='abstractmusic:acemusic'`
+  - full Runtime `LLM_CALL` workflow completed durably with `ledger_entries=4`
+    and an artifact-backed MP3 result
+
+## Completion Report
+
+### Date
+
+2026-05-21
+
+### Summary
+
+Runtime now surfaces music in the same three Runtime-owned ways that it already
+surfaces other generated-media capabilities:
+
+- discovery snapshots for host/query use
+- durable run-scoped execution for existing runs
+- artifact-backed normalized outputs for replay-safe state
+
+The boundary remains correct: Runtime still talks only to AbstractCore and
+AbstractCore Server contracts. Music capability packages remain behind
+AbstractCore.
+
+### Behavior Changes
+
+- Hosts can ask Runtime for music provider and model catalogs through the
+  public discovery facade instead of querying Core directly.
+- Hosts can ask Runtime to durably execute run-scoped music generation through
+  the public run facade instead of doing out-of-band work and synthesizing
+  history afterward.
+- Remote music bytes are persisted as Runtime artifacts with the same durable
+  output shape used by image and voice generation.
+- The common `multimodal` install now includes the Core music extra so local
+  Runtime installs can expose music when the selected Core profile supports it.
+- Runtime is now validated against the `abstractcore>=2.13.24` floor and the
+  lightweight remote ACE Music backend path from `abstractmusic>=0.1.4`.
+
+### Review Notes
+
+- No new ADR was added. This change is an extension of existing accepted
+  Runtime policy:
+  - Runtime owns run-scoped media execution truth.
+  - Runtime owns host discovery boundaries.
+- The main regression caught during implementation was that remote generated
+  media had briefly stopped preserving `output.run_id` and `output.tags` for
+  artifact storage. That was fixed before closure.
+
+### Tests
+
+- `tests/test_abstractcore_discovery_facade.py`
+- `tests/test_multimodal_abstractcore_integration.py`
+- `tests/test_abstractcore_run_facade.py`
+- regression support in:
+  - `tests/test_remote_llm_client.py`
+  - `tests/test_packaging_extras.py`
+  - `tests/test_runtime_install_boundary.py`
+  - `tests/test_abstractcore_host_facade.py`
+
+### Docs
+
+- `README.md`
+- `docs/integrations/abstractcore.md`
+- `docs/api.md`
+- `docs/faq.md`
+- `docs/architecture.md`
+- `llms.txt`
+- `llms-full.txt`
+
+### Residual Risks
+
+- Runtime is ready for the AbstractCore music boundary, but the exact local
+  backend matrix still depends on which AbstractCore capability packages and
+  backends a host installs.
+- Remote music currently follows the current AbstractCore `/v1/audio/music`
+  contract. If Core changes provider/backend routing semantics, Runtime should
+  keep mirroring that public contract rather than growing direct modality
+  knowledge.
+
+### Follow-Ups
+
+- Gateway/other hosts should adopt the new Runtime discovery and run facades
+  for music instead of querying or invoking Core directly.
+- If a later Runtime surface needs music-specific operator controls, keep them
+  behind the existing Runtime-to-AbstractCore boundary rather than importing
+  `abstractmusic` directly.

abstractruntime-0.4.17/docs/backlog/planned/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md

@@ -0,0 +1,165 @@
+# Planned: Runtime host facades for comms and Telegram, with tool-spec follow-up split out
+
+## Metadata
+- Created: 2026-05-21
+- Status: Planned
+- Completed: N/A
+
+## ADR status
+- Governing ADRs: None
+- ADR impact: None; this extends the existing public host-facade pattern rather than creating a new architecture rule.
+
+## Context
+
+Runtime already owns the public Gateway-facing integration boundary for the
+main AbstractCore-backed surfaces:
+
+- `AbstractCoreHostFacade` for operator/control-plane helpers
+- `AbstractCoreDiscoveryFacade` for provider/model/media catalogs
+- `AbstractCoreRunFacade` for run-scoped durable media execution
+
+Gateway now uses those facades for prompt-cache control, durable blocs, model
+residency, discovery, and run-scoped voice/STT/image work. The remaining
+direct `abstractcore` imports in Gateway are concentrated in comms/Telegram
+helpers and a smaller tool-spec/testing tail.
+
+## Current code reality
+
+Inspected on 2026-05-21:
+
+- `src/abstractruntime/integrations/abstractcore/host_facade.py`
+  - exposes prompt-cache, bloc, and model-residency helpers
+  - does not expose email/comms helpers
+- `src/abstractruntime/integrations/abstractcore/default_tools.py`
+  - imports `abstractcore.tools.common_tools`, `comms_tools`, and `telegram_tools`
+  - derives JSON-safe tool specs via `abstractcore.tools.core.ToolDefinition`
+- `src/abstractruntime/integrations/abstractcore/mcp_worker.py`
+  - converts callables to MCP entries through `ToolDefinition.from_function(...)`
+- `src/abstractruntime/integrations/abstractcore/tool_executor.py`
+  - still constructs `abstractcore.tools.core.ToolCall`
+- `../abstractgateway/src/abstractgateway/routes/gateway.py`
+  - still imports `abstractcore.tools.comms_tools` directly for email helper routes
+- `../abstractgateway/src/abstractgateway/cli.py`
+  - still imports `abstractcore.tools.telegram_tdlib` directly for `telegram-auth`
+- `../abstractgateway/src/abstractgateway/integrations/telegram_bridge.py`
+  - still imports `abstractcore.tools.telegram_tdlib` global-client helpers directly
+
+Runtime therefore has the right facade pattern already, but the remaining
+host/operator surfaces have not been moved onto it. The strongest current
+Gateway production pressure is comms/email and Telegram bootstrap/global-client
+access; tool-spec coupling is lower-pressure follow-up work.
+
+## Problem
+
+Gateway cannot fully stop importing `abstractcore` directly until Runtime owns
+two small public surfaces in phase 1:
+
+1. comms/email host helpers
+2. Telegram bootstrap/global-client wrappers, plus a thin send helper for notifier parity
+
+The missing pieces are not durable-run problems. They are host/operator
+integration surfaces, so they belong next to the existing host-facade pattern.
+Tool-spec helpers remain useful, but they are not the strongest current
+Gateway blocker and should not hold up the narrower phase-1 cleanup.
+
+## What we want to do
+
+Extend Runtime's public host integration layer so Gateway can depend on
+Runtime alone for the remaining comms/Telegram edges, while tracking
+tool-spec normalization as a separate follow-up.
+
+## Why
+
+- keeps Gateway source aligned with the Runtime-owned boundary
+- reuses the existing facade pattern instead of inventing another Gateway/Core seam
+- gives future hosts one place to look for operator-scoped helper contracts
+- lets Runtime normalize local/remote Core topology for these paths too when needed later
+- avoids over-scoping a release-blocking boundary cleanup around a lower-pressure
+  tool-spec concern
+
+## Requirements
+
+- Add public host-facing email helpers for:
+  - list accounts
+  - list messages
+  - read message
+  - send message
+- Add a Runtime-owned Telegram wrapper surface for:
+  - one-shot TDLib auth bootstrap from env
+  - a stable "not available" error
+  - access to the global TDLib client lifecycle used by the Gateway bridge
+  - stop/cleanup of the global client
+  - `send_telegram_message(...)` for notifier parity
+- Keep these host helpers nondurable. They must not write Runtime run history by themselves.
+- Allow Runtime to wrap existing public Core tool modules in phase 1; do not block on a larger Core refactor.
+- Do not require a new AbstractCore runtime-facing backend seam for phase 1.
+
+## Suggested implementation
+
+1. Extend `AbstractCoreHostFacade` with email/comms methods:
+   - `list_email_accounts(...)`
+   - `list_emails(...)`
+   - `read_email(...)`
+   - `send_email(...)`
+2. Add a small Runtime Telegram helper module, for example under
+   `abstractruntime.integrations.abstractcore.telegram_facade`, with:
+   - `TelegramTdlibNotAvailable`
+   - `bootstrap_telegram_auth_from_env(...)`
+   - `get_global_telegram_client(start=False)`
+   - `stop_global_telegram_client()`
+   - `send_telegram_message(...)`
+3. Keep Runtime wrappers thin over current public Core helpers first:
+   - `abstractcore.tools.comms_tools`
+   - `abstractcore.tools.telegram_tdlib`
+   - `abstractcore.tools.telegram_tools`
+4. Keep full abstractagent/tool-type decoupling explicitly out of scope here.
+
+## Scope
+
+- Runtime host facade extension for email/comms
+- Runtime Telegram wrappers for Gateway CLI/bridge/notifier adoption
+- tests proving those surfaces are public, stable, and JSON-safe
+
+## Non-goals
+
+- Do not move Gateway workspace/file policy into Runtime.
+- Do not redesign Core tool execution or the durable `TOOL_CALLS` effect.
+- Do not block this on a full replacement of `abstractcore.tools.ToolCall` inside AbstractAgent.
+- Do not block this phase on Runtime-owned tool-spec adapters; track those separately.
+- Do not introduce new Core HTTP endpoints just to satisfy Gateway.
+
+## Dependencies and related tasks
+
+- `../completed/019_runtime_host_facade_for_core_operator_surfaces.md`
+- `../completed/026_runtime_host_discovery_facade_for_core_catalogs.md`
+- `../completed/027_runtime_durable_bloc_prompt_cache_facade.md`
+- `../completed/028_runtime_bloc_kv_lifecycle_and_pruning.md`
+- `../proposed/0031_runtime_tool_spec_adapters_for_gateway_and_mcp.md`
+- `../../../../abstractgateway/docs/backlog/planned/0050_gateway_runtime_boundary_cleanup_for_workspace_comms_and_telegram.md`
+- `../../../../abstractcore/docs/backlog/proposed/0796_runtime_facing_comms_and_telegram_backend_surface.md`
+
+## Expected outcomes
+
+- Gateway can stop importing `abstractcore.tools.comms_tools` directly.
+- Gateway can stop importing `abstractcore.tools.telegram_tdlib` and `telegram_tools` directly.
+- Runtime remains the only lower-level dependency that Gateway imports for these operator/tooling paths.
+- Runtime phase 1 proves whether a later Runtime-owned tool-spec surface is still needed.
+
+## Validation
+
+- focused Runtime tests for new host-facade email methods
+- focused Runtime tests for Telegram wrapper happy/unavailable paths
+- Gateway adoption tests proving direct `abstractcore` imports are removed from those paths
+
+## Progress checklist
+- [ ] Extend `AbstractCoreHostFacade` with email/comms helpers.
+- [ ] Add Runtime-owned Telegram wrapper helpers for bootstrap, send, and global-client lifecycle.
+- [ ] Validate Gateway adoption and re-run focused Runtime/Gateway boundary tests.
+
+## Guidance for the implementing agent
+
+Prefer thin public wrappers over current Core functionality first. If phase 1
+can unblock Gateway without new Core changes, do that. Keep Core item `0796`
+proposed unless Runtime adoption proves the existing public tool modules are
+too unstable or too duplicative. Keep Runtime-owned tool-spec adapters as a
+separate follow-up rather than blocking this narrower comms/Telegram item.