AbstractRuntime 0.4.6__tar.gz → 0.4.7__tar.gz

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.7] - 2026-05-08
+
+### Changed
+- Minimum `abstractcore` optional dependency increased to `>=2.13.11` for the `abstractcore`, `multimodal`, and `mcp-worker` extras so Runtime aligns with the current Core server-auth, provider-key, generated-media, and capability-catalog contracts.
+- AbstractCore integration imports now fail fast when a stale local AbstractCore install is older than the 2.13.11 Gateway/Core deployment baseline.
+- Documentation now makes the Gateway handoff explicit: hosts choose Runtime plus the Core/capability/memory profile, pass Core server URLs/auth headers deliberately, and keep provider clients, auth objects, model handles, and sessions out of durable runtime state.
+- Runtime no longer reads Gateway-owned environment variables directly. Prompt-cache defaults use explicit Runtime state or `ABSTRACTRUNTIME_PROMPT_CACHE`, read-file attachment registration limits use explicit Runtime state/payload values or `ABSTRACTRUNTIME_MAX_ATTACHMENT_BYTES`, and workflow bundle registries use shared/framework or explicit directories.
+
+### Testing
+- Added packaging boundary coverage proving Runtime exposes no fake hardware profile extras (`apple`, `gpu`, `all-apple`, `all-gpu`) and keeps the Core floors aligned.
+- Added import-boundary coverage proving the runtime kernel and package root do not import optional Core/Vision/Voice/Memory/Music stacks.
+- Added a remote client regression test proving Gateway auth/provider-key environment variables are not inherited as AbstractCore server auth or provider-key headers.
+- Added regression tests proving Gateway env vars alone do not enable prompt-cache keys, shrink attachment registration limits, or select workflow bundle registry directories.
+
 ## [0.4.6] - 2026-05-07
 
 ### Changed
