AbstractRuntime 0.4.26__tar.gz → 0.4.28__tar.gz

{abstractruntime-0.4.26 → abstractruntime-0.4.28}/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.28] - 2026-06-06
+
+### Added
+- VisualFlow `read_pdf` and `write_pdf` document nodes. `read_pdf` extracts PDF text/metadata with `pypdf`; `write_pdf` renders text or Markdown-style content to real PDF bytes with `reportlab` while keeping run state JSON-safe.
+- Runtime discovery now exposes installed compatible vision adapters through `list_vision_adapters(...)`.
+- Runtime's local/remote image and video media helpers now preserve task-specific batch generation controls (`count` / `n`, `seeds`) and ordered `lora_adapters`, and VisualFlow media nodes now lower those fields for image generation, image edit, text-to-video, and image-to-video.
+
+### Changed
+- Runtime's base dependency path no longer selects AbstractCore's media extra or direct PyMuPDF/PyMuPDF4LLM/PyMuPDF-layout packages for VisualFlow PDF support.
+- Raised the AbstractCore dependency floor to `abstractcore>=2.13.37`, matching the released Core/Vision adapter, batch-generation, and media-parameter contract used by Runtime's base and hardware profiles.
+- Forwarded newer Core/Vision controls such as `guidance_2`, `flow_shift`, and image-upscaler parameters through generated-media execution.
+- The per-turn `<runtime_metadata>` prompt envelope is now temporal-only by default (`local_datetime` plus a country-free `display`). Full grounding remains in result metadata (`runtime_grounding`); operators can opt fields back into the prompt with `ABSTRACTRUNTIME_GROUNDING_PROMPT_FIELDS` (comma-separated subset of `local_datetime,timezone,country,user,display`).
+- When the runtime injects a `<runtime_metadata>` envelope into the user turn, it now also appends a stable "RUNTIME GROUNDING" contract to the system prompt explaining that the envelope is machine context, not a user language/locale preference.
+
+### Fixed
+- Markdown-to-PDF rendering now handles ATX heading levels 1 through 6, preventing deeper headings such as `####` from appearing as literal paragraph text in generated PDFs.
+- VisualFlow LLM Call and Agent structured outputs now expose the parsed object on the `data` output while preserving the existing textual `response` output.
+- VisualFlow LLM Call nodes now preserve inline `resp_schema` / `response_schema` constraints when provider and model are left on Auto, so Gateway/Core default routing still receives a structured-output `response_model`.
+- VisualFlow `answer_user` lowering now always emits a string `message` payload, preventing connected-but-null message inputs from creating invalid `ANSWER_USER` effects.
+- Structured-output field descriptions from JSON Schema now survive Runtime's Pydantic response-model conversion, so providers receive the same guidance authored in Flow.
+- Local subprocess media execution now supports task-compatible image edit and image upscaling inputs under the same durable image/video contract as in-process Runtime media calls.
+- Runtime now ships its own workspace-path and file-filter helper modules instead of importing unreleased AbstractCore internals, so published installs and release CI use the same supported dependency surface.
+
+## [0.4.27] - 2026-06-03
+
+### Changed
+- Raised the AbstractCore dependency floor to `abstractcore>=2.13.32` so Runtime hosts inherit provider endpoint profiles, route-specific multimodal defaults, and updated audio-understanding model metadata.
+- Updated AbstractCore discovery integration to expose Gateway/Core capability defaults, provider endpoint profiles, and route-specific media catalogs to thin clients.
+
+### Fixed
+- LLM and generated-media execution now resolves Gateway/Core default provider and model selections when VisualFlow nodes leave provider/model on Auto.
+- Media artifact resolution and VisualFlow generated-media calls now preserve uploaded artifacts and progress callbacks across Runtime/AbstractCore boundaries.
+
 ## [0.4.26] - 2026-05-31
 
 ### Changed
@@ -579,7 +612,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.26...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.28...HEAD
+[0.4.28]: https://github.com/lpalbou/abstractruntime/compare/v0.4.27...v0.4.28
+[0.4.27]: https://github.com/lpalbou/abstractruntime/compare/v0.4.26...v0.4.27
 [0.4.26]: https://github.com/lpalbou/abstractruntime/compare/v0.4.25...v0.4.26
 [0.4.25]: https://github.com/lpalbou/abstractruntime/compare/v0.4.24...v0.4.25
 [0.4.24]: https://github.com/lpalbou/abstractruntime/compare/v0.4.23...v0.4.24

