AbstractRuntime 0.4.13__tar.gz → 0.4.15__tar.gz

{abstractruntime-0.4.13 → abstractruntime-0.4.15}/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.15] - 2026-05-20
+
+### Added
+- Public AbstractCore Runtime facades for:
+  - discovery/catalog snapshot queries (`get_abstractcore_discovery_facade(...)`)
+  - prompt-cache and model-residency host control operations (`get_abstractcore_host_facade(...)`)
+  - durable run-scoped child-run execution for image, TTS, STT, and direct LLM calls (`get_abstractcore_run_facade(...)`)
+- `EffectType.MODEL_RESIDENCY` with AbstractCore-backed load/list/unload handling and VisualFlow lowering support for runtime-owned model residency control.
+
+### Changed
+- Minimum optional AbstractCore dependency floor is now `abstractcore>=2.13.20`.
+- Local cached-vision discovery now depends on AbstractCore's public `get_local_vision_cache_catalog()` helper instead of private server internals.
+- Local media residency no-op/unsupported responses now complete truthfully with warning/degraded metadata, and media-only results distinguish runtime orchestration identity from the actual media backend identity.
+- Documentation was refreshed for the current Runtime/Core boundary, including root docs, ADR/backlog references, and AI-readable `llms.txt` / `llms-full.txt`.
+
+## [0.4.14] - 2026-05-19
+
+### Fixed
+- Runtime extras that pull AbstractCore provider/tool dependencies now declare current compatible OpenAI/httpx/anyio bounds directly, preventing Python 3.10 pip installs from backtracking through the full OpenAI 1.x history.
+
 ## [0.4.13] - 2026-05-19
 
 ### Fixed