@@ -340,7 +354,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.6...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.7...HEAD
+[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
 [0.4.4]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.4.4

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.6
+Version: 0.4.7
 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
@@ -22,15 +22,15 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: abstractsemantics>=0.0.2
 Provides-Extra: abstractcore
-Requires-Dist: abstractcore>=2.13.10; extra == 'abstractcore'
+Requires-Dist: abstractcore>=2.13.11; extra == 'abstractcore'
 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: mcp-worker
-Requires-Dist: abstractcore[tools]>=2.13.10; extra == 'mcp-worker'
+Requires-Dist: abstractcore[tools]>=2.13.11; extra == 'mcp-worker'
 Provides-Extra: multimodal
-Requires-Dist: abstractcore[audio,media,openai,vision,voice]>=2.13.10; extra == 'multimodal'
+Requires-Dist: abstractcore[audio,media,openai,vision,voice]>=2.13.11; extra == 'multimodal'
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == 'test'
 Description-Content-Type: text/markdown
@@ -41,7 +41,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.6 • **Python:** 3.10+
+**Version:** 0.4.7 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -75,7 +75,7 @@ AbstractCore integration (LLM + tools):
 pip install "abstractruntime[abstractcore]"
 ```
 
-The `abstractcore` extra installs AbstractCore 2.13.10 or newer so the hardened server auth model, provider-key header routing, prompt-cache control plane, current tool catalog, unified multimodal generation response types, 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.11 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.
 
 MCP worker entrypoint (default toolsets over stdio):
 
@@ -124,7 +124,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.6)
+## What’s included (v0.4.7)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/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.6 • **Python:** 3.10+
+**Version:** 0.4.7 • **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.10 or newer so the hardened server auth model, provider-key header routing, prompt-cache control plane, current tool catalog, unified multimodal generation response types, 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.11 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.
 
 MCP worker entrypoint (default toolsets over stdio):
 
@@ -87,7 +87,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.6)
+## What’s included (v0.4.7)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/adr/0002_execution_modes_local_remote_hybrid.md

@@ -1,7 +1,7 @@
 ## ADR 0002: Execution modes (local, remote, hybrid)
 
 ### Status
-Accepted (2025-12-11)
+Accepted (2025-12-11); clarified 2026-05-08 by framework ADR-0033
 
 ### Context
 Agents/workflows must run in multiple deployment topologies:
@@ -20,6 +20,12 @@ AbstractRuntime supports three execution modes:
 - **Remote**: HTTP to AbstractCore server; tools default to passthrough (untrusted)
 - **Hybrid**: remote LLM + local tool execution
 
+Remote AbstractCore server mode uses the Core server's own URL, auth token, base URL allowlists,
+and provider-key override rules. It must not inherit Gateway bearer tokens or browser origin policy
+implicitly. If Gateway is the caller, Gateway acts as an explicit Core-server client.
+Gateway-specific env/config is consumed by Gateway and passed to Runtime through explicit run state,
+effect payloads, client construction arguments, or Runtime-owned environment variables.
+
 ### Consequences
 - Thin-mode clients can run the workflow logic while delegating inference to a server.
 - Remote mode supports AbstractCore per-request `base_url` routing (dynamic endpoint selection).
@@ -28,5 +34,6 @@ AbstractRuntime supports three execution modes:
 ### 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)
 - Code: `src/abstractruntime/integrations/abstractcore/factory.py`
-
+- Framework ADR: `../../../docs/adr/0033-install-profiles-config-entrypoints-and-server-boundaries.md`

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/api.md

@@ -176,7 +176,7 @@ This produces a portable record of a run’s state + ledger + artifacts suitable
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.10 or newer).
+Requires: `pip install "abstractruntime[abstractcore]"` (AbstractCore 2.13.11 or newer).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -198,12 +198,16 @@ 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
+- 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:
 - LLM clients expose cache control methods listed above for host-side preparation and inspection
-- `LLM_CALL.params.prompt_cache_key` selects a cache key for a call; runtime can also derive a session-scoped key from `run.vars["_runtime"]["prompt_cache"]`
+- `LLM_CALL.params.prompt_cache_key` selects a cache key for a call; runtime can also derive a session-scoped key from `run.vars["_runtime"]["prompt_cache"]` or the Runtime-owned `ABSTRACTRUNTIME_PROMPT_CACHE` process default
 - provider cache/session handles are not durable runtime state and should not be stored in `RunState.vars`
 
+Attachment registration limits:
+- `TOOL_CALLS.payload.max_attachment_bytes`, `run.vars["_runtime"]["max_attachment_bytes"]`, or `ABSTRACTRUNTIME_MAX_ATTACHMENT_BYTES` bound the bytes Runtime stores when local `read_file` outputs are captured as session attachments
+
 Docs: `integrations/abstractcore.md`.
 
 ### AbstractMemory bridge (KG effects)

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-05-07
-> Version: 0.4.6
+> Updated: 2026-05-08
+> Version: 0.4.7
 > 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.
@@ -37,6 +37,8 @@ The boundary is intentionally narrow:
 - 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.
 - 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 does not expose hardware profile extras such as `apple`, `gpu`, `all-apple`, or `all-gpu`; those 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.
 
 This keeps the runtime usable by `../abstractgateway` and application layers such as `../abstractflow`, `../abstractassistant`, `../abstractobserver`, and `../abstractcode` without embedding provider-specific model logic in the durable kernel.
 

abstractruntime-0.4.7/docs/backlog/proposed/2026-05-08_runtime_gateway_env_namespace_cleanup.md

@@ -0,0 +1,163 @@
+# Completed: Runtime Gateway Env Namespace Cleanup
+
+## Metadata
+- Created: 2026-05-08
+- Status: Completed
+- Completed: 2026-05-08
+
+## Context
+
+AbstractRuntime should remain a lower-level durable runner. Gateway may compose Runtime and pass
+run-scoped defaults, policy, and deployment choices into Runtime, but Runtime should not learn
+Gateway-specific environment variable names.
+
+This matters for the two-entry-point design:
+
+- developers may use Runtime/Core without Gateway;
+- Gateway may deploy Runtime as one component in a larger server;
+- config precedence should be explicit and testable;
+- lower packages should not depend on higher-package env namespaces.
+
+## Current Code Reality
+
+Runtime 0.4.7 largely carried out the install-boundary work:
+
+- `pyproject.toml` now points Runtime AbstractCore extras at `abstractcore>=2.13.11`.
+- Runtime does not expose `apple`, `gpu`, `all-apple`, or `all-gpu` extras.
+- `tests/test_packaging_extras.py` verifies the Core floor and absence of fake hardware extras.
+- `tests/test_runtime_install_boundary.py` verifies the package root/kernel import boundary.
+- `tests/test_remote_llm_client.py` verifies remote AbstractCore clients do not inherit Gateway auth
+  or provider-key env vars.
+
+Before this cleanup, Runtime still had Gateway namespace reads in implementation code:
+
+- prompt cache auto-enable reads both `ABSTRACTRUNTIME_PROMPT_CACHE` and
+  `ABSTRACTGATEWAY_PROMPT_CACHE`;
+- pending-media attachment limits read `ABSTRACTGATEWAY_MAX_ATTACHMENT_BYTES`.
+- workflow bundle default registry resolution reads `ABSTRACTGATEWAY_FLOWS_DIR`.
+
+Runtime also reads Runtime-owned or generic env vars such as
+`ABSTRACTRUNTIME_GLOBAL_MEMORY_RUN_ID`, `ABSTRACTRUNTIME_MAX_INLINE_BYTES`, and
+`ABSTRACT_WORKSPACE_BASE_DIR`. Those are not the problem; the problem is Runtime directly reading
+Gateway-owned names.
+
+## Problem
+
+The current behavior partially violates the desired config cascade:
+
+1. Gateway config/env should be consumed by Gateway.
+2. Gateway should pass Runtime-relevant values explicitly through run state, effect payloads,
+   constructor/config arguments, or a Runtime-owned env name.
+3. Runtime should not read `ABSTRACTGATEWAY_*` directly.
+
+Leaving these reads in Runtime creates subtle deployment coupling:
+
+- a standalone Runtime/Core process can change behavior because a Gateway env var happens to be set;
+- Gateway cannot cleanly document its config precedence because Runtime also consumes some of it;
+- tests currently cover auth/key leakage but not non-auth Gateway env leakage;
+- future Gateway settings may be copied into Runtime ad hoc instead of using explicit handoff.
+
+## What We Want To Do
+
+Remove Gateway-specific env reads from Runtime and make the handoff explicit.
+
+Prompt cache:
+
+- keep `_runtime.prompt_cache` as the preferred run-scoped control plane;
+- allow a Runtime-owned process default such as `ABSTRACTRUNTIME_PROMPT_CACHE`;
+- Gateway should read `ABSTRACTGATEWAY_PROMPT_CACHE` itself and write `_runtime.prompt_cache` when
+  it wants prompt cache enabled for a run/session.
+
+Attachment/media limits:
+
+- add an explicit Runtime-side control such as `_runtime.max_attachment_bytes`, effect payload
+  `max_attachment_bytes`, or a small typed attachment policy object;
+- allow a Runtime-owned process default such as `ABSTRACTRUNTIME_MAX_ATTACHMENT_BYTES` if a process
+  env fallback is still needed;
+- Gateway should read `ABSTRACTGATEWAY_MAX_ATTACHMENT_BYTES` itself and pass the effective limit to
+  Runtime explicitly.
+
+## Requirements
+
+- Runtime must not read `ABSTRACTGATEWAY_*` env vars.
+- Runtime may keep `ABSTRACTRUNTIME_*` env vars for Runtime-owned process defaults.
+- Gateway-provided values must travel through explicit run state, effect payloads, Runtime config, or
+  constructor arguments.
+- Existing `_runtime.prompt_cache` behavior should remain supported.
+- Add regression tests proving Gateway env vars alone do not change Runtime behavior.
+- Add tests proving explicit Runtime controls still work.
+- Any compatibility fallback for old Gateway env names must be temporary, documented with
+  `#FALLBACK`, and preferably implemented in Gateway instead of Runtime.
+
+## Suggested Implementation
+
+1. Update `_maybe_inject_prompt_cache_key(...)` to remove the
+   `ABSTRACTGATEWAY_PROMPT_CACHE` branch.
+2. Update the pending-media attachment byte limit resolver to prefer explicit Runtime state/payload
+   and then `ABSTRACTRUNTIME_MAX_ATTACHMENT_BYTES`; remove `ABSTRACTGATEWAY_MAX_ATTACHMENT_BYTES`.
+3. Add focused tests in `tests/test_remote_llm_client.py` or a new effect-handler test module:
+   - setting `ABSTRACTGATEWAY_PROMPT_CACHE=1` alone does not inject a prompt cache key;
+   - setting `_runtime.prompt_cache=True` does inject a prompt cache key when session/provider/model
+     are present;
+   - setting `ABSTRACTGATEWAY_MAX_ATTACHMENT_BYTES` alone does not alter Runtime attachment limits;
+   - the chosen explicit Runtime limit path does alter Runtime attachment limits.
+4. Update Runtime docs that mention prompt cache or attachment limits.
+5. Update the Gateway backlog/implementation to translate Gateway config/env into Runtime handoff
+   values instead of relying on Runtime to read Gateway env names.
+
+## Implementation Notes
+
+Runtime 0.4.7 applies this cleanup directly:
+
+- `_maybe_inject_prompt_cache_key(...)` no longer reads `ABSTRACTGATEWAY_PROMPT_CACHE`.
+- Prompt cache auto-keying still supports explicit `LLM_CALL.params.prompt_cache_key`,
+  `_runtime.prompt_cache`, and Runtime-owned `ABSTRACTRUNTIME_PROMPT_CACHE`.
+- Read-file session attachment registration now resolves byte limits from
+  `TOOL_CALLS.payload.max_attachment_bytes`, `_runtime.max_attachment_bytes`,
+  `ABSTRACTRUNTIME_MAX_ATTACHMENT_BYTES`, then the default 25 MiB.
+- `default_workflow_bundles_dir()` no longer reads `ABSTRACTGATEWAY_FLOWS_DIR`; Gateway should pass
+  `bundles_dir` explicitly or translate to `ABSTRACTFRAMEWORK_WORKFLOWS_DIR`.
+- Regression tests cover prompt-cache env isolation, attachment-limit env isolation, explicit
+  Runtime namespace and effect payload attachment limits, and workflow bundle registry env
+  isolation.
+
+## Scope
+
+Included:
+
+- Runtime AbstractCore effect-handler config lookup cleanup.
+- Runtime tests for env namespace isolation.
+- Runtime docs/backlog notes required to preserve the boundary.
+
+Excluded:
+
+- Gateway config implementation.
+- Gateway package extras.
+- Gateway server route behavior.
+- Provider/model/auth decisions, which are already separately covered by existing tests.
+
+## Promotion Criteria
+
+Promote this before declaring Runtime fully clean for a production Gateway release if either of
+these is true:
+
+- Gateway still relies on `ABSTRACTGATEWAY_PROMPT_CACHE` or `ABSTRACTGATEWAY_MAX_ATTACHMENT_BYTES`
+  being read by Runtime;
+- Runtime is being released as the official Gateway-aligned baseline.
+
+If Gateway is updated first to pass explicit Runtime state and no production deployment relies on the
+old env reads, this can be implemented as a small cleanup immediately after Gateway config lands.
+
+## Validation
+
+- [x] `python -m pytest tests/test_runtime_install_boundary.py tests/test_packaging_extras.py`
+- [x] focused prompt-cache/env isolation tests;
+- [x] focused attachment-limit/env isolation tests;
+- [x] `rg -n "ABSTRACTGATEWAY" src tests docs` should show no Runtime implementation reads, except
+  tests that assert the env name is ignored and docs/backlog references explaining the cleanup.
+
+## Guidance For The Implementing Agent
+
+Re-check current Gateway behavior before deleting compatibility assumptions. The clean target is not
+"no env vars"; it is "Runtime owns Runtime env vars, Gateway owns Gateway env vars, and Gateway
+passes Runtime-relevant values explicitly."

abstractruntime-0.4.7/docs/backlog/proposed/2026-05-08_runtime_gateway_install_boundary.md

@@ -0,0 +1,117 @@
+# Proposed: Runtime Gateway Install Boundary
+
+## Metadata
+- Created: 2026-05-08
+- Status: Completed
+- Completed: 2026-05-08
+
+## Context
+
+AbstractRuntime is the durable graph runner. It persists runs, effects, waits, ledgers, artifacts,
+snapshots, and resume behavior. It should remain stable and dependency-light even when Gateway
+deployments pull in Core, agents, media, memory, tools, and provider SDKs.
+
+## Current Code Reality
+
+- Runtime base depends on `abstractsemantics>=0.0.2`.
+- AbstractCore integration is explicit through `abstractruntime[abstractcore]`.
+- Multimodal helper dependencies are explicit through `abstractruntime[multimodal]`.
+- Runtime does not directly depend on AbstractMemory; memory effects are integration/host-wired.
+- Runtime config contains run-level defaults and limits, not deployment auth or provider secrets.
+- As of the AbstractCore `2.13.11` release, Core exposes the canonical install-profile aliases
+  `abstractcore[apple]`, `abstractcore[gpu]`, `abstractcore[all-apple]`, and
+  `abstractcore[all-gpu]`, plus the released Voice/Vision catalog-capable floors
+  `abstractvoice>=0.9.1` and `abstractvision>=0.3.2`.
+- Runtime's package metadata now points its AbstractCore extras at `abstractcore>=2.13.11`
+  for Gateway deployment alignment.
+
+## Problem
+
+The desire for cascading Gateway installs can accidentally push Core/Vision/Voice/Memory/local
+engine dependencies down into Runtime. That would weaken the clean boundary:
+
+- Runtime should be able to execute non-LLM workflows without Core.
+- Runtime should not own provider configuration.
+- Runtime should not import Vision, Voice, Music, or Memory in its kernel.
+- Runtime should persist artifact refs and JSON-safe results, not model/provider clients.
+
+## Proposed Direction
+
+Keep Runtime base minimal.
+
+Profile guidance:
+
+- `abstractruntime`: durable kernel plus Semantics schema refs.
+- `abstractruntime[abstractcore]`: LLM/tool integration, with a floor of
+  `abstractcore>=2.13.11` so Gateway receives the current Core server-auth, provider-key,
+  generated-media, and capability-catalog contracts.
+- `abstractruntime[multimodal]`: Core media/capability helpers for generated images, voice/audio,
+  and media inputs, also with `abstractcore>=2.13.11`.
+- Do not add `apple`, `gpu`, `all-apple`, or `all-gpu` to Runtime unless Runtime itself owns a
+  hardware-specific dependency, which it currently does not.
+
+Gateway should compose Runtime with the selected Core/capability/memory profile. The cascade belongs
+to Gateway, not Runtime.
+
+## Gateway Configuration Handoff Rules
+
+Runtime should stay explicit about configuration handoff:
+
+- Gateway may pass run defaults in JSON-safe run state, such as `run.vars["_runtime"]["provider"]`
+  and `run.vars["_runtime"]["model"]`.
+- Gateway may pass effect-level overrides in LLM/media effect payloads when workflow pins or request
+  values require them.
+- Gateway may construct local/remote/hybrid AbstractCore clients with explicit Core server URL,
+  Core server auth headers, provider/model defaults, tool executor, retry policy, and artifact
+  store.
+- Runtime should not read `ABSTRACTGATEWAY_*` env vars directly; Gateway-owned config must be
+  translated into explicit Runtime inputs or Runtime-owned env names.
+- Runtime should not reinterpret Gateway auth tokens as Core server auth tokens or provider keys.
+- Runtime should keep persisted run state JSON-safe: provider names, model ids, policy flags, and
+  artifact refs are fine; provider clients, auth objects, downloaded model handles, and server
+  sessions are not.
+
+## Implementation Notes
+
+Runtime was touched only for release-alignment and boundary validation.
+
+What changed in Runtime 0.4.7:
+
+- `abstractruntime[abstractcore]`, `abstractruntime[multimodal]`, and
+  `abstractruntime[mcp-worker]` now require `abstractcore>=2.13.11`.
+- Runtime still exposes no `apple`, `gpu`, `all-apple`, or `all-gpu` extras.
+- The AbstractCore integration version guard now fails fast on stale Core installs older than
+  2.13.11.
+- Runtime no longer reads Gateway-owned environment variables for prompt-cache defaults,
+  attachment registration limits, or workflow bundle registry paths.
+- Tests now cover the optional-stack import boundary, package metadata floor, missing hardware
+  profile extras, Gateway env namespace isolation, and the rule that Gateway auth/provider-key
+  environment variables are not inherited by remote AbstractCore clients.
+
+Related package guidance remains:
+
+- Gateway should keep Runtime base as the dependency for minimal installs.
+- Gateway server profiles may choose `AbstractRuntime[multimodal]`.
+- Gateway Apple/GPU profiles should cascade through Core profile names such as
+  `abstractcore[all-apple]` or `abstractcore[all-gpu]`; Runtime should remain unchanged.
+- Root `abstractframework` should update Runtime version floors to match the current Gateway/Core
+  integration baseline.
+- AbstractAgent should tighten its Runtime dependency floor.
+
+## Promotion Criteria
+
+Promoted because the Runtime release needed package metadata alignment, clearer install-boundary
+docs, and regression tests for the Gateway handoff.
+
+## Validation
+
+- [x] Subprocess import test for `abstractruntime` with Core/Vision/Voice/Memory/Music blocked.
+- [x] Fresh venv import test for `abstractruntime` without AbstractCore installed.
+- [x] Fresh venv import test for `abstractruntime[abstractcore]`.
+- [x] Runtime LLM/media integration tests gated behind extras.
+- [x] Static import checks that Runtime kernel modules do not import Core, Vision, Voice, Memory, or
+  Music.
+- [x] Package metadata test proving Runtime exposes no fake `apple`, `gpu`, `all-apple`, or `all-gpu`
+  extras.
+- [x] Package metadata test proving `abstractruntime[abstractcore]` and `abstractruntime[multimodal]`
+  depend on `abstractcore>=2.13.11`.

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/faq.md

@@ -107,7 +107,9 @@ No. AbstractRuntime provides the durable graph runner, checkpoint/ledger model,
 
 ## Where should cached session or prompt-cache state live?
 
-Store stable cache keys or cache configuration in runtime-visible JSON, for example `payload.params.prompt_cache_key` or `run.vars["_runtime"]["prompt_cache"]`. Do not store provider session objects, cache handles, clients, or warm-cache state in `RunState.vars`. AbstractCore clients/servers own those objects, and runtime correctness should still hold when a cache is cold.
+Store stable cache keys or cache configuration in runtime-visible JSON, for example `payload.params.prompt_cache_key` or `run.vars["_runtime"]["prompt_cache"]`. A Runtime process can also opt in with `ABSTRACTRUNTIME_PROMPT_CACHE`. Do not store provider session objects, cache handles, clients, or warm-cache state in `RunState.vars`. AbstractCore clients/servers own those objects, and runtime correctness should still hold when a cache is cold.
+
+Gateway-specific prompt-cache environment variables should be consumed by Gateway and passed to Runtime explicitly; Runtime does not read the Gateway env namespace directly.
 
 Hosts can inspect or prepare caches through the configured `_abstractcore_llm_client` control-plane methods (`get_prompt_cache_capabilities`, `prompt_cache_prepare_modules`, and related methods).
 Docs: `integrations/abstractcore.md`. Code: `src/abstractruntime/integrations/abstractcore/llm_client.py`.

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/getting-started.md

@@ -18,7 +18,7 @@ Optional (LLM + tools via AbstractCore):
 pip install "abstractruntime[abstractcore]"
 ```
 
-This installs AbstractCore 2.13.10 or newer, which matches the documented server auth, provider-key header routing, prompt-cache control plane, current tool behavior, unified multimodal generation response types, public output-selector contract, and async/sync text-generation output-selector parity. Use `abstractruntime[multimodal]` when your workflows need common media, vision, voice, or audio dependencies.
+This installs AbstractCore 2.13.11 or newer, which matches the documented server auth, provider-key header routing, generated-media contracts, capability catalog, prompt-cache control plane, current tool behavior, public output-selector contract, and async/sync text-generation output-selector parity. Use `abstractruntime[multimodal]` when your workflows need common media, vision, voice, or audio dependencies.
 
 ## Mental model (source of truth)
 

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/integrations/abstractcore.md

@@ -16,7 +16,7 @@ Implementation pointers (this repo):
 pip install "abstractruntime[abstractcore]"
 ```
 
-This extra installs AbstractCore 2.13.10 or newer. That is the supported baseline for the current server auth split (`Authorization` for server auth, `X-AbstractCore-Provider-API-Key` for provider overrides), prompt-cache control-plane endpoints, current tool catalog, the unified multimodal `generate(..., output=...)` response types, AbstractCore's public output-selector contract, and async/sync text-generation output-selector parity.
+This extra installs AbstractCore 2.13.11 or newer. That is the supported baseline for the current server auth split (`Authorization` for server auth, `X-AbstractCore-Provider-API-Key` for provider overrides), generated-media contracts, capability catalog, prompt-cache control-plane endpoints, current tool catalog, AbstractCore's public output-selector contract, and async/sync text-generation output-selector parity.
 
 For AbstractCore's multimodal `generate(..., output=...)` path, use the newer baseline and optional media packages:
 
@@ -24,7 +24,7 @@ For AbstractCore's multimodal `generate(..., output=...)` path, use the newer ba
 pip install "abstractruntime[multimodal]"
 ```
 
-This installs `abstractcore[media,openai,vision,voice,audio]>=2.13.10`. Local image/voice generation still depends on the configured AbstractCore capability backends (for example AbstractVision and AbstractVoice, or OpenAI/OpenAI-compatible remote engines).
+This installs `abstractcore[media,openai,vision,voice,audio]>=2.13.11`. Local image/voice generation still depends on the configured AbstractCore capability backends (for example AbstractVision and AbstractVoice, or OpenAI/OpenAI-compatible remote engines).
 
 The MCP worker entrypoint uses the `mcp-worker` extra:
 
@@ -44,6 +44,8 @@ Factory functions (exported from `abstractruntime.integrations.abstractcore`):
 - `create_remote_runtime(...)`
 - `create_hybrid_runtime(...)`
 
+Runtime stays explicit at the boundary: Gateway/hosts construct these clients with the Core server URL, Core server auth headers, provider/model defaults, retry policy, tool executor, and artifact store they intend to use. Runtime does not read `ABSTRACTGATEWAY_*` environment variables directly and does not reinterpret Gateway bearer tokens as Core server tokens or provider keys. Gateway-owned config should be consumed by Gateway, then passed to Runtime through explicit run state, effect payloads, constructor arguments, or Runtime-owned environment variables.
+
 ## Minimal LLM workflow
 
 ```python
@@ -111,6 +113,7 @@ Notes:
 - `media` accepts one item or a list. Durable artifact refs such as `{"$artifact": "...", "filename": "speech.wav"}` are materialized to temporary files for AbstractCore and never stored as raw bytes in `RunState`.
 - `output` may be top-level or inside `params`; top-level `outputs` is accepted as a runtime alias for AbstractCore's `output`.
 - `output.tags`, when present, are merged into the generated artifact metadata. Runtime metadata such as `run_id` and `tags` is used by AbstractRuntime's ArtifactStore boundary and is not forwarded as provider-specific generation kwargs.
+- Host-supplied run defaults such as `run.vars["_runtime"]["provider"]` and `run.vars["_runtime"]["model"]` are persisted as JSON-safe routing metadata; provider clients, auth objects, downloaded model handles, and server sessions are not durable runtime state.
 
 ## Multimodal generation
 
@@ -282,6 +285,7 @@ Contract notes:
 - When a provider reports `mode=local_control_plane` (for example MLX, or GGUF models whose llama.cpp chat format has an exact cached renderer), the runtime can maintain a compartmentalized `system | tools | history` cache path automatically.
 - When a provider reports `mode=keyed`, the runtime still forwards stable `prompt_cache_key`s but skips module preparation/fork/update orchestration.
 - This surface is intentionally host-oriented; the runtime effect handlers still only use prompt caching during LLM execution, but gateway/CLI hosts can now manage prompt caches without reaching through to provider internals.
+- Automatic per-session prompt-cache keys are enabled by `run.vars["_runtime"]["prompt_cache"]`, `LLM_CALL.params.prompt_cache_key`, or the Runtime-owned `ABSTRACTRUNTIME_PROMPT_CACHE` process default. Gateway-specific prompt-cache env vars should be translated by Gateway into `_runtime.prompt_cache`.
 
 Host-side prompt-cache example:
 
@@ -300,6 +304,17 @@ if caps.get("capabilities", {}).get("supports_prepare_modules"):
     )
 ```
 
+## Attachment registration limits
+
+When local `read_file` tool outputs are captured as session attachments, Runtime bounds the file bytes it stores. The limit is resolved in this order:
+
+- `TOOL_CALLS.payload.max_attachment_bytes`
+- `run.vars["_runtime"]["max_attachment_bytes"]`
+- `ABSTRACTRUNTIME_MAX_ATTACHMENT_BYTES`
+- the default of 25 MiB
+
+Gateway-specific attachment env vars should be translated by Gateway into one of the explicit Runtime inputs above.
+
 ## Default toolsets (incl. comms)
 
 `default_tools.get_default_toolsets()` provides a host-side convenience catalog of common tools:

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/limits.md

@@ -62,7 +62,7 @@ Returns a structured dict for UI/status display. (`src/abstractruntime/core/runt
 
 Returns a list of `LimitWarning` objects for limits approaching/exceeded. (`src/abstractruntime/core/models.py`, `src/abstractruntime/core/runtime.py`)
 
