AbstractRuntime 0.4.2__tar.gz → 0.4.4__tar.gz

abstractruntime-0.4.4/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e ".[abstractcore,mcp-worker,test]"
+      - name: Pytest basic suite
+        run: python -m pytest -q -m basic
+      - name: Pytest focused runtime suite
+        run: |
+          python -m pytest -q \
+            tests/test_tool_approval_executor.py \
+            tests/test_tool_approval_resume_executes.py \
+            tests/test_remote_llm_client.py \
+            tests/test_prompt_cache_modules.py \
+            tests/test_multimodal_abstractcore_integration.py \
+            tests/test_visualflow_llm_call_multimodal_output.py \
+            tests/test_visual_multi_entry_loop_overrides.py \
+            tests/test_control_adapter_while.py \
+            tests/test_jsonl_ledger_recovery.py \
+            tests/test_llm_client_media_artifacts.py
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Build
+        run: |
+          python -m pip install -U pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+
+  docs:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e ".[docs]"
+      - name: MkDocs build
+        run: mkdocs build -q

abstractruntime-0.4.4/.github/workflows/release.yml

@@ -0,0 +1,281 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version, with or without the leading v (example: 0.4.3)"
+        required: true
+        type: string
+      publish:
+        description: "Publish to PyPI, create the GitHub Release, and deploy docs"
+        required: true
+        type: boolean
+        default: false
+      publish_confirmation:
+        description: "Required only when publish=true: publish-abstractruntime-<version>"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e ".[abstractcore,mcp-worker,test]"
+      - name: Pytest basic suite
+        run: python -m pytest -q -m basic
+      - name: Pytest focused runtime suite
+        run: |
+          python -m pytest -q \
+            tests/test_tool_approval_executor.py \
+            tests/test_tool_approval_resume_executes.py \
+            tests/test_remote_llm_client.py \
+            tests/test_prompt_cache_modules.py \
+            tests/test_multimodal_abstractcore_integration.py \
+            tests/test_visualflow_llm_call_multimodal_output.py \
+            tests/test_visual_multi_entry_loop_overrides.py \
+            tests/test_control_adapter_while.py \
+            tests/test_jsonl_ledger_recovery.py \
+            tests/test_llm_client_media_artifacts.py
+
+  docs:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e ".[docs]"
+      - name: MkDocs build
+        run: mkdocs build -q
+
+  build:
+    name: Validate and build distributions
+    runs-on: ubuntu-latest
+    needs: [test, docs]
+    outputs:
+      version: ${{ steps.release-meta.outputs.version }}
+      tag: ${{ steps.release-meta.outputs.tag }}
+      should_publish: ${{ steps.release-meta.outputs.should_publish }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install build tools
+        run: |
+          python -m pip install -U pip
+          python -m pip install build twine
+      - name: Validate version, changelog, tag, and publish guard
+        id: release-meta
+        env:
+          RELEASE_INPUT_VERSION: ${{ inputs.version }}
+          RELEASE_PUBLISH: ${{ inputs.publish }}
+          RELEASE_CONFIRMATION: ${{ inputs.publish_confirmation || '' }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          import re
+          import subprocess
+          import tomllib
+          import urllib.error
+          import urllib.request
+          from pathlib import Path
+
+          raw_version = os.environ["RELEASE_INPUT_VERSION"].strip()
+          version = raw_version[1:] if raw_version.startswith("v") else raw_version
+          if not re.fullmatch(r"\d+\.\d+\.\d+(?:[a-zA-Z0-9.-]+)?", version):
+              raise SystemExit(f"Invalid release version: {raw_version!r}")
+          tag = f"v{version}"
+
+          pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+          package_version = pyproject["project"]["version"]
+          if version != package_version:
+              raise SystemExit(
+                  f"Requested version {version!r} does not match pyproject.toml version {package_version!r}"
+              )
+
+          changelog = Path("CHANGELOG.md").read_text(encoding="utf-8")
+          header = re.search(rf"^## \[{re.escape(version)}\] - .+$", changelog, re.MULTILINE)
+          if not header:
+              raise SystemExit(f"CHANGELOG.md has no entry for {version}")
+
+          rest = changelog[header.end():]
+          next_header = re.search(r"^## \[", rest, re.MULTILINE)
+          notes = rest[: next_header.start() if next_header else len(rest)].strip()
+          if not notes:
+              raise SystemExit(f"CHANGELOG.md entry for {version} is empty")
+          Path("release-notes.md").write_text(notes + "\n", encoding="utf-8")
+
+          publish = os.environ["RELEASE_PUBLISH"].lower() == "true"
+          if publish:
+              if os.environ.get("GITHUB_REF") != "refs/heads/main":
+                  raise SystemExit("Publishing is only allowed from the main branch.")
+
+              expected = f"publish-abstractruntime-{version}"
+              confirmation = os.environ.get("RELEASE_CONFIRMATION", "").strip()
+              if confirmation != expected:
+                  raise SystemExit(
+                      f"publish_confirmation must be exactly {expected!r}; got {confirmation!r}"
+                  )
+
+              tag_check = subprocess.run(
+                  ["git", "ls-remote", "--exit-code", "--tags", "origin", f"refs/tags/{tag}"],
+                  check=False,
+                  stdout=subprocess.DEVNULL,
+                  stderr=subprocess.DEVNULL,
+              )
+              if tag_check.returncode == 0:
+                  raise SystemExit(f"Remote tag {tag} already exists.")
+              if tag_check.returncode not in (0, 2):
+                  raise SystemExit(f"Could not check remote tag {tag}.")
+
+              try:
+                  with urllib.request.urlopen(
+                      f"https://pypi.org/pypi/AbstractRuntime/{version}/json",
+                      timeout=20,
+                  ) as response:
+                      json.load(response)
+                  raise SystemExit(f"PyPI already has AbstractRuntime {version}.")
+              except urllib.error.HTTPError as exc:
+                  if exc.code != 404:
+                      raise
+
+          output = Path(os.environ["GITHUB_OUTPUT"])
+          with output.open("a", encoding="utf-8") as fh:
+              print(f"version={version}", file=fh)
+              print(f"tag={tag}", file=fh)
+              print(f"should_publish={str(publish).lower()}", file=fh)
+          PY
+      - name: Build
+        run: python -m build
+      - name: Check distributions
+        run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-dist
+          path: dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-notes
+          path: release-notes.md
+
+  ensure-tag:
+    name: Ensure release tag
+    runs-on: ubuntu-latest
+    needs: build
+    if: needs.build.outputs.should_publish == 'true'
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Create annotated tag
+        run: |
+          tag="${{ needs.build.outputs.tag }}"
+          if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null 2>&1; then
+            echo "Tag ${tag} already exists on origin."
+            exit 1
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "${tag}" -m "AbstractRuntime ${tag}"
+          git push origin "${tag}"
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build, ensure-tag]
+    if: needs.build.outputs.should_publish == 'true'
+    environment:
+      name: pypi
+      url: https://pypi.org/project/AbstractRuntime/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [build, ensure-tag, publish-pypi]
+    if: needs.build.outputs.should_publish == 'true'
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-notes
+          path: .
+      - uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.build.outputs.tag }}
+          name: AbstractRuntime ${{ needs.build.outputs.tag }}
+          body_path: release-notes.md
+          files: dist/*
+          fail_on_unmatched_files: true
+
+  deploy-docs:
+    name: Deploy docs to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: [build, github-release]
+    if: needs.build.outputs.should_publish == 'true'
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install docs dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e ".[docs]"
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: Deploy MkDocs site
+        run: mkdocs gh-deploy --force --clean --message "Deploy docs for ${{ needs.build.outputs.tag }}"

{abstractruntime-0.4.2 → abstractruntime-0.4.4}/.gitignore

@@ -11,6 +11,7 @@ __pycache__/
 build/
 develop-eggs/
 dist/
+site/
 downloads/
 eggs/
 .eggs/
@@ -85,4 +86,4 @@ venv.bak/
 # End Generation Here
 ```
 
-.DS_Store
+.DS_Store

{abstractruntime-0.4.2 → abstractruntime-0.4.4}/ACKNOWLEDGMENTS.md

@@ -7,14 +7,14 @@ The canonical dependency list lives in `pyproject.toml`.
 
 ## Runtime dependencies (core install)
 
-- **abstractsemantics** — structured schema registry support (declared in `pyproject.toml`, used in `src/abstractruntime/integrations/abstractmemory/effect_handlers.py` and VisualFlow execution wiring).
+- **abstractsemantics** (`>=0.0.2`) — structured schema registry support (declared in `pyproject.toml`, used in `src/abstractruntime/integrations/abstractmemory/effect_handlers.py` and VisualFlow execution wiring).
 
 ## Optional integrations (extras)
 
 Installed only when you opt in to extras:
-- **abstractcore** — LLM + tools integration used by `abstractruntime[abstractcore]` (declared in `pyproject.toml`, implementation under `src/abstractruntime/integrations/abstractcore/*`, docs: `docs/integrations/abstractcore.md`).
+- **abstractcore** (`>=2.11.8`) — LLM + tools integration used by `abstractruntime[abstractcore]` (declared in `pyproject.toml`, implementation under `src/abstractruntime/integrations/abstractcore/*`, docs: `docs/integrations/abstractcore.md`).
   - The AbstractCore integration uses **httpx** for remote mode (`src/abstractruntime/integrations/abstractcore/llm_client.py`) and **pydantic** for structured validation (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). These are provided by AbstractCore’s dependency set.
-- **abstractcore[tools]** — toolchain extra used by `abstractruntime[mcp-worker]` (declared in `pyproject.toml`) and intended to include HTML parsing dependencies (see comments in `pyproject.toml`).
+- **abstractcore[tools]** (`>=2.11.8`) — toolchain extra used by `abstractruntime[mcp-worker]` (declared in `pyproject.toml`) and intended to include HTML parsing dependencies (see comments in `pyproject.toml`).
 - **RestrictedPython** (optional) — used for sandboxed execution of VisualFlow “Code” nodes when available (`src/abstractruntime/visualflow_compiler/visual/code_executor.py`).
 
 ## Build & test tooling

{abstractruntime-0.4.2 → abstractruntime-0.4.4}/CHANGELOG.md

@@ -7,10 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.4] - 2026-05-07
+
 ### Added
+- **AbstractCore multimodal generation integration**:
+  - `LLM_CALL` now forwards AbstractCore's unified `generate(..., output=...)` selector for image generation, TTS/voice output, and audio transcription
+  - generated binary outputs are normalized into JSON-safe runtime results with ArtifactStore-backed refs instead of inline bytes
+  - local runtimes can use AbstractCore capability plugins such as AbstractVision and AbstractVoice through the same runtime effect shape
+  - remote runtimes support AbstractCore Server image generation, speech, and transcription endpoints, plus OpenAI-compatible chat media content arrays
+- **Multimodal packaging extra**:
+  - new `abstractruntime[multimodal]` extra installs `abstractcore[media,openai,vision,voice,audio]>=2.13.8`
+- **VisualFlow LLM media selectors**:
+  - LLM nodes lowered from VisualFlow can request generated media through `output` / `outputs` from node config or input data
+
 ### Changed
+- Minimum `abstractcore` optional dependency increased to `>=2.13.8` for the unified multimodal response types.
+- `LLM_CALL` accepts top-level `text`, top-level `output`, and top-level `outputs` as a runtime alias for AbstractCore `output`.
+- `LLM_CALL.media` accepts one media item or a list; artifact refs are materialized to provider-ready temporary files before model calls.
+- Remote AbstractCore clients now preserve existing OpenAI-style content arrays when adding media attachments.
+- Remote AbstractCore clients now resolve ArtifactStore-backed media refs for direct client use, matching the runtime effect-handler path.
+- VisualFlow LLM pending-call lowering now carries `output` / `outputs` selectors into runtime LLM effects.
+- VisualFlow LLM result syncing now projects generated media artifacts into node outputs such as `outputs`, `resources`, `artifact_ref`, `artifact_id`, and `meta.output_mode`.
 
 ### Fixed
+- Runtime artifact metadata (`run_id`, tags, artifact ids) is kept out of AbstractCore provider/capability kwargs while still being applied to stored generated media artifacts.
+- Generated binary media now fails closed without an ArtifactStore instead of embedding base64 bytes in durable state.
+- Remote image/TTS/STT calls no longer reuse the chat model unless an output-specific media model is supplied.
+- Remote media inputs now either convert to a provider-ready content item or fail before dispatch; unsupported remote image edits, voice reference inputs, and non-file STT inputs are rejected explicitly.
+- Turn-grounding injection now preserves structured multimodal message content arrays instead of stringifying them.
+- Session-scoped prompt-cache key derivation now uses the effective AbstractCore client provider/model identity when an `LLM_CALL` payload omits explicit provider/model overrides.
+
+### Documentation
+- Documented multimodal `LLM_CALL` payloads, artifact-backed response shape, remote endpoint coverage, cached-session/prompt-cache boundaries, and the `abstractruntime[multimodal]` extra in the AbstractCore integration guide, API reference, architecture guide, FAQ, README, getting-started guide, docs index, and AI-ready `llms*.txt` files.
+- Added a planned workspace/media access policy item covering default workspace-only access, explicit user allow/deny paths, and a conscious full-machine access mode for long-running agency deployments.
+
+### Testing
+- Added focused coverage for multimodal response normalization, artifact-backed generated media, media-only transcription calls, remote image/TTS/STT endpoints, remote media guardrails, remote chat media content arrays, content-array prompt extraction, direct remote artifact-ref media resolution, text-alias routing, provider-request redaction, and runtime metadata/tag boundaries.
+- Added coverage for effective prompt-cache key identity and VisualFlow LLM media selector/result projection.
+
+## [0.4.3] - 2026-05-06
+
+### Added
+- **AbstractCore prompt-cache control plane**:
+  - local, multi-local, and remote LLM clients expose `get_prompt_cache_capabilities`, `get_prompt_cache_stats`, `prompt_cache_set`, `prompt_cache_update`, `prompt_cache_fork`, `prompt_cache_clear`, and `prompt_cache_prepare_modules`
+  - local clients can maintain compartmentalized `system | tools | history` prompt-cache modules when providers support `local_control_plane`
+  - remote clients proxy `/acore/prompt_cache/*` endpoints for gateway/CLI hosts
+- **Artifact-backed media for AbstractCore LLM calls**:
+  - local and remote AbstractCore clients can resolve runtime artifact refs into provider-ready media inputs
+  - AbstractCore runtime factories now pass the runtime artifact store into LLM clients
+- **Durable tool approval execution**:
+  - `ToolApprovalPolicy` and `ApprovalToolExecutor` support safe auto-approval, durable approval waits, and approved re-execution
+  - runtime factories expose the configured tool executor for approval-style `TOOL_CALLS` resumes
+- **VisualFlow multi-entry lowering**:
+  - authoring graphs with multiple incoming `exec-in` routes can be lowered into internal `join_exec` and `path_mux` nodes
+  - per-entry input overrides survive pause/resume and file-store restart scenarios
+
+### Changed
+- AbstractCore remote provider-key overrides now use `X-AbstractCore-Provider-API-Key` headers instead of body/query `api_key` fields rejected by current AbstractCore servers.
+- AbstractCore LLM clients keep per-turn grounding out of stable system prompts, coalesce leading system messages, strip internal tool-activity system messages, and propagate trace metadata headers.
+- AbstractCore runtime factories expose the underlying LLM client for host-side control-plane operations and continue to honor AbstractCore timeout/config defaults.
+- Default runtime iteration budget increased from 25 to 50.
+- Minimum AbstractCore optional dependency increased to `>=2.13.5` so the documented prompt-cache control plane, hardened server auth, provider-key header routing, Telegram tools, and current model/provider behavior are available by default.
+- Documentation: align version references with `pyproject.toml` (0.4.3), document AbstractCore prompt-cache operations, update remote provider-key guidance, and add concrete VisualFlow multi-entry authoring metadata.
+- CI/release automation now builds the package and docs on normal CI and exposes a manual-only guarded release path for PyPI, GitHub Releases, and the docs site.
+
+### Fixed
+- VisualFlow While nodes again route `condition=true` to Loop and `condition=false` to Done/parent/complete after the execution-handle tracking refactor.
+- Tool approval resumes now execute approved calls in-runtime when configured, return structured tool errors when denied or unavailable, and append completion ledger records for ledger-only replay clients.
+- JSONL ledger listing now recovers concatenated JSON records defensively.
+- `TOOL_CALLS` now emits durable warnings for missing or duplicate tool call ids.
+- Optional VisualFlow fixture tests now skip cleanly when assessment fixtures are absent.
+
+### Testing
+- Added focused coverage for prompt-cache module preparation/rebuilds, remote prompt-cache proxying, artifact-backed media, tool approval waits/resumes, JSONL ledger recovery, remote provider-key headers, VisualFlow multi-entry prompt overrides, direct effect re-entry, same-predecessor route handles, stale route metadata, join-only fan-in, and While routing regressions.
+
+## [0.4.2] - 2026-02-08
+
+### Changed
+- **Dependencies**:
+  - bump minimum `abstractcore` / `abstractcore[tools]` to `>=2.11.8` (`pyproject.toml`)
+  - bump minimum `abstractsemantics` to `>=0.0.2` (`pyproject.toml`)
 
 ## [0.4.1] - 2026-02-04
 
@@ -247,7 +323,10 @@ 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.1...HEAD
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.4...HEAD
+[0.4.4]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.4.4
+[0.4.3]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.4.3
+[0.4.2]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.4.2
 [0.4.1]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.4.1
 [0.4.0]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.4.0
 [0.0.1]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.0.1

{abstractruntime-0.4.2 → abstractruntime-0.4.4}/CONTRIBUTING.md

@@ -8,6 +8,9 @@ AbstractRuntime is a **durable workflow runtime** (interrupt → checkpoint →
 
 Prereqs: **Python 3.10+**.
 
+Recommended (workspace checkout): develop inside the [AbstractFramework](https://github.com/lpalbou/AbstractFramework) workspace.  
+The test bootstrap (`tests/conftest.py`) will auto-wire sibling projects on `sys.path` (e.g., `abstractcore/`, `abstractmemory/`, `abstractsemantics/`, `abstractflow/`).
+
 ```bash
 python -m venv .venv
 source .venv/bin/activate
@@ -19,6 +22,8 @@ python -m pip install -e ".[abstractcore,mcp-worker]"
 python -m pytest -q
 ```
 
+If you cloned **only** this repo (without the AbstractFramework workspace), make sure the sibling packages above are importable (install them or clone them next to this repo) before running the full test suite.
+
 ## Repo map (source of truth)
 
 - Public exports: `src/abstractruntime/__init__.py` (keep this consistent with `docs/api.md`)
@@ -55,4 +60,3 @@ When behavior changes, update:
 
 - Bump `version` in `pyproject.toml`
 - Add a dated section to `CHANGELOG.md` (Keep a Changelog format)
-

abstractruntime-0.4.2/README.md → abstractruntime-0.4.4/PKG-INFO

@@ -1,10 +1,65 @@
+Metadata-Version: 2.4
+Name: AbstractRuntime
+Version: 0.4.4
+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
+Project-URL: Documentation, https://www.lpalbou.info/AbstractRuntime/
+Project-URL: Changelog, https://github.com/lpalbou/abstractruntime/blob/main/CHANGELOG.md
+Author: Laurent-Philippe Albou
+License: MIT
+License-File: LICENSE
+Keywords: agents,checkpoint,durable,graph,llm,resume,workflow
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: abstractsemantics>=0.0.2
+Provides-Extra: abstractcore
+Requires-Dist: abstractcore>=2.13.8; 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.8; extra == 'mcp-worker'
+Provides-Extra: multimodal
+Requires-Dist: abstractcore[audio,media,openai,vision,voice]>=2.13.8; extra == 'multimodal'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
 # AbstractRuntime
 
 **AbstractRuntime** is a durable workflow runtime (interrupt → checkpoint → resume) with an append-only execution ledger.
 
 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.1 (`pyproject.toml`) • **Python:** 3.10+
+**Version:** 0.4.4 • **Python:** 3.10+
+
+**Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
+
+## AbstractFramework ecosystem
+
+AbstractRuntime is one component of the wider [AbstractFramework](https://github.com/lpalbou/AbstractFramework) ecosystem:
+- **AbstractRuntime** (this repo) — durable workflow kernel (`src/abstractruntime/core/*`)
+- **AbstractCore** — LLM + tools integration (wired via `src/abstractruntime/integrations/abstractcore/*`)  
+  Repo: [lpalbou/abstractcore](https://github.com/lpalbou/abstractcore)
+
+At a high level, hosts define workflow graphs (`WorkflowSpec`) and AbstractRuntime executes them durably. When nodes request LLM/tool work (`EffectType.LLM_CALL`, `EffectType.TOOL_CALLS`), those effects are typically handled via AbstractCore.
+
+```mermaid
+flowchart LR
+  Host["Host app / orchestrator"] -->|"WorkflowSpec"| RT["AbstractRuntime"]
+  RT -->|"LLM_CALL / TOOL_CALLS"| AC["AbstractCore"]
+  AC -->|"results / waits"| RT
+```
 
 ## Install
 
@@ -20,6 +75,8 @@ AbstractCore integration (LLM + tools):
 pip install "abstractruntime[abstractcore]"
 ```
 
+The `abstractcore` extra installs AbstractCore 2.13.8 or newer so the hardened server auth model, provider-key header routing, prompt-cache control plane, current tool catalog, and unified multimodal generation response types are available. Use `abstractruntime[multimodal]` when you need common media, vision, voice, and audio dependencies.
+
 MCP worker entrypoint (default toolsets over stdio):
 
 ```bash
@@ -46,7 +103,9 @@ def ask(run, ctx):
 
 
 def done(run, ctx):
-    return StepPlan(node_id="done", complete_output={"answer": run.vars.get("user_answer")})
+    answer = run.vars.get("user_answer") or {}
+    text = answer.get("text") if isinstance(answer, dict) else None
+    return StepPlan(node_id="done", complete_output={"answer": text})
 
 
 wf = WorkflowSpec(workflow_id="demo", entry_node="ask", nodes={"ask": ask, "done": done})
@@ -65,7 +124,7 @@ state = rt.resume(
 assert state.status.value == "completed"
 ```
 
-## What’s included (v0.4.1)
+## What’s included (v0.4.4)
 
 Kernel (dependency-light):
 - workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
@@ -73,9 +132,11 @@ Kernel (dependency-light):
 - durable waits/events: `WAIT_EVENT`, `WAIT_UNTIL`, `ASK_USER`, `EMIT_EVENT`
 - append-only ledger (`StepRecord`) + node traces (`vars["_runtime"]["node_traces"]`)
 - retries/idempotency hooks: `src/abstractruntime/core/policy.py`
+- runtime-aware limits (`_limits`) with a default iteration budget of 50 (`docs/limits.md`)
 
 Durability + storage:
 - stores: in-memory, JSON/JSONL, SQLite (`src/abstractruntime/storage/*`)
+- durable command inbox primitives (idempotent, append-only): `CommandStore`, `CommandCursorStore` (`src/abstractruntime/storage/commands.py`, `src/abstractruntime/storage/sqlite.py`)
 - artifacts + offloading (store large payloads by reference)
 - snapshots/bookmarks (`docs/snapshots.md`)
 - tamper-evident hash-chained ledger (`docs/provenance.md`)
@@ -83,10 +144,11 @@ Durability + storage:
 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`)
 - run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
 
 Optional integrations:
-- AbstractCore (LLM + tools): `docs/integrations/abstractcore.md`
+- AbstractCore (LLM + tools, cached sessions/prompt cache, media inputs, generated media, tool approval waits): `docs/integrations/abstractcore.md`
 - comms toolset gating (email/WhatsApp/Telegram): `docs/tools-comms.md`
 
 ## Built-in scheduler (zero-config)
@@ -98,7 +160,7 @@ sr = create_scheduled_runtime()
 run_id, state = sr.run(my_workflow)
 
 if state.status.value == "waiting":
-    state = sr.respond(run_id, {"answer": "yes"})
+    state = sr.respond(run_id, {"text": "yes"})
 
 sr.stop()
 ```
@@ -143,7 +205,7 @@ sr = create_scheduled_runtime(
 python -m venv .venv
 source .venv/bin/activate
 python -m pip install -U pip
-python -m pip install -e ".[abstractcore,mcp-worker]"
+python -m pip install -e ".[abstractcore,mcp-worker,test,docs]"
 python -m pytest -q
 ```