@@ -414,7 +434,15 @@ 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.7...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.15...HEAD
+[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
+[0.4.13]: https://github.com/lpalbou/abstractruntime/compare/v0.4.12...v0.4.13
+[0.4.12]: https://github.com/lpalbou/abstractruntime/compare/v0.4.11...v0.4.12
+[0.4.11]: https://github.com/lpalbou/abstractruntime/compare/v0.4.10...v0.4.11
+[0.4.10]: https://github.com/lpalbou/abstractruntime/compare/v0.4.9...v0.4.10
+[0.4.9]: https://github.com/lpalbou/abstractruntime/compare/v0.4.8...v0.4.9
+[0.4.8]: https://github.com/lpalbou/abstractruntime/compare/v0.4.7...v0.4.8
 [0.4.7]: https://github.com/lpalbou/abstractruntime/compare/v0.4.6...v0.4.7
 [0.4.6]: https://github.com/lpalbou/abstractruntime/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/lpalbou/abstractruntime/compare/v0.4.4...v0.4.5

{abstractruntime-0.4.13 → abstractruntime-0.4.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.13
+Version: 0.4.15
 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,27 +23,48 @@ Requires-Python: >=3.10
 Requires-Dist: abstractmemory>=0.2.6
 Requires-Dist: abstractsemantics>=0.0.3
 Provides-Extra: abstractcore
-Requires-Dist: abstractcore>=2.13.15; extra == 'abstractcore'
+Requires-Dist: abstractcore>=2.13.20; 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.15; extra == 'all-apple'
+Requires-Dist: abstractcore[all-apple]>=2.13.20; 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.15; extra == 'all-gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.13.20; 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.15; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.13.20; 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'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'apple'
 Provides-Extra: docs
 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.15; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.13.20; 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.15; extra == 'mcp-worker'
+Requires-Dist: abstractcore[tools]>=2.13.20; 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.15; extra == 'multimodal'
+Requires-Dist: abstractcore[audio,remote,vision,voice]>=2.13.20; 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'
 Requires-Dist: pandas<3.0.0,>=1.0.0; extra == 'multimodal'
 Requires-Dist: pillow<13.0.0,>=10.0.0; extra == 'multimodal'
 Requires-Dist: pymupdf-layout<2.0.0,>=1.26.6; extra == 'multimodal'
@@ -60,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.10 • **Python:** 3.10+
+**Version:** 0.4.15 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -94,7 +115,7 @@ AbstractCore integration (LLM + tools):
 pip install "abstractruntime[abstractcore]"
 ```
 
-The `abstractcore` extra installs AbstractCore 2.13.13 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, current tool catalog, public output-selector contract, and async/sync text-generation output-selector parity are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
+The `abstractcore` extra installs AbstractCore 2.13.20 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, 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.
 
 Hardware profile cascades are available for native Python installs:
 `abstractruntime[apple]`, `abstractruntime[gpu]`, `abstractruntime[all-apple]`,
@@ -148,7 +169,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.10)
+## What’s included (v0.4.15)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -172,7 +193,7 @@ Drivers + distribution:
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Optional integrations:
-- AbstractCore (LLM + tools, cached sessions/prompt cache, media inputs, generated media, tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions/prompt cache, media inputs, generated media, 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.13 → abstractruntime-0.4.15}/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.10 • **Python:** 3.10+
+**Version:** 0.4.15 • **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.13 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, current tool catalog, public output-selector contract, and async/sync text-generation output-selector parity are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
+The `abstractcore` extra installs AbstractCore 2.13.20 or newer so the hardened server auth model, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, 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.
 
 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.10)
+## What’s included (v0.4.15)
 
 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, cached sessions/prompt cache, media inputs, generated media, tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions/prompt cache, media inputs, generated media, 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.13 → abstractruntime-0.4.15}/docs/adr/0002_execution_modes_local_remote_hybrid.md

@@ -34,6 +34,6 @@ effect payloads, client construction arguments, or Runtime-owned environment var
 ### See Also
 - Implementation: [`backlog/completed/005_abstractcore_integration.md`](../backlog/completed/005_abstractcore_integration.md)
 - Integration guide: [`integrations/abstractcore.md`](../integrations/abstractcore.md)
-- Gateway install boundary: [`backlog/proposed/2026-05-08_runtime_gateway_install_boundary.md`](../backlog/proposed/2026-05-08_runtime_gateway_install_boundary.md)
+- Gateway install boundary: [`backlog/completed/020_runtime_gateway_install_boundary.md`](../backlog/completed/020_runtime_gateway_install_boundary.md)
 - Code: `src/abstractruntime/integrations/abstractcore/factory.py`
 - Framework ADR: `../../../docs/adr/0033-install-profiles-config-entrypoints-and-server-boundaries.md`

abstractruntime-0.4.15/docs/adr/0004_runtime_owns_run_scoped_media_execution_truth.md

@@ -0,0 +1,44 @@
+## ADR 0004: Runtime owns run-scoped media execution truth
+
+### Status
+Accepted (2026-05-20)
+
+### Context
+Hosts sometimes need to trigger image generation, TTS, or STT for an existing run after the main workflow was already created.
+
+If a host executes that media work directly and only appends ledger-like records afterward, Runtime is no longer the
+source of truth for:
+
+- what was requested;
+- what provider/model path actually executed;
+- which artifacts were produced;
+- how replay should represent the step.
+
+We also observed that local media residency can be misunderstood as successful warmup even when the local execution mode
+is a one-shot subprocess boundary that cannot reuse the previous warm state.
+
+### Decision
+AbstractRuntime owns run-scoped media execution truth.
+
+Specifically:
+
+- Hosts must route run-scoped image/TTS/STT work through Runtime, not execute it out-of-band.
+- The integration provides a public durable run facade that creates Runtime-owned child runs for these operations.
+- Operator/control-plane prompt-cache and model-residency controls remain separate host-oriented helpers and do not
+  create durable run history by themselves.
+- Local unsupported media residency must be reported explicitly with machine-readable fields such as
+  `execution_mode`, `requires_long_lived_server`, and `config_hint`.
+- Media-only normalized results must separate orchestration identity from actual media backend identity via
+  `runtime_provider` / `runtime_model` and `media_provider` / `media_model`.
+
+### Consequences
+- Gateway/other hosts have a clean migration target for run-scoped media routes without synthesizing history after the
+  fact.
+- Ledger and artifact truth stay Runtime-authored and replay-friendly.
+- Optional local media warmup can remain non-fatal while still rendering honestly as a warning/no-op.
+- Consumers can distinguish the runtime orchestration model from the media backend that produced the output.
+
+### See Also
+- Implementation: [`../backlog/completed/023_truthful_local_media_residency_boundaries.md`](../backlog/completed/023_truthful_local_media_residency_boundaries.md)
+- Implementation: [`../backlog/completed/024_runtime_owned_run_scoped_media_execution.md`](../backlog/completed/024_runtime_owned_run_scoped_media_execution.md)
+- Integration guide: [`../integrations/abstractcore.md`](../integrations/abstractcore.md)

abstractruntime-0.4.15/docs/adr/0005_runtime_owns_abstractcore_host_discovery_queries.md

@@ -0,0 +1,55 @@
+## ADR 0005: Runtime owns AbstractCore host discovery queries
+
+### Status
+Accepted (2026-05-20)
+
+### Context
+Gateway and other hosts still need to answer operator and thin-client discovery questions such as:
+
+- which providers are available;
+- which models a provider exposes;
+- what a model's capabilities are;
+- which voice, TTS, STT, and vision catalogs are currently visible;
+- which local vision models are cached.
+
+Before this decision, those reads were often handled outside Runtime by:
+
+- raw HTTP proxying from Gateway to AbstractCore server routes;
+- direct imports of public `abstractcore.*` registries and helpers from Gateway;
+- in at least one case, direct import of a Core-server route implementation.
+
+That creates an inconsistent boundary: execution and some controls go through Runtime, but discovery reads bypass it entirely.
+
+These discovery reads are not durable run truth in the same sense as `LLM_CALL`, `TOOL_CALLS`, or run-scoped media child runs. They are current-environment snapshots that may change between the original query and a later replay.
+
+### Decision
+AbstractRuntime owns the host-facing AbstractCore discovery/query boundary.
+
+Specifically:
+
+- Hosts should ask Runtime for AbstractCore discovery and catalog queries rather than importing Core registries or proxying Core server routes directly.
+- Runtime provides a public discovery facade for host-oriented snapshot queries.
+- These discovery methods are query/snapshot oriented, not durable run effects.
+- Replay or audit consumers should treat discovery results as recorded snapshots when they are persisted by hosts, not as work that should be re-executed automatically.
+- Gateway-local liveness, auth, install diagnostics, and non-Core helper projections may remain host-local.
+
+### Consequences
+- Runtime becomes the single Python integration boundary for AbstractCore execution, control, and discovery surfaces.
+- Gateway can shrink into an HTTP projection layer rather than a second Core integration layer.
+- Discovery results remain semantically distinct from durable run execution truth.
+- Some local discovery implementations may still require Runtime integration code to adapt Core capability helpers or server-backed routes until Core exposes cleaner public helpers.
+
+### Enforcement
+- New Gateway or host adoption work should prefer Runtime facades over direct `abstractcore.*` imports for discovery/catalog routes.
+- Runtime docs should distinguish durable run work, operator controls, and snapshot discovery queries.
+- Direct Gateway reach-through to `runtime._abstractcore_llm_client` remains prohibited when a public facade exists.
+
+### Validation
+- Runtime tests should cover local and remote discovery facade behavior.
+- Documentation should show the public discovery facade entrypoint and its scope.
+- Follow-up backlog work in hosts should remove direct Core discovery bypasses where the facade now covers them.
+
+### See Also
+- Implementation: [`../backlog/planned/026_runtime_host_discovery_facade_for_core_catalogs.md`](../backlog/planned/026_runtime_host_discovery_facade_for_core_catalogs.md)
+- Existing operator controls: [`0004_runtime_owns_run_scoped_media_execution_truth.md`](0004_runtime_owns_run_scoped_media_execution_truth.md)
+- Integration guide: [`../integrations/abstractcore.md`](../integrations/abstractcore.md)

{abstractruntime-0.4.13 → abstractruntime-0.4.15}/docs/adr/README.md

@@ -16,6 +16,8 @@ When you ask "why is it designed this way?", the answer is in an ADR. ADRs are:
 | 0001 | [Layered Coupling with AbstractCore](0001_layered_coupling_with_abstractcore.md) | Accepted | 2025-12-11 | Kernel stays dependency-light; AbstractCore integration is opt-in |
 | 0002 | [Execution Modes](0002_execution_modes_local_remote_hybrid.md) | Accepted | 2025-12-11 | Support local, remote, and hybrid execution topologies |
 | 0003 | [Provenance Hash Chain](0003_provenance_tamper_evident_hash_chain.md) | Accepted | 2025-12-11 | Tamper-evident ledger first; cryptographic signatures deferred |
+| 0004 | [Runtime Owns Run-Scoped Media Execution Truth](0004_runtime_owns_run_scoped_media_execution_truth.md) | Accepted | 2026-05-20 | Hosts must route run-scoped media execution through Runtime |
+| 0005 | [Runtime Owns AbstractCore Host Discovery Queries](0005_runtime_owns_abstractcore_host_discovery_queries.md) | Accepted | 2026-05-20 | Hosts should ask Runtime for Core discovery/catalog snapshots |
 
 ## Relationship to Backlog
 
@@ -26,6 +28,8 @@ ADRs explain *why*. Backlog items explain *what* and *how*.
 | 0001 | `backlog/completed/005_abstractcore_integration.md` |
 | 0002 | `backlog/completed/005_abstractcore_integration.md` |
 | 0003 | `backlog/completed/007_provenance_hash_chain.md`, `backlog/planned/008_signatures_and_keys.md` |
+| 0004 | `backlog/completed/023_truthful_local_media_residency_boundaries.md`, `backlog/completed/024_runtime_owned_run_scoped_media_execution.md` |
+| 0005 | `backlog/completed/026_runtime_host_discovery_facade_for_core_catalogs.md` |
 
 ## Adding New ADRs
 
@@ -34,4 +38,3 @@ When making a significant architectural decision:
 2. Use the template: Status, Context, Decision, Consequences
 3. Set status to "Accepted" once the decision is final
 4. If superseding an old ADR, update the old one's status to "Superseded by NNNN"
-

{abstractruntime-0.4.13 → abstractruntime-0.4.15}/docs/api.md

@@ -176,15 +176,20 @@ This produces a portable record of a run’s state + ledger + artifacts suitable
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.12 or newer).
+Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.20 or newer).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
 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 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`)
-- prompt-cache control methods on the configured LLM client: `get_prompt_cache_capabilities`, `get_prompt_cache_stats`, `prompt_cache_set`, `prompt_cache_update`, `prompt_cache_fork`, `prompt_cache_clear`, `prompt_cache_prepare_modules` (`src/abstractruntime/integrations/abstractcore/llm_client.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`, `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`)
 
 `LLM_CALL` payloads are JSON-safe effect payloads. Common fields:
 - `prompt`, `messages`, `system_prompt`, and convenience `text`
@@ -198,6 +203,8 @@ Multimodal support:
 - 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 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
+- 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
 
 Prompt cache / cached sessions:

{abstractruntime-0.4.13 → abstractruntime-0.4.15}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-05-08
-> Version: 0.4.9
+> Updated: 2026-05-20
+> Version: 0.4.15
 > 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,6 +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.
 - 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.
@@ -168,7 +169,7 @@ Registered in `Runtime._register_builtin_handlers()` (`src/abstractruntime/core/
 
 ### Host-wired effects
 The kernel defines the protocol; concrete integrations provide handlers:
-- `LLM_CALL`, `TOOL_CALLS`: provided by AbstractCore integration (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). The integration supports local/remote/hybrid execution, cached sessions/prompt-cache control, media inputs, generated media outputs, provider-key header routing for remote servers, passthrough tools, and approval-gated local tool execution.
+- `LLM_CALL`, `TOOL_CALLS`, `MODEL_RESIDENCY`: provided by AbstractCore integration (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). The integration supports local/remote/hybrid execution, cached sessions/prompt-cache control, discovery/catalog snapshots, model residency, durable run-scoped media child runs, media inputs, generated media outputs, provider-key header routing for remote servers, passthrough tools, and approval-gated local tool execution.
 - `MEMORY_KG_*`: provided by the AbstractMemory bridge (`src/abstractruntime/integrations/abstractmemory/effect_handlers.py`)
 
 ### Reliability: retries + idempotency

{abstractruntime-0.4.13 → abstractruntime-0.4.15}/docs/backlog/README.md

@@ -1,8 +1,11 @@
 # Backlog (maintainers)
 
+This README currently serves as the backlog overview for this repository.
+
 This folder contains a structured backlog used during development. Items are grouped as:
 - `completed/` — implemented work items (what shipped, with implementation pointers)
-- `planned/` — future work proposals
+- `planned/` — committed future work items that still match current runtime reality
+- `proposed/` — uncommitted ideas and follow-on risks worth preserving
 - `deprecated/` — historical backlog notes (superseded)
 
 If you are new to the project, start with `../README.md` and `../architecture.md` instead.
@@ -24,6 +27,13 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 | 012 | `completed/012_run_store_query_and_scheduler_support.md` |
 | 013 | `completed/013_effect_retries_and_idempotency.md` |
 | 016 | `completed/016_runtime_aware_parameters.md` |
+| 019 | `completed/019_runtime_host_facade_for_core_operator_surfaces.md` |
+| 020 | `completed/020_runtime_gateway_install_boundary.md` |
+| 021 | `completed/021_runtime_gateway_env_namespace_cleanup.md` |
+| 022 | `completed/022_model_residency_control_plane.md` |
+| 023 | `completed/023_truthful_local_media_residency_boundaries.md` |
+| 024 | `completed/024_runtime_owned_run_scoped_media_execution.md` |
+| 026 | `completed/026_runtime_host_discovery_facade_for_core_catalogs.md` |
 
 ## Planned
 
@@ -31,9 +41,16 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 |----|------|
 | 008 | `planned/008_signatures_and_keys.md` |
 | 014 | `planned/014_remote_tool_worker_executor.md` |
-| 015 | `planned/015_agent_integration_improvements.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` |
+
+## Proposed
+
+| Date | 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` |
 
 ## Deprecated
 

abstractruntime-0.4.15/docs/backlog/completed/019_runtime_host_facade_for_core_operator_surfaces.md

@@ -0,0 +1,181 @@
+# Runtime Host Facade For Core Operator Surfaces
+
+## Metadata
+- Created: 2026-05-20
+- Status: Completed
+- Completed: 2026-05-20
+- Origin: promoted directly from `docs/backlog/proposed/2026-05-20_runtime_host_facade_for_core_operator_surfaces.md`
+
+## Context
+
+`abstractruntime.integrations.abstractcore` already owned the real control-plane behavior for:
+
+- prompt-cache operations
+- model-residency operations
+- local/remote/hybrid runtime topology normalization
+
+But hosts had no stable public Runtime-facing contract for those surfaces. In practice, they either:
+
+1. reached through `runtime._abstractcore_llm_client`, or
+2. rebuilt control-plane behavior outside Runtime
+
+That was inconsistent with the broader Runtime mission: keep execution topology and control semantics inside Runtime so
+hosts request work from Runtime rather than re-deriving integration behavior themselves.
+
+## Current Code Reality At Implementation Time
+
+Already implemented before this item was completed:
+
+- prompt-cache control methods on local, multi-local, and remote AbstractCore clients
+- `MODEL_RESIDENCY` as a Runtime effect
+- truthful local media-residency constraints
+
+Missing or incomplete before this item:
+
+- a public facade/export path for host code
+- documentation telling hosts to use that public path
+- tests proving the public facade works across local, remote, and hybrid runtime factories
+
+## Problem
+
+Hosts needed a narrow, documented control-plane surface for prompt-cache and model-residency operations without:
+
+- hard-coupling `Runtime` itself to an AbstractCore-specific public accessor
+- normalizing too much Gateway/product-level readiness logic into Runtime
+- implying that operator actions are durable run truth
+
+## What We Implemented
+
+Phase 1 shipped the narrow public host facade proposed in the backlog review:
+
+- `AbstractCoreHostFacade`
+- `get_abstractcore_host_facade(...)`
+
+Scope kept intentionally narrow:
+
+- prompt-cache operations
+- model-residency operations
+
+Explicit non-goals preserved:
+
+- no media/TTS/STT helper methods in this item
+- no discovery/catalog/readiness aggregation in this item
+- no provider-private prompt-cache save/load promotion in this item
+- no change to the rule that durable run truth must still flow through Runtime effects/commands
+
+## Files And Symbols Touched
+
+Implementation:
+
+- `src/abstractruntime/integrations/abstractcore/host_facade.py`
+- `src/abstractruntime/integrations/abstractcore/__init__.py`
+- `src/abstractruntime/integrations/abstractcore/factory.py`
+
+Tests:
+
+- `tests/test_abstractcore_host_facade.py`
+
+Docs:
+
+- `docs/integrations/abstractcore.md`
+- `docs/api.md`
+- `docs/faq.md`
+- `llms-full.txt`
+- `docs/backlog/README.md`
+
+## Expected Outcomes
+
+The following are now true:
+
+- hosts have a documented public facade for prompt-cache and model-residency controls
+- the facade delegates to the real AbstractCore-backed Runtime topology instead of duplicating logic
+- local, remote, and hybrid runtime factories all expose the same host-facade entrypoint
+- docs now point hosts at the public facade instead of instructing them to use the private runtime attachment directly
+- factory attachment failures fail fast instead of surfacing as a later opaque facade error
+
+## Validation
+
+Primary validation:
+
+- `pytest -q tests/test_abstractcore_host_facade.py`
+- `pytest -q tests/test_abstractcore_host_facade.py tests/test_prompt_cache_modules.py tests/test_model_residency_control_plane.py`
+
+Example proof run:
+
+- `PYTHONPATH=src python` example using `create_remote_runtime(...)` + `get_abstractcore_host_facade(...)` with a stub request sender
+
+## Completion Report
+
+### Date
+
+2026-05-20
+
+### Summary
+
+Implemented a public, integration-scoped host facade for AbstractCore prompt-cache and model-residency control
+operations. The facade is exported from `abstractruntime.integrations.abstractcore`, documented as the host entrypoint,
+and validated across local, remote, and hybrid runtime construction paths.
+
+### Behavior Changes
+
+- Added `AbstractCoreHostFacade` as the public host-control surface for prompt-cache and model-residency operations.
+- Added `get_abstractcore_host_facade(runtime)` as the documented integration-scoped helper.
+- Exported the facade from `abstractruntime.integrations.abstractcore`.
+- Kept the underlying runtime attachment private, but made factory attachment fail fast if it cannot be installed.
+- Replaced public docs guidance that previously told hosts to access `_abstractcore_llm_client` directly.
+
+### Tests
+
+Local validation run in this completion pass:
+
+- `tests/test_abstractcore_host_facade.py`: `12 passed in 0.20s`
+- `tests/test_abstractcore_host_facade.py tests/test_prompt_cache_modules.py tests/test_model_residency_control_plane.py`: `32 passed in 0.25s`
+
+Independent test-agent validation:
+
+- `tests/test_abstractcore_host_facade.py`: `12 passed`
+- `tests/test_prompt_cache_modules.py`: `10 passed`
+- `tests/test_model_residency_control_plane.py`: `10 passed`
+- aggregate: `32 passed`, `0 failed`, `0 skipped`, `3.00s` aggregate wall time
+
+### Example Evidence
+
+The example proof run used a factory-created remote runtime plus the public facade and produced:
+
+- prompt-cache capabilities response with `mode=keyed`
+- model-residency load response with `runtime_id=rid-42`
+- provider API key forwarded as `X-AbstractCore-Provider-API-Key`
+- correct root-level control URLs:
+  - `http://core.example/acore/prompt_cache/capabilities?...`
+  - `http://core.example/acore/models/load`
+- combined example execution time: `0.056 ms` with an in-memory stub sender
+
+### Docs Updated
+
+- integration guide now shows `get_abstractcore_host_facade(...)`
+- API reference lists the public host facade entrypoint
+- FAQ points hosts at the facade rather than the private runtime attachment
+- `llms-full.txt` reflects the new public contract
+
+### Residual Risks
+
+- The facade still depends internally on the private `_abstractcore_llm_client` runtime attachment; that coupling is
+  now explicit and fail-fast, but it remains an internal integration detail worth revisiting in future refactors.
+- The remote-runtime proof path swaps the underlying client's private `_sender` in tests/example setup, so that one
+  validation path is not purely black-box from the public facade surface.
+- There is no dedicated test for the exceptional attach-failure path in `factory.py`; success-path wiring is covered.
+- The docs snippets are not yet executed as tests.
+
+### Backlog / Code Drift Found
+
+- During this completion pass, the stranded residency proposal was cleaned up separately into
+  `docs/backlog/completed/022_model_residency_control_plane.md`.
+- No `docs/backlog/overview.md` exists in this repository; `docs/backlog/README.md` currently serves as the effective
+  backlog overview and was updated accordingly.
+- No `docs/backlog/recurrent/` directory exists here, so there were no recurrent-task files to scan in this pass.
+
+### Follow-Up Impact
+
+- This completion narrows and stabilizes the Runtime-owned control plane for host code.
+- The remaining adjacent boundary work is still represented by the separate local media truthfulness proposal and the
+  sibling Gateway run-truth item discussed in backlog review.