-As of v0.4.6, warnings are computed for:
+As of v0.4.7, warnings are computed for:
 - `iterations` (`current_iteration` vs `max_iterations`)
 - `tokens` (`estimated_tokens_used` vs `max_tokens`)
 

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/proposal.md

@@ -79,7 +79,7 @@ AbstractRuntime stays dependency-light at the kernel level; concrete integration
 
 ## Status (implemented in this repository)
 
-As of v0.4.6:
+As of v0.4.7:
 - durable kernel: `RunState`, `WaitState`, `Runtime.start/tick/resume`
 - built-in waits + events: `WAIT_EVENT`, `WAIT_UNTIL`, `ASK_USER`, `EMIT_EVENT`
 - persistence backends: in-memory, JSON/JSONL, SQLite

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/provenance.md

@@ -8,7 +8,7 @@ Implementation pointers:
 - model fields: `src/abstractruntime/core/models.py` (`StepRecord.prev_hash`, `StepRecord.record_hash`, `StepRecord.signature`)
 - hash-chain decorator + verifier: `src/abstractruntime/storage/ledger_chain.py`
 
-## What is implemented (v0.4.6)
+## What is implemented (v0.4.7)
 
 - `HashChainedLedgerStore(inner_store)` — wraps any `LedgerStore` to compute hashes on append
 - `verify_ledger_chain(records)` — validates the chain and returns a verification report

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/docs/workflow-bundles.md

