AbstractRuntime 0.4.19__tar.gz → 0.4.20__tar.gz

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

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.20] - 2026-05-21
+
+### Added
+- Runtime now exposes a public host-local prompt-cache export/import admin surface on `get_abstractcore_host_facade(...)`:
+  - `list_prompt_cache_exports(...)`
+  - `prompt_cache_export(...)`
+  - `prompt_cache_import(...)`
+
+### Changed
+- Local Runtime now owns the prompt-cache export root/catalog policy:
+  - `~/.abstractruntime/prompt_cache_exports` by default
+  - `<base_dir>/prompt_cache_exports` for `create_local_file_runtime(...)`
+  - exact provider/model partitioning with Runtime-managed metadata sidecars
+- Remote and hybrid runtimes now fail honestly for prompt-cache export/import admin with a structured local-only response instead of implying server-side support.
+- Runtime docs and AI-readable `llms.txt` / `llms-full.txt` now document the secondary host-local export/import contract distinctly from the primary durable bloc/binding prompt-cache path.
+
 ## [0.4.19] - 2026-05-21
 
 ### Added
@@ -489,7 +505,8 @@ AbstractRuntime is the durable execution substrate designed to pair with Abstrac
 
 Initial development version with basic proof-of-concept features.
 
-[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.19...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.20...HEAD
+[0.4.20]: https://github.com/lpalbou/abstractruntime/compare/v0.4.19...v0.4.20
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.19
+Version: 0.4.20
 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.19 • **Python:** 3.10+
+**Version:** 0.4.20 • **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.19)
+## What’s included (v0.4.20)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -193,7 +193,7 @@ Drivers + distribution:
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Optional integrations:
-- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, local-only prompt-cache export/import admin, 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

{abstractruntime-0.4.19 → abstractruntime-0.4.20}/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.19 • **Python:** 3.10+
+**Version:** 0.4.20 • **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.19)
+## What’s included (v0.4.20)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -116,7 +116,7 @@ Drivers + distribution:
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Optional integrations:
-- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, durable bloc prompt-cache controls, bindings, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, `MODEL_RESIDENCY`, public discovery/host/run facades, cached sessions, local-only prompt-cache export/import admin, 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

{abstractruntime-0.4.19 → abstractruntime-0.4.20}/docs/api.md

