AbstractRuntime 0.4.16__tar.gz → 0.4.18__tar.gz

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

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.18] - 2026-05-21
+
+### Added
+- Runtime now exposes the remaining Gateway-facing comms/Telegram package boundary through public Runtime wrappers:
+  - host-local email helpers on `get_abstractcore_host_facade(...)`
+  - host-local Telegram TDLib/bootstrap/global-client wrappers in `abstractruntime.integrations.abstractcore.telegram_facade`
+- Outbound email and Telegram sends can now execute as durable Runtime-authored child runs through `get_abstractcore_run_facade(...)`:
+  - `send_email(...)`
+  - `send_telegram_message(...)`
+  - `resume_tool_calls(...)` for approval-gated or passthrough tool waits
+
+### Changed
+- Runtime docs and AI-readable `llms.txt` / `llms-full.txt` now distinguish clearly between:
+  - host-local operator comms helpers
+  - durable run-owned outbound comms execution and replay semantics
+- Outbound comms replay now follows the Runtime-owned truth model: recorded send requests and outcomes are replayed as data, not re-executed as external sends.
+
+## [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 +478,9 @@ 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.18...HEAD
+[0.4.18]: https://github.com/lpalbou/abstractruntime/compare/v0.4.17...v0.4.18
+[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.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.16
+Version: 0.4.18
 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.18 • **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.18)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -193,7 +193,8 @@ 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, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
+- For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers remain host-local and nondurable.
 - 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.18}/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.18 • **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.18)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -116,7 +116,8 @@ 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, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