@@ -58,6 +58,8 @@ print([ep.flow_id for ep in b.manifest.entrypoints])
 - default directory resolution: `default_workflow_bundles_dir()` (`src/abstractruntime/workflow_bundle/registry.py`)
 - resolve `bundle_id[@version]` and entrypoints (`resolve_bundle`, `resolve_entrypoint`)
 
+Default directory resolution checks `ABSTRACTFRAMEWORK_WORKFLOWS_DIR`, then AbstractFlow authoring env names, then `./flows/bundles/`, then `~/.abstractframework/workflows/`. Hosts with Gateway-specific flow settings should pass `bundles_dir` explicitly or translate them to the shared framework env name before constructing the registry.
+
 ## VisualFlow multi-entry fan-in
 
 Visual authoring tools may connect more than one execution edge into the same target `exec-in` pin. For example, a first prompt can enter a node from `on_flow_start`, while a later loop can re-enter the same node with a different prompt produced by the previous turn.

{abstractruntime-0.4.6 → abstractruntime-0.4.7}/llms-full.txt

@@ -10,11 +10,12 @@ This file is an **agent-oriented build guide** for the AbstractRuntime *library*
 
 Quick facts:
 - Python: 3.10+ (`pyproject.toml`)
-- Version: 0.4.6
+- Version: 0.4.7
 - 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.10`
-- Multimodal extra: `abstractruntime[multimodal]` installs `abstractcore[media,openai,vision,voice,audio]>=2.13.10`
+- Optional AbstractCore baseline: `abstractruntime[abstractcore]` installs `abstractcore>=2.13.11`
+- Multimodal extra: `abstractruntime[multimodal]` installs `abstractcore[media,openai,vision,voice,audio]>=2.13.11`
+- Config boundary: Runtime does not read `ABSTRACTGATEWAY_*`; Gateway-owned env/config should be translated into explicit Runtime inputs or Runtime-owned env names.
 
 ```mermaid
 flowchart LR