@@ -191,6 +191,7 @@ Entry points:
 - 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 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-local prompt-cache export/import admin also lives on the host facade and client delegation layer (`list_prompt_cache_exports`, `prompt_cache_export`, `prompt_cache_import`) and is intentionally local-only
 - 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`)
 

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

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
 > Updated: 2026-05-21
-> Version: 0.4.19
+> Version: 0.4.20
 > 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.

{abstractruntime-0.4.19 → abstractruntime-0.4.20}/docs/backlog/README.md

@@ -10,6 +10,14 @@ 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.
 
+## Counts
+
+- Planned: 5
+- Proposed: 1
+- Completed: 26
+- Deprecated: 13
+- Recurrent: 0
+
 ## Next recommended work
 
 1. `planned/018_workspace_access_policy_for_media_and_tools.md`
@@ -52,6 +60,7 @@ If you are new to the project, start with `../README.md` and `../architecture.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` |
+| 0033 | `completed/0033_runtime_host_local_prompt_cache_export_import_surface.md` |
 
 ## Planned
 
@@ -67,10 +76,10 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 
 | 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
 
 See `deprecated/DEPRECATED_README.md` for context on the deprecated backlog set.
+Recent deprecation:
+- `deprecated/0034_agent_runtime_convenience_constructor.md`

abstractruntime-0.4.20/docs/backlog/completed/0033_runtime_host_local_prompt_cache_export_import_surface.md

@@ -0,0 +1,184 @@
+# 0033 Runtime Host-Local Prompt-Cache Export/Import Surface
+
+## Metadata
+- Created: 2026-05-20
+- Status: Completed
+- Completed: 2026-05-21
+- Origin: implemented from repository backlog and user request
+
+## Goal
+
+Remove the remaining Gateway prompt-cache export/import bypass by giving Runtime
+a public host-facing surface for:
+
+- listing host-local prompt-cache exports
+- exporting one live local provider cache to disk
+- importing one previously exported local provider cache
+
+without confusing that admin workflow with Runtime's durable bloc/binding
+memory model.
+
+## What Shipped
+
+- Extended `AbstractCoreHostFacade` with:
+  - `list_prompt_cache_exports(...)`
+  - `prompt_cache_export(...)`
+  - `prompt_cache_import(...)`
+- Implemented the local behavior in Runtime's AbstractCore clients on top of
+  Core's existing **public** provider hooks:
+  - `prompt_cache_save(...)`
+  - `prompt_cache_load(...)`
+  - `prompt_cache_artifact_extension()`
+  - `prompt_cache_artifact_format()`
+  - prompt-cache capability flags
+- Kept the surface honest:
+  - **local-only** for local/file runtimes
+  - remote and hybrid return structured `prompt_cache_local_only` payloads and
+    do not issue HTTP requests
+- Added a Runtime-owned export root policy:
+  - default local root: `~/.abstractruntime/prompt_cache_exports`
+  - default file-runtime root: `<base_dir>/prompt_cache_exports`
+  - explicit `prompt_cache_export_root_dir=...` overrides are supported
+- Added Runtime-owned listing/catalog metadata so hosts no longer need a
+  Gateway-local `saved/` directory convention
+- Kept per-provider/model separation exact by partitioning export directories
+  with reversible encoded provider/model ids instead of lossy slugs
+- Preserved the broader prompt-cache boundary:
+  - durable app-facing exact reuse is still `bloc + KV artifact + prompt_cache_binding`
+  - host-local export/import remains secondary operator/admin tooling around
+    live local provider cache state
+
+## Current Code Pointers
+
+- `src/abstractruntime/integrations/abstractcore/host_facade.py`
+- `src/abstractruntime/integrations/abstractcore/llm_client.py`
+- `src/abstractruntime/integrations/abstractcore/factory.py`
+- `tests/test_prompt_cache_export_import.py`
+- `tests/test_abstractcore_host_facade.py`
+- `tests/test_remote_llm_client.py`
+- `docs/integrations/abstractcore.md`
+- `docs/api.md`
+- `docs/faq.md`
+- `README.md`
+
+Related accepted prompt-cache policy still lives in:
+- `docs/adr/0006_runtime_owns_durable_abstractcore_bloc_prompt_cache.md`
+
+No new ADR was added. This item extends the existing host-surface boundary
+without changing the durable app contract.
+
+## Validation
+
+Focused validation run on 2026-05-21:
+
+- `pytest -q tests/test_prompt_cache_export_import.py tests/test_abstractcore_host_facade.py tests/test_remote_llm_client.py`
+- Result: `29 passed in 0.24s`
+
+Broader regression and packaging-adjacent sanity:
+
+- `pytest -q tests/test_prompt_cache_export_import.py tests/test_abstractcore_host_facade.py tests/test_remote_llm_client.py tests/test_prompt_cache_modules.py tests/test_packaging_extras.py`
+- Result: `48 passed in 0.21s`
+
+Syntax/import sanity:
+
+- `python -m compileall src/abstractruntime/integrations/abstractcore`
+- Result: clean
+
+Documentation build sanity:
+
+- `mkdocs build -q --site-dir /tmp/abstractruntime-0033-docs`
+- Result: build passed; upstream Material for MkDocs emitted its current
+  non-blocking MkDocs 2.0 warning
+
+Practical proof covered by the shipped tests:
+
+- local/multi-local Runtime can export, list, and import prompt-cache
+  artifacts through Runtime's public host facade and local client path
+- the same logical export name can coexist for distinct provider/model ids
+  without directory collisions
+- local listing no longer requires loading the target provider/model client to
+  exist on disk
+- remote Runtime returns `prompt_cache_local_only` for list/export/import and
+  does not emit HTTP traffic
+- `create_local_file_runtime(...)` now wires the default export root to
+  `<base_dir>/prompt_cache_exports`
+
+## Completion Report
+
+### Date
+
+2026-05-21
+
+### Summary
+
+Runtime now owns the last prompt-cache admin surface that Gateway was still
+handling through private provider/runtime internals.
+
+Hosts can keep manual provider-native export/import when they genuinely need
+it, but the contract is now:
+
+- public Runtime boundary
+- Core public hooks underneath
+- local-only filesystem semantics made explicit
+- clean separation from durable bloc/binding workflow memory
+
+### Behavior Changes
+
+- `get_abstractcore_host_facade(runtime)` now exposes:
+  - `list_prompt_cache_exports(...)`
+  - `prompt_cache_export(...)`
+  - `prompt_cache_import(...)`
+- Local/file runtimes store host-local prompt-cache exports under a Runtime
+  root rather than letting Gateway or another host invent its own unmanaged
+  directory contract.
+- Listing is now Runtime-owned and returns catalog metadata for one
+  provider/model partition.
+- `prompt_cache_import(clear_existing=True)` now validates the artifact before
+  clearing live cache state, then performs the clear/load sequence so a corrupt
+  file does not wipe the old cache first.
+- When the caller omits `key` on import, Runtime now surfaces the effective
+  loaded key returned by the provider instead of dropping it.
+
+### Contract Notes
+
+- This is intentionally a **host-local admin** contract. It is not a durable
+  workflow effect and it is not replayed like `LLM_CALL`.
+- Runtime currently returns `root_dir`, `artifact_path`, and `meta_path` in the
+  public payload because this is a host/operator surface and Gateway still
+  needs a real listing/catalog replacement. That path exposure is intentional
+  for this local admin surface, not the general durable app contract.
+- Remote/hybrid runtimes do not proxy or fake host-local export roots. They
+  fail honestly with `prompt_cache_local_only`.
+
+### Tests
+
+- `tests/test_prompt_cache_export_import.py`
+- `tests/test_abstractcore_host_facade.py`
+- regression support in:
+  - `tests/test_remote_llm_client.py`
+
+### Docs
+
+- `README.md`
+- `docs/integrations/abstractcore.md`
+- `docs/api.md`
+- `docs/faq.md`
+- `llms.txt`
+- `llms-full.txt`
+
+### Residual Risks
+
+- This is still a secondary operator feature. The primary prompt-cache story
+  for durable apps remains bloc/KV artifacts plus `prompt_cache_binding`.
+- Import/export support still depends on the local AbstractCore backend family
+  and the public `supports_save` / `supports_load` capability flags.
+- Gateway adoption is still separate work in the sibling package before
+  `/prompt_cache/saved|save|load` is fully cleaned up end-to-end.
+
+### Follow-Ups
+
+- Gateway should adopt these Runtime host-facade methods and remove its
+  remaining private `/prompt_cache/saved|save|load` implementation.
+- Keep AbstractCore item `0797` only as optional follow-up memory. Promote it
+  only if Runtime/Gateway later prove they need a narrower cross-provider
+  metadata/compatibility contract than the current public hooks provide.

abstractruntime-0.4.20/docs/backlog/deprecated/0034_agent_runtime_convenience_constructor.md

@@ -0,0 +1,85 @@
+# Deprecated: Agent Runtime Convenience Constructor
+
+## Metadata
+- Created: 2026-05-20
+- Status: Deprecated
+- Completed: N/A
+- Deprecated: 2026-05-21
+
+## Context
+
+The old `015_agent_integration_improvements` item no longer fits as planned runtime work.
+
+Most of the important integration correctness work is already done:
+
+- agent tool execution can go through durable `TOOL_CALLS`
+- runtime tool execution is host-configured through `ToolExecutor`
+- agent state persistence is not blocked on runtime internals
+
+The main remaining idea is much smaller: a convenience constructor such as
+`create_agent_runtime(...)` that would wrap `create_local_runtime(...)` plus
+`MappingToolExecutor.from_tools(...)` for simple local setups.
+
+## Current code reality
+
+- `src/abstractruntime/integrations/abstractcore/factory.py`
+  - already exposes the generic Runtime constructor layer:
+    - `create_local_runtime(...)`
+    - `create_remote_runtime(...)`
+    - `create_hybrid_runtime(...)`
+- `../abstractagent/src/abstractagent/agents/react.py`
+  - already wraps `create_local_runtime(...)` +
+    `MappingToolExecutor.from_tools(...)`
+- `../abstractagent/src/abstractagent/agents/codeact.py`
+  - does the same for CodeAct
+- `../abstractagent/src/abstractagent/agents/memact.py`
+  - does the same for MemAct
+- `../abstractflow/abstractflow/visual/executor.py`
+  - assembles its own Runtime/tool wiring with different host-specific policy
+
+The duplication exists, but it is concentrated in higher-level packages that
+already own agent or host semantics.
+
+## Why it is not planned now
+
+- It is an ergonomics improvement, not a runtime correctness gap.
+- The API shape depends on cross-repo expectations from `abstractagent`.
+- This repo should stay careful about adding convenience APIs that quietly pull in higher-level agent assumptions.
+
+## Possible future direction
+
+- keep the helper explicitly local-only
+- accept direct tool functions and build the `MappingToolExecutor`
+- avoid storing callables in durable run state
+- document clearly that advanced approval/passthrough/delegated tool setups should still use the lower-level factories directly
+
+## Guidance
+
+Re-promote this only if maintainers still want a tiny convenience API after the higher-priority runtime boundary work lands.
+
+## Deprecation report
+
+Deprecated: 2026-05-21
+
+Reason:
+
+- Runtime already has the correct generic constructor layer.
+- The exact convenience pattern is agent-shaped rather than runtime-shaped.
+- The real duplication is currently in `abstractagent`, not across Runtime
+  consumers generally.
+
+What replaced it:
+
+- Nothing new in Runtime. Higher-level packages should keep owning their own
+  factories or factor a shared helper in their own package.
+
+Why it should not be built here:
+
+- A public `create_agent_runtime(...)` would encode agent-level assumptions into
+  the lower-level Runtime package.
+- Sibling packages do not share one uniform shape anyway: some use
+  approval/passthrough executors or other host policy that a tiny Runtime
+  convenience wrapper would not capture cleanly.
+
+If this idea returns later, it should start in `abstractagent` as a package-
+owned helper rather than a new public Runtime API.

{abstractruntime-0.4.19 → abstractruntime-0.4.20}/docs/backlog/deprecated/DEPRECATED_README.md

@@ -28,6 +28,9 @@ These were temporary implementation specs created in the abstractcore workspace
 - `005_docs_updates.md` - Implemented
 - `README.md` - Original context document (preserved as-is)
 
+### From Current Numbered Backlog
+- `0034_agent_runtime_convenience_constructor.md` - Deprecated on 2026-05-21 because the convenience pattern is agent-shaped and belongs in `abstractagent` if it is needed at all
+
 ## Note
 
 Do not add new items here. Use `completed/` for finished work and `planned/` for future work.

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

@@ -120,6 +120,29 @@ Gateway-specific prompt-cache environment variables should be consumed by Gatewa
 Hosts can inspect, prepare, and now clean up caches through `abstractruntime.integrations.abstractcore.get_abstractcore_host_facade(runtime)`, which exposes the normal prompt-cache/model-residency controls plus durable bloc helpers such as `upsert_text_bloc(...)`, `ensure_bloc_kv_artifact(...)`, `load_bloc_kv_artifact(...)`, `list_bloc_kv_artifacts(...)`, `delete_bloc_kv_artifact(...)`, and `delete_bloc(...)` without depending on the private runtime attachment directly.
 Docs: `integrations/abstractcore.md`. Code: `src/abstractruntime/integrations/abstractcore/host_facade.py`, `src/abstractruntime/integrations/abstractcore/llm_client.py`.
 
+## Can a host still export or import local provider prompt caches?
+
+Yes, but treat that as **host-local operator tooling**, not the main durable
+workflow memory model.
+
+Use the Runtime host facade:
+- `list_prompt_cache_exports(...)`
+- `prompt_cache_export(...)`
+- `prompt_cache_import(...)`
+
+Important limits:
+- this surface is **local-only**; remote and hybrid runtimes return
+  `prompt_cache_local_only`
+- Runtime owns the export root policy:
+  - `~/.abstractruntime/prompt_cache_exports` by default
+  - `<base_dir>/prompt_cache_exports` for `create_local_file_runtime(...)`
+- exports are partitioned per provider/model, so the same logical export name
+  can coexist cleanly across different local backends
+
+For durable replay-safe workflow reuse, prefer `prompt_cache_binding` from
+durable bloc/KV artifacts instead of host-local provider cache exports.
+Docs: `integrations/abstractcore.md`. Code: `src/abstractruntime/integrations/abstractcore/host_facade.py`, `src/abstractruntime/integrations/abstractcore/llm_client.py`.
+
 ## Does Runtime duplicate durable bloc text? How do per-model caches relate to it?
 
 For local runtimes, Runtime owns the bloc root and stores one durable **text snapshot** per SHA256 within that root. That bloc is the source of truth. The provider/model cache is a **derived artifact** under that bloc, not a second independent memory model.

{abstractruntime-0.4.19 → abstractruntime-0.4.20}/docs/integrations/abstractcore.md

@@ -322,6 +322,9 @@ AbstractRuntime's AbstractCore integration now exposes a public host-control fac
 - `prompt_cache_fork(...)`
 - `prompt_cache_clear(...)`
 - `prompt_cache_prepare_modules(...)`
+- `list_prompt_cache_exports(...)`
+- `prompt_cache_export(...)`
+- `prompt_cache_import(...)`
 - `upsert_text_bloc(...)`
 - `get_bloc_record(...)`
 - `list_blocs(...)`
@@ -359,7 +362,9 @@ Contract notes:
 - The three prompt-cache tracks are distinct:
   - session prompt cache: best-effort volatile reuse
   - durable bloc prompt cache: exact reuse through bloc/KV/binding
-  - snapshot prompt-cache admin: separate local-admin work, if enabled later
+  - host-local prompt-cache export/import admin: optional operator tooling
+    around live local provider cache state, separate from durable workflow
+    memory
 
 Host-side prompt-cache example:
 
@@ -416,6 +421,38 @@ loaded = facade.load_bloc_kv_artifact(
 binding = loaded["artifact"]["prompt_cache_binding"]
 ```
 