+- For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers remain host-local and nondurable.
 - 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.18}/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/*`.
 
@@ -184,12 +184,14 @@ 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 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`)
 - 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`)
-- 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`)
+- 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 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`, `list_model_residency`, `load_model_residency`, `unload_model_residency`)
+- host-facade email helpers remain host-local wrappers over AbstractCore's public comms helpers (`list_email_accounts`, `list_emails`, `read_email`, `send_email`)
+- run-facade helpers create and resume durable child runs for existing runs (`execute_llm_call`, `execute_tool_calls`, `resume_tool_calls`, `generate_image`, `generate_voice`, `generate_music`, `transcribe_audio`, `send_email`, `send_telegram_message`)
 
 `LLM_CALL` payloads are JSON-safe effect payloads. Common fields:
 - `prompt`, `messages`, `system_prompt`, and convenience `text`
@@ -198,11 +200,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.18}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-05-20
-> Version: 0.4.16
+> Updated: 2026-05-21
+> Version: 0.4.18
 > 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.
@@ -36,7 +36,7 @@ The boundary is intentionally narrow:
 - Generated binary outputs are written to `ArtifactStore` and returned as `artifact_id` / `artifact_ref`, keeping `RunState.vars` and ledger records bounded and JSON-safe.
 - Remote chat media is sent to AbstractCore Server as provider-ready content arrays, but persisted provider-request metadata redacts data URLs so checkpoints and ledgers do not embed media bytes.
 - Provider sessions and prompt-cache objects are not runtime state. Runtime may carry stable cache keys, while AbstractCore clients/servers manage warm caches.
-- Hosts should use Runtime-owned AbstractCore facades for discovery snapshots, prompt-cache/model-residency control operations, and durable run-scoped media child runs instead of reaching through private runtime attachments or importing Core internals directly.
+- Hosts should use Runtime-owned AbstractCore facades for discovery snapshots, prompt-cache/model-residency control operations, and durable run-scoped media/comms child runs instead of reaching through private runtime attachments or importing Core internals directly.
 - Local execution can use richer AbstractCore capability plugins. Remote and hybrid execution map the common media cases to AbstractCore Server endpoints and OpenAI-compatible content arrays, while hybrid keeps tool execution local.
 - Gateway and other hosts compose Runtime with the desired Core/capability/memory profile. Runtime's base package includes the AbstractMemory contract but not backend extras such as LanceDB; hosts choose storage, embeddings, and readiness policy. Hardware profile extras such as `apple`, `gpu`, `all-apple`, and `all-gpu` cascade through AbstractCore when a host selects them.
 - Remote and hybrid clients use explicit Core server URLs and auth headers supplied by the host. Runtime does not read Gateway auth environment variables for provider/model/auth decisions or treat Gateway bearer tokens as Core server/provider credentials.

{abstractruntime-0.4.16 → abstractruntime-0.4.18}/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/018_workspace_access_policy_for_media_and_tools.md`
+   Keep workspace and tool policy explicit while Gateway extracts its local
+   workspace helpers.
+2. `planned/014_remote_tool_worker_executor.md`
+   The public ToolExecutor path is still the larger follow-on after the current
+   Gateway boundary cleanup.
+3. `proposed/0031_runtime_tool_spec_adapters_for_gateway_and_mcp.md`
+   The comms/Telegram boundary cleanup is now complete; the remaining lower
+   pressure follow-up is a Runtime-owned tool-spec surface if Gateway or the
+   MCP worker still need one after adoption.
+
 ## Completed
 
 | ID | Item |
@@ -36,6 +49,9 @@ 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` |
+| 0030 | `completed/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md` |
+| 0032 | `completed/0032_runtime_durable_outbound_comms_truth.md` |
 
 ## Planned
 
@@ -49,10 +65,11 @@ If you are new to the project, start with `../README.md` and `../architecture.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.18/docs/backlog/completed/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md

@@ -0,0 +1,295 @@
+# 0030 Runtime Host Facades For Comms And Telegram, With Tool-Spec Follow-Up Split Out
+
+## Metadata
+- Created: 2026-05-21
+- Status: Completed
+- Completed: 2026-05-21
+
+## 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
+
+- Runtime exposes the public surfaces Gateway needs in order to stop importing
+  `abstractcore.tools.comms_tools` directly.
+- Runtime exposes the public surfaces Gateway needs in order to stop importing
+  `abstractcore.tools.telegram_tdlib` and `telegram_tools` directly.
+- Runtime remains the only lower-level dependency that Gateway needs for these
+  operator/tooling paths once Gateway adopts the new wrappers.
+- Runtime phase 1 proves whether a later Runtime-owned tool-spec surface is
+  still needed; that work stays split into `0031`.
+
+## Validation
+
+- focused Runtime tests for the new host-facade email methods
+- focused Runtime tests for Telegram wrapper happy/unavailable paths
+- focused Runtime wiring proof that the host email helpers still work when the
+  runtime is local/remote/hybrid because they are host-local wrappers, not
+  remote Core server routes
+- aggregate Runtime regression covering the adjacent host-facade behavior
+
+## Progress checklist
+- [x] Extend `AbstractCoreHostFacade` with email/comms helpers.
+- [x] Add Runtime-owned Telegram wrapper helpers for bootstrap, send, and global-client lifecycle.
+- [x] Validate the Runtime surfaces and re-run focused Runtime 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.
+
+## Completion report
+
+### Date
+
+2026-05-21
+
+### Summary
+
+Runtime now exposes the phase-1 public comms and Telegram wrappers that Gateway
+needed for its remaining direct AbstractCore imports:
+
+- host-facade email helpers on `AbstractCoreHostFacade`
+- a separate Runtime-owned `telegram_facade` module for TDLib bootstrap,
+  process-global client lifecycle, and send parity
+
+The implementation stayed intentionally narrow. It did not add remote server
+routes, and it did not mix the lower-pressure tool-spec cleanup back into this
+item.
+
+### What shipped
+
+- Extended `AbstractCoreHostFacade` with:
+  - `list_email_accounts(...)`
+  - `list_emails(...)`
+  - `read_email(...)`
+  - `send_email(...)`
+- Added `abstractruntime.integrations.abstractcore.telegram_facade` with:
+  - `TelegramTdlibNotAvailable`
+  - `bootstrap_telegram_auth_from_env(...)`
+  - `get_global_telegram_client(...)`
+  - `stop_global_telegram_client()`
+  - `send_telegram_message(...)`
+- Exported the new Telegram wrappers from
+  `abstractruntime.integrations.abstractcore`.
+- Updated docs and LLM indexes so the public boundary now points hosts at
+  Runtime instead of direct `abstractcore.tools.*` imports.
+
+### Current code pointers
+
+- `src/abstractruntime/integrations/abstractcore/host_facade.py`
+- `src/abstractruntime/integrations/abstractcore/telegram_facade.py`
+- `src/abstractruntime/integrations/abstractcore/__init__.py`
+- `tests/test_abstractcore_host_facade.py`
+- `tests/test_abstractcore_telegram_facade.py`
+- `docs/integrations/abstractcore.md`
+- `docs/tools-comms.md`
+- `docs/api.md`
+- `docs/faq.md`
+
+### Behavior changes
+
+- Hosts can now use Runtime for operator-scoped email account discovery, email
+  listing/reading, and email sending instead of importing
+  `abstractcore.tools.comms_tools` directly.
+- Hosts can now use Runtime for Telegram TDLib bootstrap, process-global TDLib
+  client lifecycle, and notifier-style `send_telegram_message(...)` instead of
+  importing `abstractcore.tools.telegram_tdlib` or `telegram_tools` directly.
+- The email and Telegram phase-1 wrappers are explicitly **host-local**:
+  - they do not proxy through a remote AbstractCore server
+  - they do not create Runtime run history on their own
+  - the Telegram global client remains process-scoped rather than
+    runtime-instance scoped
+
+### Review notes
+
+- No new ADR was added. This is an extension of the already-established public
+  Runtime facade pattern rather than a new durable architecture rule.
+- The two focused subagent reviews converged on the shipped shape:
+  - email belongs on the existing host facade
+  - Telegram lifecycle belongs in a separate module because it is process-global
+    host state, not normal runtime-instance state
+- Tool-spec adapters remain explicitly deferred to `0031` rather than being
+  silently dropped.
+
+### Tests
+
+- `pytest -q tests/test_abstractcore_host_facade.py tests/test_abstractcore_telegram_facade.py`
+  - Result: `24 passed`
+- `pytest -q tests/test_abstractcore_host_facade.py tests/test_abstractcore_telegram_facade.py tests/test_prompt_cache_modules.py tests/test_model_residency_control_plane.py tests/test_packaging_extras.py`
+  - Result: `53 passed in 0.29s`
+- `python -m compileall src/abstractruntime/integrations/abstractcore`
+  - Result: clean
+- `mkdocs build -q --site-dir /tmp/abstractruntime-0030-docs`
+  - Result: docs build passed; upstream Material for MkDocs emitted a
+    non-blocking roadmap warning
+- `git diff --check`
+  - Result: clean
+
+### Docs
+
+- `README.md`
+- `docs/integrations/abstractcore.md`
+- `docs/tools-comms.md`
+- `docs/api.md`
+- `docs/faq.md`
+- `llms.txt`
+- `llms-full.txt`
+
+### Residual risks
+
+- These wrappers intentionally do not normalize remote/hybrid comms/Telegram
+  behavior through a remote Core server. If a later product requirement wants a
+  remote backend seam for those paths, that should be a separate decision.
+- Gateway adoption is still tracked separately in
+  `../../../../abstractgateway/docs/backlog/planned/0050_gateway_runtime_boundary_cleanup_for_workspace_comms_and_telegram.md`.
+- Gateway's backlog item `0050` still links to the old planned path for this
+  Runtime item. That stale sibling-package link was detected during closure
+  hygiene but was not edited here because Runtime write scope stayed confined to
+  this repository.
+
+### Follow-ups
+
+- Durable outbound comms sends were corrected separately in
+  `completed/0032_runtime_durable_outbound_comms_truth.md` so `0030` can stay
+  an honest record of the narrower package-boundary cleanup it originally
+  shipped.
+- Keep Runtime-owned tool-spec adapters in
+  `../proposed/0031_runtime_tool_spec_adapters_for_gateway_and_mcp.md`.
+- Keep the optional Core seam idea in
+  `../../../../abstractcore/docs/backlog/proposed/0796_runtime_facing_comms_and_telegram_backend_surface.md`
+  proposed unless Runtime or Gateway adoption proves the current public Core
+  wrappers are insufficient.