@@ -219,9 +220,11 @@ Notes:
 - Tool calls and results are durable (ledger + checkpoints). Keep secrets out of tool arguments.
 - 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 can access the configured LLM client via the factory-set `_abstractcore_llm_client` attribute for prompt-cache operations such as `get_prompt_cache_capabilities()` and `prompt_cache_prepare_modules(...)`.
 - Use `pip install "abstractruntime[multimodal]"` for common AbstractCore media, vision, voice, and audio dependencies.
 - Optional comms tools (email/WhatsApp/Telegram) are gated by env vars; see `docs/tools-comms.md` and code `src/abstractruntime/integrations/abstractcore/default_tools.py`.
+- Read-file session attachment registration is bounded by `TOOL_CALLS.payload.max_attachment_bytes`, `run.vars["_runtime"]["max_attachment_bytes"]`, `ABSTRACTRUNTIME_MAX_ATTACHMENT_BYTES`, then the 25 MiB default.
 
 Minimal approval executor wiring:
 
@@ -307,7 +310,8 @@ Remote multimodal guardrails:
 - provider-request metadata redacts data URLs before persistence so ledger/checkpoints do not embed media bytes
 
 Cached sessions / prompt cache:
-- Prefer stable `params.prompt_cache_key` values or `run.vars["_runtime"]["prompt_cache"]` config to select cache namespaces.
+- 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.
 - 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.
 - Use `_abstractcore_llm_client` only as a host-side control-plane escape hatch for cache inspection/preparation, not as data stored in `RunState.vars`.