{abstractruntime-0.4.26 → abstractruntime-0.4.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.4.26
+Version: 0.4.28
 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
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
-Requires-Dist: abstractcore[audio,media,music,remote,tools,vision,voice]>=2.13.31
+Requires-Dist: abstractcore[audio,music,remote,tools,vision,voice]>=2.13.37
 Requires-Dist: abstractmemory>=0.2.6
 Requires-Dist: abstractsemantics>=0.0.3
 Requires-Dist: anyio<5.0.0,>=4.12.1
@@ -28,19 +28,19 @@ Requires-Dist: httpx<1.0.0,>=0.28.1
 Requires-Dist: openai<2.0.0,>=1.109.1
 Requires-Dist: pandas<3.0.0,>=1.0.0
 Requires-Dist: pillow<13.0.0,>=10.0.0
-Requires-Dist: pymupdf-layout<2.0.0,>=1.26.6
-Requires-Dist: pymupdf4llm<1.0.0,>=0.0.20
+Requires-Dist: pypdf<7.0.0,>=6.0.0
 Requires-Dist: python-pptx<2.0.0,>=1.0.2
+Requires-Dist: reportlab<5.0.0,>=4.0.0
 Requires-Dist: unstructured[docx,odt,pptx,rtf,xlsx]<0.19.0,>=0.18.32
 Provides-Extra: apple
-Requires-Dist: abstractcore[all-apple]>=2.13.31; extra == 'apple'
+Requires-Dist: abstractcore[all-apple]>=2.13.37; extra == 'apple'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'apple'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
 Provides-Extra: gpu
-Requires-Dist: abstractcore[all-gpu]>=2.13.31; extra == 'gpu'
+Requires-Dist: abstractcore[all-gpu]>=2.13.37; extra == 'gpu'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'gpu'
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == 'test'
@@ -52,7 +52,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.26 • **Python:** 3.10+
+**Version:** 0.4.28 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -80,13 +80,18 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.13.31 or newer with remote provider,
-tool, media, vision, voice, audio, and music integration, plus the
+The base install includes AbstractCore 2.13.37 or newer with remote provider,
+tool, vision, voice, audio, and music integration, plus the
 `abstractruntime-mcp-worker` entry point. It keeps inference remote/light by
 default: local engines such as MLX, vLLM, HuggingFace/Torch, Diffusers, and
 sentence-transformer embeddings are not selected unless you choose a hardware
 profile or another package-specific local extra.
 
+VisualFlow PDF document nodes use permissive dependencies in Runtime's base
+install: `Read PDF` extracts text and metadata with `pypdf`, and `Write PDF`
+renders text or Markdown-style report content to real PDF bytes with
+`reportlab`.
+
 Native Python hardware profiles add local inferencer stacks:
 
 ```bash
@@ -159,6 +164,17 @@ Drivers + distribution:
 - scheduler: `create_scheduled_runtime()` (`src/abstractruntime/scheduler/*`)
 - VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
 - VisualFlow multi-entry execution lowering for fan-in routes and per-entry input overrides (`docs/workflow-bundles.md`)
+- VisualFlow LLM Call and Agent nodes propagate Core generation params such as
+  `thinking` through Runtime effects. Provider Models nodes can apply Core
+  `capability_route` filters so run-time model discovery matches Gateway/Flow
+  authoring.
+- VisualFlow image/video nodes and Runtime media helpers preserve task-specific
+  Core media controls, including `count`/`n`, `seeds`, ordered
+  `lora_adapters`, and video `flow_shift`, while keeping provider/model/task
+  truth in AbstractCore and AbstractVision.
+- VisualFlow structured LLM/Agent results preserve `response` as text and expose
+  the schema-conformant object on `data`, so Break Object and Switch can consume
+  fields without reparsing the response string.
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Runtime-owned integrations:

{abstractruntime-0.4.26 → abstractruntime-0.4.28}/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.26 • **Python:** 3.10+
+**Version:** 0.4.28 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
@@ -32,13 +32,18 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.13.31 or newer with remote provider,
-tool, media, vision, voice, audio, and music integration, plus the
+The base install includes AbstractCore 2.13.37 or newer with remote provider,
+tool, vision, voice, audio, and music integration, plus the
 `abstractruntime-mcp-worker` entry point. It keeps inference remote/light by
 default: local engines such as MLX, vLLM, HuggingFace/Torch, Diffusers, and
 sentence-transformer embeddings are not selected unless you choose a hardware
 profile or another package-specific local extra.
 
+VisualFlow PDF document nodes use permissive dependencies in Runtime's base
+install: `Read PDF` extracts text and metadata with `pypdf`, and `Write PDF`
+renders text or Markdown-style report content to real PDF bytes with
+`reportlab`.
+
 Native Python hardware profiles add local inferencer stacks:
 
 ```bash
@@ -111,6 +116,17 @@ Drivers + distribution:
 - scheduler: `create_scheduled_runtime()` (`src/abstractruntime/scheduler/*`)
 - VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
 - VisualFlow multi-entry execution lowering for fan-in routes and per-entry input overrides (`docs/workflow-bundles.md`)
+- VisualFlow LLM Call and Agent nodes propagate Core generation params such as
+  `thinking` through Runtime effects. Provider Models nodes can apply Core
+  `capability_route` filters so run-time model discovery matches Gateway/Flow
+  authoring.
+- VisualFlow image/video nodes and Runtime media helpers preserve task-specific
+  Core media controls, including `count`/`n`, `seeds`, ordered
+  `lora_adapters`, and video `flow_shift`, while keeping provider/model/task
+  truth in AbstractCore and AbstractVision.
+- VisualFlow structured LLM/Agent results preserve `response` as text and expose
+  the schema-conformant object on `data`, so Break Object and Switch can consume
+  fields without reparsing the response string.
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Runtime-owned integrations:

{abstractruntime-0.4.26 → abstractruntime-0.4.28}/docs/README.md

@@ -26,8 +26,10 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 - `faq.md` — common questions (recommended)
 - `troubleshooting.md` — symptom-oriented setup, runtime, and integration fixes
 - `manual_testing.md` — manual smoke tests and how to run the test suite
+- `artifacts.md` — Runtime artifact identity, descriptors, provenance, catalog search, and access stats
 - `integrations/abstractcore.md` — wiring `LLM_CALL` / `TOOL_CALLS`, cached sessions, durable bloc prompt-cache control, media inputs, generated media outputs, video progress events, and tool approval waits via AbstractCore
 - `tools-comms.md` — enabling the optional comms toolset (email/WhatsApp/Telegram)
+- `api.md#workflowbundles-flow-and-visualflow-distribution` — VisualFlow compiler APIs, media nodes, and PDF document nodes (`read_pdf` / `write_pdf`)
 
 ## Features (reference)
 

{abstractruntime-0.4.26 → abstractruntime-0.4.28}/docs/api.md

@@ -117,11 +117,17 @@ These APIs are exported at the package root (see `src/abstractruntime/__init__.p
 ## Artifacts (store by reference)
 
 Implementation: `src/abstractruntime/storage/artifacts.py`.
+Deep dive: `artifacts.md`.
 
 Key types:
 - `ArtifactStore` (interface), `InMemoryArtifactStore`, `FileArtifactStore`
 - helpers: `artifact_ref(...)`, `resolve_artifact(...)`, `is_artifact_ref(...)`
 
+The store keeps payload bytes out of run state and persists structured metadata:
+- `ArtifactDescriptor` is the Runtime-owned descriptor used by Gateway and Observer. It separates `semantic_kind` such as `voice`, `music`, `sound`, or `image` from `render_kind` such as `audio`, `markdown`, `html`, or `json`, and can carry workflow/node/turn links, media facts, generation/provenance data, source refs, security, and action links.
+- `ArtifactAccessStats` records explicit metadata/content/preview/download/export actions when HTTP or UI layers call `record_access(...)`. Plain `load(...)` and `get_metadata(...)` remain side-effect free.
+- `search(...)`, `count(...)`, `facet_counts(...)`, and `stats(...)` provide metadata queries for host control planes. `FileArtifactStore` serves these from a repairable SQLite catalog when possible, including exact `total`, `total_bytes`, and requested facet counts without forcing Gateway/Observer to load every matching artifact.
+
 Artifacts are used by:
 - offloading wrappers (`src/abstractruntime/storage/offloading.py`)
 - evidence capture (`docs/evidence.md`, `src/abstractruntime/evidence/recorder.py`)
@@ -156,9 +162,23 @@ VisualFlow compiler helpers are available from `abstractruntime.visualflow_compi
 - `visual_to_flow(...)` lowers VisualFlow into the internal Flow IR.
 - `compile_visualflow(...)` and `compile_visualflow_tree(...)` compile VisualFlow JSON into executable `WorkflowSpec` objects.
 
-VisualFlow authoring note (media nodes):
-- Runtime recognizes first-class VisualFlow media nodes such as `generate_image`, `edit_image`, `image_to_image`, `generate_video`, `text_to_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, and `listen_voice`.
+VisualFlow authoring note (media and document nodes):
+- Runtime recognizes first-class VisualFlow media nodes such as `generate_image`, `edit_image`, `image_to_image`, `upscale_image`, `image_upscale`, `generate_video`, `text_to_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, and `listen_voice`.
 - Generated-media and transcription nodes lower to a durable `EffectType.LLM_CALL` with an `output` selector (for example `{"modality":"music","task":"music_generation"}`), while `listen_voice` lowers to `WAIT_EVENT`. Hosts should persist the authoring node type rather than pre-lowering to `llm_call`.
+- Runtime also recognizes file/document nodes. `read_file` and `write_file`
+  handle UTF-8 text/JSON workspace paths. In Gateway-hosted runs, those paths
+  follow the shared canonical contract: `rel/path` for the main workspace root
+  and `mount_alias/rel/path` for approved mounts. `read_pdf` extracts text and
+  metadata from PDF paths with `pypdf`; `write_pdf` renders text or
+  Markdown-style content to real PDF bytes with `reportlab`; `list_folder_files`
+  enumerates workspace-scoped folders with family/extension filters;
+  `import_workspace_file` snapshots a workspace file into a durable artifact;
+  `read_artifact` projects saved file content back out as text/JSON/bounded
+  binary metadata; and `export_artifact` writes a durable artifact back to a
+  workspace path. PDF bytes are written to the workspace path and only
+  JSON-safe metadata/path values are stored in run state. In local Runtime-only
+  runs with no workspace scope, relative file-node paths still fall back to the
+  process working directory.
 
 Public bundle APIs are exported from `src/abstractruntime/workflow_bundle/__init__.py` and re-exported in `src/abstractruntime/__init__.py`:
 - open: `open_workflow_bundle(...)`
@@ -180,7 +200,7 @@ This produces a portable record of a run’s state + ledger + artifacts suitable
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install abstractruntime` (AbstractCore 2.13.31 or newer is part of the base install).
+Requires: `pip install abstractruntime` (AbstractCore 2.13.37 or newer is part of the base install).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 
@@ -193,11 +213,14 @@ Entry points:
 - 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`)
+- 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`, `list_vision_adapters`)
 - 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`, `get_model_residency_capabilities`, `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`, `edit_image`, `generate_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, `send_email`, `send_telegram_message`)
+- run-facade helpers create and resume durable child runs for existing runs (`execute_llm_call`, `execute_tool_calls`, `resume_tool_calls`, `generate_image`, `edit_image`, `upscale_image`, `generate_video`, `image_to_video`, `generate_voice`, `generate_music`, `transcribe_audio`, `send_email`, `send_telegram_message`)
+- task-specific image/video helpers preserve batch and adapter controls such as
+  `count`/`n`, `seeds`, ordered `lora_adapters`, and video `flow_shift`; local
+  subprocess isolation stays within the same public contract.
 
 `LLM_CALL` payloads are JSON-safe effect payloads. Common fields:
 - `prompt`, `messages`, `system_prompt`, and convenience `text`
@@ -208,11 +231,11 @@ Entry points:
 Multimodal support:
 - common remote-light AbstractCore media, vision, voice, audio, and music dependencies are part of the base Runtime install
 - local clients call AbstractCore's unified `generate(..., media=..., output=...)`
-- remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, image edits, text-to-video, image-to-video, speech, music generation, and transcription endpoints; pass an output-specific `model` for remote media provider routing, otherwise the server endpoint can use its configured capability default
+- remote and hybrid clients support AbstractCore Server chat media content arrays plus image generation, image edits, image upscaling, text-to-video, image-to-video, speech, music generation, 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/video/voice/music/audio bytes require a runtime `ArtifactStore`; the result contains `artifact_id` / `artifact_ref` instead of inline bytes
 - media-only normalized results expose `runtime_provider` / `runtime_model` separately from `media_provider` / `media_model`
-- optional local media residency failures complete with `status_hint="warning"` and `degraded=true`; unsupported local media warmup for `image_generation`, `video_generation`, `text_to_video`, `image_to_video`, `tts`, `stt`, and `music_generation` reports `requires_long_lived_server=true`, and generated image/video tasks also report `execution_mode="local_one_shot_subprocess"`
+- optional local media residency failures complete with `status_hint="warning"` and `degraded=true`; unsupported local media warmup for `image_generation`, `image_upscale`, `video_generation`, `text_to_video`, `image_to_video`, `tts`, `stt`, and `music_generation` reports `requires_long_lived_server=true`, and generated image/video tasks also report `execution_mode="local_one_shot_subprocess"`
 - Gateway/hosts remain responsible for explicit Core server URLs, Core server auth headers, provider/model defaults, selected local-inference profiles, and translation of Gateway-owned env/config into explicit Runtime inputs; Runtime persists only JSON-safe routing metadata and artifact refs
 
 Prompt cache / cached sessions:

{abstractruntime-0.4.26 → abstractruntime-0.4.28}/docs/architecture.md

@@ -1,7 +1,7 @@
 # AbstractRuntime — Architecture
 
-> Updated: 2026-05-23
-> Version: 0.4.24
+> Updated: 2026-06-13
+> Version: 0.4.28
 > 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.
@@ -38,7 +38,7 @@ The boundary is intentionally narrow:
 - Provider sessions and prompt-cache objects are not runtime state. Runtime may carry stable cache keys, while AbstractCore clients/servers manage warm caches.
 - Hosts should use Runtime-owned AbstractCore facades for discovery snapshots, prompt-cache/model-residency control operations, and durable run-scoped media/comms child runs instead of reaching through private runtime attachments or importing Core internals directly.
 - Local execution can use richer AbstractCore capability plugins. Remote and hybrid execution map the common media cases to AbstractCore Server endpoints and OpenAI-compatible content arrays, while hybrid keeps tool execution local.
-- Gateway and other hosts compose Runtime with the desired memory and local-inference profile. Runtime's base package includes the AbstractMemory contract, AbstractCore remote/tool/media capability integration, and the MCP worker entry point, but not backend extras such as LanceDB or local inferencer stacks. Hosts choose storage, embeddings, readiness policy, and whether to add `abstractruntime[apple]` or `abstractruntime[gpu]`.
+- Gateway and other hosts compose Runtime with the desired memory and local-inference profile. Runtime's base package includes the AbstractMemory contract, AbstractCore remote/tool capability integration, Runtime-owned permissive PDF read/write support, and the MCP worker entry point, but not backend extras such as LanceDB, Core media document stacks, or local inferencer stacks. Hosts choose storage, embeddings, readiness policy, and whether to add `abstractruntime[apple]` or `abstractruntime[gpu]`.
 - 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.
@@ -213,6 +213,10 @@ The scheduler is an in-process driver loop that resumes due waits and can delive
 AbstractRuntime includes a compiler and a portable bundle format:
 - VisualFlow compiler: `src/abstractruntime/visualflow_compiler/*` (VisualFlow JSON -> `WorkflowSpec`)
 - Multi-entry VisualFlow authoring routes are lowered into internal `join_exec` and `path_mux` nodes when a target has multiple incoming `exec-in` edges plus per-route input overrides. This keeps authoring JSON clean while making runtime behavior explicit and restart-safe. See `workflow-bundles.md` for the concrete metadata shape.
+- VisualFlow document nodes include `read_pdf` and `write_pdf`. They use
+  workspace-scoped paths, keep PDF bytes out of checkpoints, and store only
+  JSON-safe extracted text, metadata, hashes, content types, and file paths in
+  node outputs.
 - WorkflowBundles (`.flow`): `src/abstractruntime/workflow_bundle/*` (manifest + flows + assets)
   - pack/unpack helpers: `pack_workflow_bundle(...)`, `open_workflow_bundle(...)`
 

abstractruntime-0.4.28/docs/artifacts.md

@@ -0,0 +1,149 @@
+# Runtime artifacts
+
+AbstractRuntime stores large payloads as artifacts so run state, ledger records,
+and workflow outputs remain JSON-safe. Artifacts are the durable record for
+files, generated media, tool evidence, exported history bundles, and other
+payloads that should be referenced by id rather than embedded inline.
+
+The implementation lives in `src/abstractruntime/storage/artifacts.py`.
+
+## File-like vocabulary boundary
+
+Runtime artifacts are not the same thing as live filesystem paths:
+
+- `Artifact`: a Runtime-owned durable payload safe to persist, search, reuse,
+  and pass between runs by reference.
+- `Workspace File` / `Workspace Folder`: a server-side path capability under
+  Gateway/runtime workspace policy. These are path values, not durable payloads.
+- `Local File` / `Local Folder`: a client-side intake source. In hosted/browser
+  mode they should be uploaded and normalized into artifacts before durable
+  execution.
+
+Gateway/Flow product copy may say `Server File` / `Server Folder` when users
+choose an origin, but Runtime stays anchored on artifact refs versus
+workspace-scoped paths.
+
+## Artifact identity
+
+An artifact has a stable `artifact_id`, a `blob_id` for content deduplication
+when the backend supports it, and a `run_id` scope. JSON state and Gateway APIs
+pass artifacts with refs such as:
+
+```json
+{
+  "$artifact": "a7050ebc5c8330...",
+  "artifact_id": "a7050ebc5c8330...",
+  "run_id": "9e19bd6a-ba07-4c2e-86c6-94ec7ca0a373",
+  "content_type": "audio/wav",
+  "size_bytes": 5293012
+}
+```
+
+The ref is a pointer, not authorization. Hosts such as AbstractGateway are
+responsible for deciding which principal may list or read an artifact.
+
+## Stored metadata
+
+Runtime stores two metadata layers:
+
+- `tags`: string fields for compatibility and simple lookups.
+- `metadata`: structured JSON for producer-specific details.
+- `descriptor`: a Runtime-owned `ArtifactDescriptor` that normalizes the fields
+  Gateway and Observer should use.
+
+The descriptor separates display format from semantic meaning:
+
+- `render_kind`: how the artifact should be rendered, such as `image`, `audio`,
+  `video`, `markdown`, `html`, `json`, `text`, or `document`.
+- `semantic_kind`: what the artifact represents, such as `voice`, `music`,
+  `sound`, `transcript`, `evidence`, `workflow_snapshot`, or `image`.
+- `classification_source`: whether the classification came from the producer,
+  runtime tags, MIME inference, or legacy fallback.
+
+The descriptor can also carry `session_id`, `workflow_id`, `node_id`, `turn_id`,
+`ledger_cursor`, `producer`, `generation`, `media`, `source_refs`, `links`,
+`security`, and action metadata. Producer metadata may be sparse; consumers
+should show missing fields as unavailable rather than guessing.
+
+## Generated media provenance
+
+When generated media is produced through the Runtime AbstractCore integration
+with output selectors, Runtime stores descriptor and metadata alongside the
+bytes. Current generated outputs include image, video, voice/TTS, music, sound
+or audio outputs, and transcription-style text outputs where the host route
+stores a transcript artifact.
+
+Generated-media descriptors record available producer facts:
+
+- package/capability route, provider, model, backend, and runtime provider/model
+  when they differ;
+- prompt or TTS text, requested format, output index, negative prompt, and
+  redacted generation parameters;
+- source artifact refs for edit, image-to-video, cloned/reference voice, or
+  other source-media flows when provided;
+- measured media facts such as duration, sample rate, dimensions, channels, or
+  frame counts when the store can inspect the bytes.
+
+Runtime redacts obvious secret fields and bounds large metadata values. It does
+not store raw provider requests as indexed descriptor fields.
+
+Gateway or package producers that store artifacts outside the main Runtime
+generated-media path should use `build_artifact_descriptor_payload(...)` from
+`abstractruntime.storage.artifacts`. That helper applies the Runtime descriptor
+schema, bounded secret-key redaction, and prompt/text sensitivity labels without
+making Gateway invent a parallel descriptor contract.
+
+## Catalog and search
+
+`InMemoryArtifactStore` and `FileArtifactStore` support:
+
+- `store(...)`, `load(...)`, and `get_metadata(...)`;
+- `update_metadata(...)` for descriptor or structured metadata enrichment;
+- `search(...)` for bounded pages;
+- `count(...)`, `facet_counts(...)`, and `stats(...)` for exact totals and
+  filter chips;
+- `record_access(...)` for explicit metadata/content/preview/download/export
+  counters.
+
+`FileArtifactStore` maintains a repairable SQLite catalog for descriptor fields,
+time filters, exact counts, byte totals, and facets. The catalog is an index of
+Runtime-owned artifact metadata; the payload bytes and metadata files remain the
+source of truth.
+
+Plain `load(...)` and `get_metadata(...)` are side-effect free. UI and HTTP
+layers that want access statistics must call `record_access(...)` or use Gateway
+content routes that label the action.
+
+## Gateway and Observer
+
+AbstractGateway exposes Runtime artifacts through bounded HTTP APIs. Search
+responses include `artifact_envelope_v1`, which projects Runtime descriptors,
+media facts, access stats, and action links while preserving legacy row fields.
+Gateway only forwards descriptor action links that are relative Gateway/UI
+links; arbitrary external provider URLs should be represented as trace
+availability or Gateway-owned trace records instead.
+
+AbstractObserver renders Gateway envelopes. It should not infer canonical
+artifact meaning from filenames or raw content except as a visible legacy
+fallback. Use the Runtime tab for artifact inventory and the Observe tab for the
+workflow/ledger narrative.
+
+## Retrieval boundaries
+
+Artifact search answers questions about stored files and media by metadata,
+scope, type, time, producer, and links back to runs. It is not a semantic memory
+search system.
+
+- Use the ledger for "what happened in this workflow?"
+- Use artifact search for "what files/media exist and how were they produced?"
+- Use AbstractMemory/KG retrieval for "what knowledge or relationships were
+  learned?"
+- Use Gateway audit/provider links for system-level request traces when the
+  envelope reports them.
+
+## Limits
+
+Legacy artifacts may only have MIME type and tags. Runtime projects them with
+fallback descriptor fields so clients can still list and preview them, but
+producer-level prompt/model/source provenance is only available for artifacts
+created through descriptor-aware paths.

{abstractruntime-0.4.26 → abstractruntime-0.4.28}/docs/backlog/README.md

@@ -14,7 +14,7 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 
 - Planned: 5
 - Proposed: 3
-- Completed: 30
+- Completed: 33
 - Deprecated: 13
 - Recurrent: 0
 
@@ -70,6 +70,9 @@ If you are new to the project, start with `../README.md` and `../architecture.md
 | 0037 | `completed/0037_visualflow_generate_music_node_compiler_parity.md` |
 | 0039 | `completed/0039_runtime_music_structure_prompt_bool_contract.md` |
 | 0040 | `completed/0040_task_agnostic_local_residency_listing.md` |
+| 0041 | `completed/0041_runtime_hardware_extras_avoid_nonpermissive_document_stacks.md` |
+| 0042 | `completed/0042_core_vision_upscale_and_parameter_surface.md` |
+| 0043 | `completed/0043_runtime_vision_adapter_and_batch_surface.md` |
 
 ## Planned
 

abstractruntime-0.4.28/docs/backlog/completed/0041_runtime_hardware_extras_avoid_nonpermissive_document_stacks.md

@@ -0,0 +1,41 @@
+# Completed: Runtime hardware extras avoid nonpermissive document stacks
+
+## Metadata
+- Created: 2026-06-05
+- Status: Completed
+- Completed: 2026-06-06
+
+## ADR status
+- Governing ADRs: root `docs/adr/0029-permissive-dependency-and-licensing-policy.md`, root `docs/adr/0033-install-profiles-config-entrypoints-and-server-boundaries.md`
+- ADR impact: None. This completes the Runtime-side enforcement of the existing permissive dependency and install-profile policies.
+
+## Context
+Runtime's base VisualFlow PDF nodes use permissive dependencies:
+
+- `pypdf` for PDF text and metadata extraction;
+- `reportlab` for PDF writing.
+
+The remaining risk was that Runtime `apple` and `gpu` extras delegated to Core aggregate profiles that previously pulled PyMuPDF-family packages. Core item `0805` moved the default Core PDF route to `pypdf` and isolated PyMuPDF-family packages behind the explicit `pdf-pymupdf-commercial` extra.
+
+## What changed
+- Runtime remains versioned with mandatory `pypdf` and `reportlab` base dependencies, so light, Apple, and GPU installs all receive PDF read/write support.
+- Runtime packaging tests now assert PyMuPDF-family packages are absent from the Runtime base, `apple`, and `gpu` profile definitions.
+- Runtime packaging tests also inspect the sibling Core `all-apple` and `all-gpu` profiles in the monorepo and assert they contain `pypdf` but not PyMuPDF-family packages.
+- The attachment/open test now creates a PDF through Runtime's ReportLab writer instead of PyMuPDF, proving the default route parses PDFs without the optional commercial backend.
+
+## Current code pointers
+- `pyproject.toml`
+- `src/abstractruntime/documents/pdf.py`
+- `tests/test_packaging_extras.py`
+- `tests/test_visualflow_file_nodes_workspace.py`
+- `tests/test_session_attachments_registry_and_open_tool.py`
+
+## Validation
+- `python -m pytest tests/test_visualflow_file_nodes_workspace.py tests/test_session_attachments_registry_and_open_tool.py::test_open_attachment_pdf_extracts_text_when_media_stack_available tests/test_packaging_extras.py -q`
+  - Result: 6 passed.
+
+## Completion report
+Runtime hardware profile PDF dependency inheritance is now aligned with the permissive default policy. PyMuPDF remains possible only through Core's explicit opt-in extra; Runtime does not install it by default in base, Apple, or GPU profiles.
+
+## Residual follow-up
+Core item `0806_pdf_images_tables_and_extraction_strategy.md` tracks richer image/table/OCR support. That work must keep capability reporting truthful and must not reintroduce PyMuPDF-family packages into default install profiles.

abstractruntime-0.4.28/docs/backlog/completed/0042_core_vision_upscale_and_parameter_surface.md

@@ -0,0 +1,80 @@
+# 0042 Core Vision Upscale and Parameter Surface
+
+## Metadata
+- Created: 2026-06-07
+- Completed: 2026-06-07
+- Status: Completed
+- Owner: AbstractRuntime
+- Origin: follow-up to AbstractCore and AbstractVision releases that added richer Vision/Core models, image upscaling, and generation controls.
+
+## ADR Status
+- Governing ADRs:
+  - `docs/adr/0004_runtime_owns_run_scoped_media_execution_truth.md`
+  - `docs/adr/0005_runtime_owns_abstractcore_host_discovery_queries.md`
+  - `docs/adr/0007_runtime_relays_core_owned_model_residency_truth.md`
+- ADR impact: none. This work applies the existing Runtime-owned execution and discovery boundary to the newly exposed Core/Vision surface.
+
+## Current Code Reality
+
+- Runtime already exposes durable run-facade helpers for image generation, image edit, text-to-video, image-to-video, TTS, music, and STT.
+- Runtime discovery already relays Core/Vision provider-model catalogs, but its local Vision task allowlist only accepts `text_to_image`, `image_to_image`, `text_to_video`, and `image_to_video`.
+- Remote generated-media routing handles Core image generation/edit and video generation/edit endpoints, including async video progress, but it has no `image_upscale` route.
+- VisualFlow media-node lowering forwards common image/video parameters, but not the newer Core/Vision controls such as `guidance_2` or image upscaler parameters.
+- Runtime model residency support reports media tasks, but does not yet include image upscaling.
+
+## Architecture Review
+
+Alternatives considered:
+
+1. **Duplicate Core's model and task registry in Runtime.**
+   - Rejected because Core owns model capabilities and provider residency truth. Runtime should relay and route, not become a second registry.
+2. **Let Gateway call Core's new upscaler endpoint directly.**
+   - Rejected for run-scoped media work because ADR 0004 requires Runtime-owned child-run history and artifact provenance.
+3. **Add a generic untyped Core pass-through media endpoint.**
+   - Deferred. It would be flexible, but it would make thin-client contracts weaker and harder to validate.
+4. **Extend Runtime's existing media abstractions with `image_upscale` and pass through named Core/Vision controls.**
+   - Recommended. It keeps the boundary simple, preserves child-run durability, and avoids registry duplication.
+
+## Goal
+
+Make Runtime support the richer AbstractCore/Vision media surface without guessing model truth:
+
+- relay `image_upscale` in Vision discovery;
+- execute image upscaling through Runtime-owned child runs and Core remote/local integration paths;
+- pass through new generation controls such as `guidance_2` and upscaler controls;
+- expose truthful residency/task support for image upscaling;
+- keep progress callbacks as ledger `abstract.progress` events and never persist callbacks.
+
+## Acceptance Criteria
+
+- `AbstractCoreRunFacade` exposes a durable `upscale_image(...)` helper.
+- Remote Core execution routes `output={"modality":"image","task":"image_upscale"}` to `/v1/images/upscale` or `/{provider}/v1/images/upscale`.
+- Local Core execution can route an upscaling output spec through the existing multimodal provider path.
+- Runtime discovery accepts `task=image_upscale` for Vision provider-model catalogs and cached model filters.
+- Runtime VisualFlow compilation/lowering recognizes an `upscale_image` / `image_upscale` node shape and forwards upscaler parameters.
+- `guidance_2` is forwarded for image/video generation and edit paths where supplied.
+- Model-residency task reporting includes `image_upscale`.
+- Focused tests prove request payloads, artifact storage, discovery filters, and progress callback behavior.
+
+## Review Checklist
+
+- No direct Gateway/Core bypass is introduced.
+- No model capability or provider residency truth is inferred in Runtime.
+- Generated media outputs remain artifact-backed and run-scoped.
+- Callback objects are not serialized into run vars, effect payloads, or artifacts.
+- Existing image/video/music/STT tests remain green.
+
+## Implementation Summary
+
+- Added `image_upscale` to Runtime's Core Vision discovery task allowlist and model-residency capability descriptors.
+- Added `AbstractCoreRunFacade.upscale_image(...)`, preserving parent/child run ownership and artifact provenance.
+- Routed remote `output={"modality":"image","task":"image_upscale"}` calls to AbstractCore Server image upscaling endpoints, including the async job/progress path when a progress callback is active.
+- Forwarded newer Core/Vision parameters including `guidance_2` for image/video generation/edit paths and upscaler controls for image upscaling.
+- Added VisualFlow compiler/executor recognition for `upscale_image` / `image_upscale` nodes.
+- Updated Runtime docs, FAQ, troubleshooting, and AI-readable indexes for the new Core floor and media surface.
+
+## Validation
+
+- `PYTHONPATH=src:../abstractcore python -m compileall -q src/abstractruntime/integrations/abstractcore src/abstractruntime/visualflow_compiler src/abstractruntime/core/runtime.py`
+- `PYTHONPATH=src:../abstractcore pytest -q tests/test_packaging_extras.py tests/test_visualflow_media_nodes.py tests/test_model_residency_control_plane.py::test_model_residency_capabilities_describe_core_backed_truth_by_task tests/test_abstractcore_run_facade.py::test_run_facade_upscale_image_creates_durable_child_run_with_media tests/test_multimodal_abstractcore_integration.py::test_remote_image_upscale_uses_abstractcore_images_upscale_endpoint_and_stores_artifact tests/test_multimodal_abstractcore_integration.py::test_remote_image_upscale_with_progress_uses_core_job_endpoint tests/test_abstractcore_discovery_facade.py::test_local_vision_provider_models_accept_image_upscale_task_from_cache`
+  - Result: `23 passed in 0.29s`