AbstractRuntime 0.4.18__tar.gz → 0.4.20__tar.gz

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

@@ -7,6 +7,33 @@ 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
+- 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
@@ -478,7 +505,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.18...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
 [0.4.16]: https://github.com/lpalbou/abstractruntime/compare/v0.4.15...v0.4.16

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.18
+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.18 • **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.18)
+## What’s included (v0.4.20)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -193,8 +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, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
-- For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers remain host-local and nondurable.
+- 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
   such as LanceDB, SQLite, or in-memory stores.

{abstractruntime-0.4.18 → 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.18 • **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.18)
+## What’s included (v0.4.20)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -116,8 +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, lifecycle operations, generated image/voice/music outputs, host email helpers, Telegram host wrappers, and tool approval waits): `docs/integrations/abstractcore.md`
-- For outbound comms, use the durable run facade when the send belongs to a run: `get_abstractcore_run_facade(...).send_email(...)` / `send_telegram_message(...)`. If that child run pauses for approval or passthrough execution, resume it through `resume_tool_calls(...)`. Direct host-facade send helpers remain host-local and nondurable.
+- 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
   such as LanceDB, SQLite, or in-memory stores.

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

@@ -184,13 +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 client delegation is implemented by the configured AbstractCore LLM clients in `src/abstractruntime/integrations/abstractcore/llm_client.py` (`get_prompt_cache_capabilities`, `get_prompt_cache_stats`, `prompt_cache_set`, `prompt_cache_update`, `prompt_cache_fork`, `prompt_cache_clear`, `prompt_cache_prepare_modules`, `upsert_text_bloc`, `get_bloc_record`, `list_blocs`, `get_bloc_kv_manifest`, `ensure_bloc_kv_artifact`, `load_bloc_kv_artifact`, `list_bloc_kv_artifacts`, `delete_bloc_kv_artifact`, `prune_bloc_kv_artifacts`, `delete_bloc`, `list_model_residency`, `load_model_residency`, `unload_model_residency`)
-- host-facade email helpers remain host-local wrappers over AbstractCore's public comms helpers (`list_email_accounts`, `list_emails`, `read_email`, `send_email`)
+- 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`)
 
 `LLM_CALL` payloads are JSON-safe effect payloads. Common fields:

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

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
 > Updated: 2026-05-21
-> Version: 0.4.18
+> 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.18 → 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.18 → 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.18 → 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.
@@ -169,6 +192,10 @@ No. For the remaining host/operator paths, use Runtime's public wrappers instead
 - `...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()`

{abstractruntime-0.4.18 → 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
@@ -493,6 +530,11 @@ email and Telegram:
   - `list_emails(...)`
   - `read_email(...)`
   - `send_email(...)`
+- `abstractruntime.integrations.abstractcore.comms_facade` also exposes:
+  - `list_email_accounts(...)`
+  - `list_emails(...)`
+  - `read_email(...)`
+  - `send_email(...)`
 - `abstractruntime.integrations.abstractcore.telegram_facade` exposes:
   - `TelegramTdlibNotAvailable`
   - `bootstrap_telegram_auth_from_env(...)`
@@ -504,6 +546,9 @@ Contract notes:
 
 - These are **host-local** wrappers over current public AbstractCore tool
   modules. They do not proxy through the remote AbstractCore server.
+- The host facade email methods and the standalone `comms_facade` functions use
+  the same Runtime-owned email wrapper layer; choose whichever is more natural
+  for the host surface you are building.
 - They are intentionally **nondurable**. They do not write Runtime run history
   on their own.
 - Direct `send_email(...)` on the host facade and direct

{abstractruntime-0.4.18 → abstractruntime-0.4.20}/docs/tools-comms.md

@@ -48,7 +48,7 @@ Notes:
 - In untrusted deployments, prefer passthrough tools so a host/worker boundary approves and executes tool calls (`PassthroughToolExecutor` in `src/abstractruntime/integrations/abstractcore/tool_executor.py`).
 - For local bridge-owned delivery flows, `ApprovalToolExecutor` can auto-run the Telegram send tools while requiring approval for email, WhatsApp, unknown tools, and write/command-style tools by default.
 - Separate from the durable `TOOL_CALLS` path, Runtime also exposes **host wrappers** for operator-owned email and Telegram surfaces:
-  - email helpers on `get_abstractcore_host_facade(runtime)`
+  - email helpers on `get_abstractcore_host_facade(runtime)` and `abstractruntime.integrations.abstractcore.comms_facade`
   - Telegram lifecycle/send wrappers in `abstractruntime.integrations.abstractcore.telegram_facade`
   - read/bootstrap helpers stay host-local and do not create run history by themselves
   - if an outbound send belongs to a run, prefer the durable run facade:

{abstractruntime-0.4.18 → 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.18
+- 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`
@@ -222,7 +222,7 @@ Notes:
 - Use `ApprovalToolExecutor(delegate=..., policy=ToolApprovalPolicy())` when a local host should auto-run safe tools but pause for user approval before write/command/unknown tools.
 - Remote `params.api_key` and `params.provider_api_key` are compatibility inputs; runtime converts them to `X-AbstractCore-Provider-API-Key` headers for current AbstractCore servers.
 - Gateway/hosts choose Core server URLs, Core server auth headers, provider/model defaults, tool executors, artifact stores, and any Gateway env/config translation before Runtime sees the call.
