AbstractRuntime 0.4.17__tar.gz → 0.4.19__tar.gz

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

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.19] - 2026-05-21
+
+### Added
+- Runtime now ships the missed standalone email comms wrapper/export layer for host-local operator surfaces:
+  - `abstractruntime.integrations.abstractcore.comms_facade`
+  - package-level email helper exports from `abstractruntime.integrations.abstractcore`
+
+### Changed
+- Host-facade email helpers now delegate through Runtime's own comms facade instead of importing `abstractcore.tools.comms_tools` directly in the facade method body.
+- Runtime docs and AI-readable `llms.txt` / `llms-full.txt` now describe the standalone email comms facade/export layer alongside the existing host facade, Telegram wrappers, and durable run-owned comms sends.
+
+## [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
@@ -461,7 +489,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.17...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.19...HEAD
+[0.4.19]: https://github.com/lpalbou/abstractruntime/compare/v0.4.18...v0.4.19
+[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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.17
+Version: 0.4.19
 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
@@ -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.17 • **Python:** 3.10+
+**Version:** 0.4.19 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -169,7 +169,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.17)
+## What’s included (v0.4.19)
 
 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 image/voice/music outputs, 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 and the standalone email comms facade 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.17 → abstractruntime-0.4.19}/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.17 • **Python:** 3.10+
+**Version:** 0.4.19 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -92,7 +92,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.17)
+## What’s included (v0.4.19)
 
 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 image/voice/music outputs, 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 and the standalone email comms facade 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.17 → abstractruntime-0.4.19}/docs/api.md

@@ -184,12 +184,15 @@ 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 email comms wrappers: `list_email_accounts(...)`, `list_emails(...)`, `read_email(...)`, `send_email(...)` (`src/abstractruntime/integrations/abstractcore/comms_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_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`, `generate_music`, `transcribe_audio`)
+- 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 delegate to Runtime's host-local comms facade/export layer (`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`

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

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
 > Updated: 2026-05-21
-> Version: 0.4.17
+> Version: 0.4.19
 > 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.
@@ -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.17 → abstractruntime-0.4.19}/docs/backlog/README.md

@@ -12,16 +12,16 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 
 ## 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`
+1. `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`
+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
 