+Host-local prompt-cache export/import example:
+
+```python
+saved = facade.prompt_cache_export(
+    name="orbit-cache",
+    key="sess:orbit",
+    q8=True,
+)
+listed = facade.list_prompt_cache_exports()
+loaded_cache = facade.prompt_cache_import(
+    name="orbit-cache",
+    key="loaded:orbit",
+    clear_existing=True,
+)
+```
+
+Host-local export/import contract:
+
+- This surface is **local-only**. Remote and hybrid runtimes return structured
+  `prompt_cache_local_only` payloads instead of proxying host filesystem state
+  through Core Server.
+- Runtime owns the export root policy:
+  - default local root: `~/.abstractruntime/prompt_cache_exports`
+  - default file-runtime root: `<base_dir>/prompt_cache_exports`
+  - explicit `prompt_cache_export_root_dir=...` overrides are allowed when a
+    host needs a different local catalog root
+- Exports stay partitioned by provider/model under that root, so the same
+  logical export name can coexist safely across different local backends.
+- This is a **secondary operator/admin feature**, not the primary durable app
+  contract. For replay-safe exact reuse inside workflows, prefer
+  `prompt_cache_binding` from durable bloc/KV artifacts instead.
+
 Host-side durable bloc lifecycle example:
 
 ```python

{abstractruntime-0.4.19 → abstractruntime-0.4.20}/llms-full.txt

@@ -10,7 +10,7 @@ This file is an **agent-oriented build guide** for the AbstractRuntime *library*
 
 Quick facts:
 - Python: 3.10+ (`pyproject.toml`)
-- Version: 0.4.19
+- Version: 0.4.20
 - Ecosystem: [AbstractFramework](https://github.com/lpalbou/AbstractFramework) umbrella; pairs with [AbstractCore](https://github.com/lpalbou/abstractcore)
 - Public export surface (source of truth): `src/abstractruntime/__init__.py`
 - Optional AbstractCore baseline: `abstractruntime[abstractcore]` installs `abstractcore>=2.13.24`
@@ -318,6 +318,7 @@ Cached sessions / prompt cache:
 - Prefer stable `params.prompt_cache_key` values or `run.vars["_runtime"]["prompt_cache"]` config to select cache namespaces; Runtime-owned `ABSTRACTRUNTIME_PROMPT_CACHE` is the process-wide opt-in.
 - Gateway prompt-cache env vars should be consumed by Gateway and translated into `_runtime.prompt_cache`; Runtime does not read Gateway env names directly.
 - For durable exact reuse across restarts, use `LLM_CALL.params.prompt_cache_binding` from a prior `load_bloc_kv_artifact(...)` result instead of treating provider-native snapshots as durable workflow state.
+- For host-local operator workflows that still need provider-native export/import, use `get_abstractcore_host_facade(runtime).list_prompt_cache_exports(...)`, `prompt_cache_export(...)`, and `prompt_cache_import(...)`. That surface is local-only, partitions exports by provider/model under a Runtime-owned export root, and is intentionally separate from the durable bloc/binding contract.
 - For local runtimes, Runtime owns one content-addressed bloc root and stores one durable bloc text snapshot per SHA256 there; provider/model caches are separate derived artifacts under that bloc, not duplicate portable memory copies.
 - Keep provider cache handles, session objects, and warm-cache state inside AbstractCore clients or servers.
 - Runtime correctness must not depend on a warm cache; a cold cache may be slower but should produce the same durable graph behavior.

{abstractruntime-0.4.19 → abstractruntime-0.4.20}/llms.txt

@@ -3,7 +3,7 @@
 > Durable workflow runtime (interrupt → checkpoint → resume) with an append-only execution ledger.
 
 - Python: 3.10+ (see `pyproject.toml`)
-- Version: 0.4.19
+- Version: 0.4.20
 - Ecosystem: [AbstractFramework](https://github.com/lpalbou/AbstractFramework) umbrella, integrates with [AbstractCore](https://github.com/lpalbou/abstractcore)
 - Hard invariant: `RunState.vars` must be JSON-serializable (`src/abstractruntime/core/models.py`)
 - Current AbstractCore baseline: `abstractruntime[abstractcore]` installs `abstractcore>=2.13.24`
@@ -34,8 +34,8 @@
 
 ## Integrations
 
-- [AbstractCore integration](docs/integrations/abstractcore.md): `LLM_CALL` / `TOOL_CALLS` / `MODEL_RESIDENCY`, local/remote/hybrid, prompt-cache and residency host controls, durable bloc/KV prompt-cache controls, discovery snapshot queries, durable run-scoped image/voice/music execution, media inputs, generated media outputs, provider-key headers, and tool approval waits
-- Prompt-cache tracks: use `LLM_CALL.params.prompt_cache_key`, `run.vars["_runtime"]["prompt_cache"]`, or `ABSTRACTRUNTIME_PROMPT_CACHE` for best-effort session reuse; use `LLM_CALL.params.prompt_cache_binding` for durable exact bloc-backed reuse. Local Runtime stores one content-addressed bloc per root plus provider/model-specific derived KV artifacts. Gateway prompt-cache env belongs in Gateway.
+- [AbstractCore integration](docs/integrations/abstractcore.md): `LLM_CALL` / `TOOL_CALLS` / `MODEL_RESIDENCY`, local/remote/hybrid, prompt-cache and residency host controls, local-only prompt-cache export/import admin, durable bloc/KV prompt-cache controls, discovery snapshot queries, durable run-scoped image/voice/music execution, media inputs, generated media outputs, provider-key headers, and tool approval waits
+- Prompt-cache tracks: use `LLM_CALL.params.prompt_cache_key`, `run.vars["_runtime"]["prompt_cache"]`, or `ABSTRACTRUNTIME_PROMPT_CACHE` for best-effort session reuse; use `LLM_CALL.params.prompt_cache_binding` for durable exact bloc-backed reuse; and use `get_abstractcore_host_facade(runtime).list_prompt_cache_exports(...)`, `prompt_cache_export(...)`, and `prompt_cache_import(...)` only for host-local operator/admin export-import workflows around live local provider caches. Local Runtime stores one content-addressed bloc per root plus provider/model-specific derived KV artifacts. Gateway prompt-cache env belongs in Gateway.
 - Durable bloc lifecycle: Runtime exposes `list_blocs(...)`, `list_bloc_kv_artifacts(...)`, `delete_bloc_kv_artifact(...)`, `prune_bloc_kv_artifacts(...)`, and `delete_bloc(...)`, with `dry_run`, `clear_loaded`, and `force` safety controls on the host facade.
 - Runtime-owned Core surfaces: `get_abstractcore_discovery_facade(...)`, `get_abstractcore_host_facade(...)`, and `get_abstractcore_run_facade(...)`
 - Host-local operator wrappers: the host facade and `abstractruntime.integrations.abstractcore.comms_facade` expose email helpers (`list_email_accounts`, `list_emails`, `read_email`, `send_email`), and `abstractruntime.integrations.abstractcore.telegram_facade` exposes Telegram bootstrap/global-client/send wrappers without requiring hosts to import AbstractCore directly.

{abstractruntime-0.4.19 → abstractruntime-0.4.20}/pyproject.toml

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

abstractruntime-0.4.20/release-notes.md

@@ -0,0 +1,13 @@
+### Added
+- Runtime now exposes a public host-local prompt-cache export/import admin surface on `get_abstractcore_host_facade(...)`:
+  - `list_prompt_cache_exports(...)`
+  - `prompt_cache_export(...)`
+  - `prompt_cache_import(...)`
+
+### Changed
+- Local Runtime now owns the prompt-cache export root/catalog policy:
+  - `~/.abstractruntime/prompt_cache_exports` by default
+  - `<base_dir>/prompt_cache_exports` for `create_local_file_runtime(...)`
+  - exact provider/model partitioning with Runtime-managed metadata sidecars
+- Remote and hybrid runtimes now fail honestly for prompt-cache export/import admin with a structured local-only response instead of implying server-side support.
+- Runtime docs and AI-readable `llms.txt` / `llms-full.txt` now document the secondary host-local export/import contract distinctly from the primary durable bloc/binding prompt-cache path.

{abstractruntime-0.4.19 → abstractruntime-0.4.20}/src/abstractruntime/integrations/abstractcore/factory.py

@@ -75,6 +75,7 @@ def create_local_runtime(
     model: str,
     llm_kwargs: Optional[Dict[str, Any]] = None,
     bloc_root_dir: Optional[str | Path] = None,
+    prompt_cache_export_root_dir: Optional[str | Path] = None,
     run_store: Optional[RunStore] = None,
     ledger_store: Optional[LedgerStore] = None,
     tool_executor: Optional[ToolExecutor] = None,
@@ -138,6 +139,7 @@ def create_local_runtime(
         llm_kwargs=effective_llm_kwargs,
         artifact_store=artifact_store,
         bloc_root_dir=bloc_root_dir,
+        prompt_cache_export_root_dir=prompt_cache_export_root_dir,
     )
     tools = tool_executor or AbstractCoreToolExecutor(timeout_s=resolved_tool_timeout_s)
     # Orchestrator policy: enforce tool execution timeout at the runtime layer.
@@ -322,6 +324,7 @@ def create_local_file_runtime(
     model: str,
     llm_kwargs: Optional[Dict[str, Any]] = None,
     bloc_root_dir: Optional[str | Path] = None,
+    prompt_cache_export_root_dir: Optional[str | Path] = None,
     context: Optional[Any] = None,
     config: Optional[RuntimeConfig] = None,
     tool_timeout_s: Optional[float] = None,
@@ -333,6 +336,11 @@ def create_local_file_runtime(
         model=model,
         llm_kwargs=llm_kwargs,
         bloc_root_dir=Path(bloc_root_dir) if bloc_root_dir is not None else (Path(base_dir) / "blocs"),
+        prompt_cache_export_root_dir=(
+            Path(prompt_cache_export_root_dir)
+            if prompt_cache_export_root_dir is not None
+            else (Path(base_dir) / "prompt_cache_exports")
+        ),
         run_store=run_store,
         ledger_store=ledger_store,
         context=context,