-- Hosts should bind `get_abstractcore_host_facade(rt)` for prompt-cache, durable bloc/KV, model-residency, and host-local email helper operations instead of reaching through the private `_abstractcore_llm_client` attachment directly.
+- Hosts should bind `get_abstractcore_host_facade(rt)` for prompt-cache, durable bloc/KV, and model-residency control operations, and use the Runtime-owned email wrapper layer (`get_abstractcore_host_facade(rt)` or `abstractruntime.integrations.abstractcore.comms_facade`) for host-local email helper operations instead of importing `abstractcore.tools.comms_tools` directly.
 - Hosts should use `abstractruntime.integrations.abstractcore.telegram_facade` for Telegram TDLib bootstrap/global-client/send helpers instead of importing `abstractcore.tools.telegram_tdlib` or `abstractcore.tools.telegram_tools` directly. These wrappers remain host-local and do not proxy through a remote Core server.
 - If an outbound email or Telegram send belongs to a run, hosts should prefer `get_abstractcore_run_facade(rt).send_email(...)` or `send_telegram_message(...)`. Those are durable `TOOL_CALLS` child runs: Runtime records the request and outcome, and replay should reuse the recorded result instead of resending the message. If the child run waits for approval or passthrough host execution, resume it through the same public boundary with `resume_tool_calls(...)`.
 - Use `pip install "abstractruntime[multimodal]"` for common AbstractCore media, vision, voice, audio, and music dependencies.
@@ -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.18 → 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.18
+- 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,11 +34,11 @@
 
 ## 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 now also wraps 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.
+- 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.
 - Durable outbound comms: when an email or Telegram send belongs to a run, use `get_abstractcore_run_facade(...).send_email(...)` or `send_telegram_message(...)` so Runtime records the request and outcome in a child run; replay should show the recorded result, not resend the message. If the child run waits for approval or passthrough execution, resume it through `resume_tool_calls(...)`.
 - [Artifacts](docs/api.md#artifacts-store-by-reference): JSON-safe refs for large payloads; generated images/audio/voice/music are stored here rather than embedded in `RunState.vars`
 - Remote multimodal guardrail: remote/hybrid media generation uses AbstractCore Server endpoints, does not inherit the chat model for media endpoints, rejects unsupported input media and non-file STT inputs instead of ignoring them, and redacts data URLs from persisted provider-request metadata