@@ -50,6 +50,8 @@ If you are new to the project, start with `../README.md` and `../architecture.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
 
@@ -60,7 +62,6 @@ 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
 

{abstractruntime-0.4.17/docs/backlog/planned → abstractruntime-0.4.19/docs/backlog/completed}/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md

@@ -1,9 +1,9 @@
-# Planned: Runtime host facades for comms and Telegram, with tool-spec follow-up split out
+# 0030 Runtime Host Facades For Comms And Telegram, With Tool-Spec Follow-Up Split Out
 
 ## Metadata
 - Created: 2026-05-21
-- Status: Planned
-- Completed: N/A
+- Status: Completed
+- Completed: 2026-05-21
 
 ## ADR status
 - Governing ADRs: None
@@ -140,21 +140,28 @@ tool-spec normalization as a separate follow-up.
 
 ## 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.
+- 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 new host-facade email methods
+- focused Runtime tests for the 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
+- 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
-- [ ] 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.
+- [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
 
@@ -163,3 +170,126 @@ 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.

abstractruntime-0.4.19/docs/backlog/completed/0032_runtime_durable_outbound_comms_truth.md

@@ -0,0 +1,165 @@
+# 0032 Runtime Durable Outbound Comms Truth
+
+## Metadata
+- Created: 2026-05-21
+- Status: Completed
+- Completed: 2026-05-21
+- Origin: follow-up correction to `completed/0030_runtime_host_facades_for_comms_telegram_and_tool_specs.md`
+
+## Goal
+
+Close the remaining durability gap left after `0030`: outbound comms sends that
+belong to a run must execute through Runtime so the request and outcome become
+ledgered child-run truth instead of host-local side effects with no Runtime
+record.
+
+## What Shipped
+
+- Extended `AbstractCoreRunFacade` with a generic durable child-run helper:
+  - `execute_tool_calls(...)`
+- Extended `AbstractCoreRunFacade` with a public durable resume helper:
+  - `resume_tool_calls(...)`
+- Extended `AbstractCoreRunFacade` with durable outbound comms helpers:
+  - `send_email(...)`
+  - `send_telegram_message(...)`
+- Kept the existing host-local read/bootstrap wrappers intact:
+  - host-facade email list/read helpers stay operator-scoped
+  - Telegram TDLib bootstrap/global-client helpers stay host-scoped
+- Preserved the replay rule:
+  - Runtime records the send request and the send outcome
+  - replay should show the recorded result
+  - replay should not resend the external email or Telegram message
+
+## Current Code Pointers
+
+- `src/abstractruntime/integrations/abstractcore/run_facade.py`
+- `tests/test_abstractcore_run_facade.py`
+- `docs/integrations/abstractcore.md`
+- `docs/api.md`
+- `docs/faq.md`
+- `docs/tools-comms.md`
+
+## ADR Status
+
+- Governing ADRs: none added
+- ADR impact: none; this extends the already-accepted Runtime-owned durable
+  child-run pattern from the run facade rather than introducing a new durable
+  policy
+
+## Validation
+
+Focused validation:
+
+- `pytest -q tests/test_abstractcore_run_facade.py tests/test_abstractcore_host_facade.py tests/test_abstractcore_telegram_facade.py`
+- Result: `32 passed in 0.19s`
+
+Aggregate validation:
+
+- `pytest -q tests/test_abstractcore_run_facade.py 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: `61 passed in 0.21s`
+
+Syntax/doc sanity:
+
+- `python -m compileall src/abstractruntime/integrations/abstractcore`
+- `mkdocs build -q --site-dir /tmp/abstractruntime-0032-docs`
+
+## Completion Report
+
+### Date
+
+2026-05-21
+
+### Summary
+
+`0030` solved the package-boundary problem for comms and Telegram, but it left
+direct host-wrapper sends nondurable. This item fixes that by making outbound
+email and Telegram sends first-class Runtime child runs through the existing
+`TOOL_CALLS` path and by giving hosts a public `resume_tool_calls(...)` helper
+for approval-gated or passthrough child runs.
+
+The result is narrower than “all comms go through one facade” and cleaner:
+
+- read/bootstrap helpers remain host-local where that still makes sense
+- outbound sends that belong to a run are now Runtime-authored truth
+
+### Behavior Changes
+
+- Hosts can now use `get_abstractcore_run_facade(runtime).send_email(...)` for
+  a ledgered child run instead of performing an unrecorded host-local send.
+- Hosts can now use
+  `get_abstractcore_run_facade(runtime).send_telegram_message(...)` for the
+  same durable behavior.
+- Hosts can now use
+  `get_abstractcore_run_facade(runtime).resume_tool_calls(...)` to continue a
+  waiting comms/tool child run through the same public Runtime boundary.
+- These durable send helpers use the configured Runtime tool executor:
+  - local/hybrid runtimes usually execute immediately
+  - approval-gated or passthrough executors still produce a durable wait that
+    Runtime can resume later
+- Direct host-facade `send_email(...)` and direct
+  `telegram_facade.send_telegram_message(...)` still exist, but they are now
+  explicitly operator/local-helper paths rather than the preferred run-owned
+  send path
+
+### Review Notes
+
+- No new Core seam was needed. Runtime already had the correct durable external
+  side-effect mechanism in `EffectType.TOOL_CALLS`.
+- The important design correction was to put outbound sends on the existing run
+  facade rather than inventing another host wrapper or another execution model.
+- The last practical gap was resumability for waiting tool child runs. That is
+  now part of the same public run-facade contract instead of a test-only
+  internal workflow reconstruction trick.
+- This keeps replay semantics honest: recorded outcomes are replayed as data,
+  not re-executed as real external sends.
+
+### Tests
+
+- `pytest -q tests/test_abstractcore_run_facade.py tests/test_abstractcore_host_facade.py tests/test_abstractcore_telegram_facade.py`
+  - Result: `32 passed in 0.19s`
+- `pytest -q tests/test_abstractcore_run_facade.py 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: `61 passed in 0.21s`
+- `python -m compileall src/abstractruntime/integrations/abstractcore`
+  - Result: clean
+- `mkdocs build -q --site-dir /tmp/abstractruntime-0032-docs`
+  - Result: docs build passed; upstream Material for MkDocs emitted a
+    non-blocking roadmap warning
+
+### Docs
+
+- `README.md`
+- `docs/integrations/abstractcore.md`
+- `docs/api.md`
+- `docs/faq.md`
+- `docs/tools-comms.md`
+- `llms.txt`
+- `llms-full.txt`
+
+### Residual Risks
+
+- Remote runtimes still default to passthrough tools, so durable comms sends may
+  enter a wait instead of executing immediately unless the host configures an
+  executing or approval-resumable tool executor.
+- Operator-only direct sends remain possible through the host-local wrappers.
+  That is intentional for maintenance/bootstrap flows, but hosts should use the
+  durable run facade when the send belongs to workflow truth.
+
+### Practical Proof
+
+- Immediate durable Telegram send smoke:
+  - child run status: `completed`
+  - ledger effect records: `3`
+  - output: `{"success": true, "transport": "bot_api", "message_ids": [42]}`
+- Approval-gated durable email smoke:
+  - initial child run status: `waiting`
+  - wait reason: `user`
+  - wait key prefix: `tool_approval`
+  - resumed child run status: `completed`
+  - output: `{"success": true, "message_id": "<smoke-1>", "account": "ops"}`
+
+### Follow-Ups
+
+- Keep `0030` as the package-boundary cleanup record and this item as the
+  durability correction record; do not collapse them into one historical file.
+- Keep `0031_runtime_tool_spec_adapters_for_gateway_and_mcp.md` separate; this
+  change does not alter the tool-spec follow-up.

{abstractruntime-0.4.17 → abstractruntime-0.4.19}/docs/faq.md

@@ -161,6 +161,37 @@ These are snapshot/query reads, not durable `LLM_CALL` effects, so replay should
 re-querying the current machine or server and pretending the answer is unchanged.
 Docs: `integrations/abstractcore.md`. Code: `src/abstractruntime/integrations/abstractcore/discovery_facade.py`, `src/abstractruntime/integrations/abstractcore/discovery_queries.py`, `src/abstractruntime/integrations/abstractcore/llm_client.py`.
 
+## Should Gateway or another host import AbstractCore comms or Telegram helpers directly?
+
+No. For the remaining host/operator paths, use Runtime's public wrappers instead:
+
+- `get_abstractcore_host_facade(runtime).list_email_accounts(...)`
+- `...list_emails(...)`
+- `...read_email(...)`
+- `...send_email(...)`
+- `abstractruntime.integrations.abstractcore.list_email_accounts(...)`
+- `...list_emails(...)`
+- `...read_email(...)`
+- `...send_email(...)`
+- `abstractruntime.integrations.abstractcore.telegram_facade.bootstrap_telegram_auth_from_env(...)`
+- `...get_global_telegram_client(...)`
+- `...stop_global_telegram_client()`
+- `...send_telegram_message(...)`
+
+Important nuance: the read/bootstrap wrappers are still **host-local**. They do not proxy through a remote Core
+server, and they do not write durable Runtime history on their own. They exist so hosts can depend
+on Runtime as the package boundary instead of importing `abstractcore.tools.comms_tools`,
+`abstractcore.tools.telegram_tdlib`, or `abstractcore.tools.telegram_tools` directly.
+
+For outbound sends that belong to a run, use the durable run facade instead:
+
+- `get_abstractcore_run_facade(runtime).send_email(...)`
+- `get_abstractcore_run_facade(runtime).send_telegram_message(...)`
+- `get_abstractcore_run_facade(runtime).resume_tool_calls(...)` when an approval-gated or passthrough tool child run needs to continue
+
+Those create child runs, record the send request and outcome in the ledger, and replay should show
+the recorded result rather than resending the external message.
+
 ## Should a host execute image / TTS / music / STT directly for an existing run?
 
 No. If the work is run-scoped and should become part of durable run history, the host should ask Runtime to execute it. Use `abstractruntime.integrations.abstractcore.get_abstractcore_run_facade(runtime)` and create a child run with `generate_image(...)`, `generate_voice(...)`, `generate_music(...)`, `transcribe_audio(...)`, or the lower-level `execute_llm_call(...)`.