AbstractRuntime 0.2.0__tar.gz → 0.4.1__tar.gz

abstractruntime-0.4.1/ACKNOWLEDGMENTS.md

@@ -0,0 +1,27 @@
+# Acknowledgments
+
+AbstractRuntime is designed to pair with the wider Abstract ecosystem and the open-source Python tooling community.
+
+This project depends on (and is shaped by) the following libraries.
+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).
+
+## 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`).
+  - 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`).
+- **RestrictedPython** (optional) — used for sandboxed execution of VisualFlow “Code” nodes when available (`src/abstractruntime/visualflow_compiler/visual/code_executor.py`).
+
+## Build & test tooling
+
+- **hatchling** — build backend (`pyproject.toml` `[build-system]`).
+- **pytest** — test runner (`pytest.ini`, `tests/`).
+
+And thanks to everyone who reports bugs, discusses design tradeoffs, and contributes improvements.
+
+See also: `LICENSE`, `CONTRIBUTING.md`.

abstractruntime-0.4.1/ACKNOWLEDMENTS.md

@@ -0,0 +1,4 @@
+# Acknowledments (legacy filename)
+
+This project uses `ACKNOWLEDGMENTS.md` (correct spelling). Please refer to that file.
+

abstractruntime-0.4.1/CHANGELOD.md

@@ -0,0 +1,4 @@
+# Changelog (legacy filename)
+
+This project uses `CHANGELOG.md`. Please refer to that file.
+

abstractruntime-0.4.1/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+All notable changes to AbstractRuntime will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+### Changed
+
+### Fixed
+
+## [0.4.1] - 2026-02-04
+
+### Added
+- **Durable prompt metadata for EVENT waits**:
+  - `WAIT_EVENT` effects may include optional `prompt`, `choices`, and `allow_free_text` fields.
+  - The runtime persists these fields onto `WaitState` so hosts (including remote/thin clients) can render a durable ask+wait UX without relying on in-process callbacks.
+- **Rendering utilities** (`abstractruntime.rendering`):
+  - `stringify_json(...)` + `JsonStringifyMode` to render JSON/JSON-ish values into strings with `none|beautify|minified` modes.
+  - `render_agent_trace_markdown(...)` to render runtime-owned `node_traces` scratchpads into a complete, review-friendly Markdown timeline.
+- **Documentation refresh**:
+  - clearer entrypoints: `README.md` → `docs/getting-started.md`
+  - new reference docs: `docs/api.md`, `docs/faq.md`, `docs/architecture.md`
+  - maintainer-facing orientation: `llms.txt`, `llms-full.txt`
+  - new repo policies: `CONTRIBUTING.md`, `SECURITY.md`, `ACKNOWLEDGMENTS.md`
+
+### Fixed
+- Normalize AbstractCore tool specs for skim tools so `paths` is always an array parameter (improves JSON schema consistency for tool callers).
+
+## [0.4.0] - 2025-01-06
+
+### Added
+
+- **Active Memory System** (`abstractruntime.memory.active_memory`): Complete MemAct agent memory module
+  - Runtime-owned `ACTIVE_MEMORY_DELTA` effect for structured Active Memory updates (used by agents via `active_memory_delta` tool)
+  - JSON-safe durable storage in `run.vars["_runtime"]["active_memory"]`
+  - Memory modules: MY PERSONA, RELATIONSHIPS, MEMORY BLUEPRINTS, CURRENT TASKS, CURRENT CONTEXT, CRITICAL INSIGHTS, REFERENCES, HISTORY
+  - Active Memory v9 format with natural-language markdown rendering (not YAML) to reduce syntax contamination
+  - All components render into system prompt by default (prevents user-role pollution on native-tool providers)
+
+- **MCP Worker** (`abstractruntime-mcp-worker`): Standalone stdio-based MCP server for AbstractRuntime tools
+  - Exposes AbstractRuntime's default toolsets as MCP tools via stdio transport
+  - Human-friendly logging to stderr with ANSI color support
+  - Security: allowlist-based command execution safety (`TOOL_WAIT` effect for dangerous commands)
+  - New optional dependency: `abstractruntime[mcp-worker]` (includes `abstractcore[tools]`)
+  - Entry point: `abstractruntime-mcp-worker` CLI script
+
+- **Evidence Capture System** (`abstractruntime.evidence.recorder`): Always-on provenance-first evidence recording
+  - Automatically records evidence for external-boundary tools: `web_search`, `fetch_url`, `execute_command`
+  - Evidence stored as artifact-backed records indexed as `kind="evidence"` in `RunState.vars["_runtime"]["memory_spans"]`
+  - Runtime helpers: `Runtime.list_evidence(run_id)` and `Runtime.load_evidence(evidence_id)`
+  - Keeps RunState JSON-safe by storing large payloads in ArtifactStore with refs
+
+- **Ledger Subscriptions**: Real-time step append events via `Runtime.subscribe_ledger()`
+  - `create_local_runtime`, `create_remote_runtime`, `create_hybrid_runtime` now wrap LedgerStore with `ObservableLedgerStore` by default
+  - Hosts can receive real-time notifications when steps are appended to ledger
+
+- **Durable Custom Events (Signals)**:
+  - `EMIT_EVENT` effect to dispatch events and resume matching `WAIT_EVENT` runs
+  - Extended `WAIT_EVENT` to accept `{scope, name}` payloads (runtime computes stable `wait_key`)
+  - `Scheduler.emit_event(...)` host API for external event delivery (session-scoped by default)
+
+- **Orchestrator-Owned Timeouts** (AbstractCore integration):
+  - Default **LLM timeout**: 7200s per `LLM_CALL` (not per-workflow), enforced by `create_*_runtime` factories
+  - Default **tool execution timeout**: 7200s per tool call (not per-workflow), enforced by ToolExecutor implementations
+
+- **Tool Executor Enhancements** (`MappingToolExecutor`):
+  - **Argument canonicalization**: Maps common parameter name variations (e.g., `file_path`/`filepath`/`path`) to canonical names
+  - **Filename aliases**: Supports `target_file`, `file_path`, `filepath`, `path` as aliases for file operations
+  - **Error output detection**: Detects structured error responses (`{"success": false, ...}`) from tools
+  - **Argument sanitization**: Cleans and validates tool call arguments
+  - **Timeout support**: Per-tool execution timeouts with configurable limits
+
+- **Memory Query Enhancements** (`MEMORY_QUERY` effect):
+  - Tag filters with **AND/OR** modes (`tags_mode=all|any`) and **multi-value** keys (`tags.person=["alice","bob"]`)
+  - Metadata filters for **authors** (`created_by`) and **locations** (`location`, `tags.location`)
+  - Span records now capture `created_by` for `conversation_span`, `active_memory_span`, `memory_note` when `actor_id` available
+  - `MEMORY_NOTE` accepts optional `location` field
+  - `MEMORY_NOTE` supports `keep_in_context=true` flag to immediately rehydrate stored note into `context.messages`
+
+- **Package Dependencies**:
+  - New optional dependency: `abstractruntime[abstractcore]` (enables `abstractruntime.integrations.abstractcore.*`)
+  - New optional dependency: `abstractruntime[mcp-worker]` (includes `abstractcore[tools]>=2.6.8`)
+
+### Changed
+
+- **LLM Client Enhancements**:
+  - Tool call parsing refactored for better robustness and error handling
+  - Streaming support with timing metrics (TTFT, generation time)
+  - Response normalization preserves JSON-safe `raw_response` for debugging
+  - Always attaches exact provider request payload under `result.metadata._provider_request` for every `LLM_CALL` step
+
+- **Runtime Core** (902 lines changed):
+  - Enhanced resume handling for paused/cancelled runs
+  - Improved subworkflow execution with async+wait support
+  - Better observable ledger integration
+
+### Fixed
+
+- **Cancellation is Terminal**: `Runtime.tick()` now treats `RunStatus.CANCELLED` as terminal and will not progress cancelled runs
+- **Control-Plane Safety**: `Runtime.tick()` stops without overwriting externally persisted pause/cancel state (used by AbstractFlow Web)
+- **Atomic Run Checkpoints**: `JsonFileRunStore.save()` writes via temp file + atomic rename to prevent partial/corrupt JSON under concurrent writes
+- **START_SUBWORKFLOW async+wait**: Support for `async=true` + `wait=true` to start child run without blocking parent tick, while keeping parent in durable SUBWORKFLOW wait
+- **ArtifactStore Run-Scoped Addressing**: Artifact IDs namespaced to run when `run_id` provided (prevents cross-run collisions, preserves purge-by-run semantics)
+- **AbstractCore Integration Imports**: `LocalAbstractCoreLLMClient` imports `create_llm` robustly in monorepo namespace-package layouts
+- **Token Limit Metadata**: `_limits.max_output_tokens` falls back to model capabilities when not configured (runtime surfaces explicit per-step output budget)
+- **Token-Cap Normalization Boundary**: Removed local `max_tokens → max_output_tokens` aliasing from AbstractRuntime's AbstractCore client (AbstractCore providers own this mapping)
+
+### Testing
+
+- **25 new/modified test files** covering:
+  - Active Memory functionality
+  - MCP worker (logging, security, stdio communication)
+  - Evidence recorder
+  - Memory query rich filters
+  - Tool executor (canonicalization, filename aliases, timeouts, error detection)
+  - LLM client tool call parsing
+  - Runtime configuration and subworkflow handling
+  - Packaging extras validation
+
+### Statistics
+
+- **33 commits** improving memory systems, MCP integration, evidence capture, and tool execution
+- **45 files changed**: 5,788 insertions, 286 deletions
+- **6,074 total lines changed** across the codebase
+- **3 new modules**: `active_memory.py`, `evidence/recorder.py`, `mcp_worker.py`
+
+## [0.2.0] - 2025-12-17
+
+### Added
+
+#### Core Runtime Features
+- **Durable Workflow Execution**: Start/tick/resume semantics for long-running workflows that survive process restarts
+- **WorkflowSpec**: Graph-based workflow definitions with node handlers keyed by ID
+- **RunState**: Durable state management (`current_node`, `vars`, `waiting`, `status`)
+- **Effect System**: Side-effect requests including `LLM_CALL`, `TOOL_CALLS`, `ASK_USER`, `WAIT_EVENT`, `WAIT_UNTIL`, `START_SUBWORKFLOW`
+- **StepPlan**: Node execution plans that define effects and state transitions
+- **Explicit Waiting States**: First-class support for pausing execution (`WaitReason`, `WaitState`)
+
+#### Scheduler & Automation
+- **Built-in Scheduler**: Zero-config background scheduler with polling thread for automatic run resumption
+- **WorkflowRegistry**: Mapping from workflow_id to WorkflowSpec for dynamic workflow resolution
+- **ScheduledRuntime**: High-level wrapper combining Runtime + Scheduler with simplified API
+- **create_scheduled_runtime()**: Factory function for zero-config scheduler creation
+- **Event Ingestion**: Support for external event delivery via `scheduler.resume_event()`
+- **Scheduler Stats**: Built-in statistics tracking and callback support
+
+#### Storage & Persistence
+- **Append-only Ledger**: Execution journal with `StepRecord` entries for audit/debug/provenance
+- **InMemoryRunStore**: In-memory run state storage for development and testing
+- **InMemoryLedgerStore**: In-memory ledger storage for development and testing
+- **JsonFileRunStore**: File-based persistent run state storage (one file per run)
+- **JsonlLedgerStore**: JSONL-based persistent ledger storage
+- **QueryableRunStore**: Interface for listing and filtering runs by status, workflow_id, actor_id, and time range
+- **Artifacts System**: Storage for large payloads (documents, images, tool outputs) to avoid bloating checkpoints
+  - `ArtifactStore` interface with in-memory and file-based implementations
+  - `ArtifactRef` type for referencing stored artifacts
+  - Helper functions: `artifact_ref()`, `is_artifact_ref()`, `get_artifact_id()`, `resolve_artifact()`, `compute_artifact_id()`
+
+#### Snapshots & Bookmarks
+- **Snapshot System**: Named, searchable checkpoints of run state for debugging and experimentation
+- **SnapshotStore**: Storage interface for snapshots with metadata (name, description, tags, timestamps)
+- **InMemorySnapshotStore**: In-memory snapshot storage for development
+- **JsonSnapshotStore**: File-based snapshot storage (one file per snapshot)
+- **Snapshot Search**: Filter by run_id, tag, or substring match in name/description
+
+#### Provenance & Accountability
+- **Hash-Chained Ledger**: Tamper-evident ledger with `prev_hash` and `record_hash` for each step
+- **HashChainedLedgerStore**: Decorator for adding hash chain verification to any ledger store
+- **verify_ledger_chain()**: Verification function that detects modifications or reordering of ledger records
+- **Actor Identity**: `ActorFingerprint` for attribution of workflow execution to specific actors
+- **actor_id tracking**: Support for actor_id in both RunState and StepRecord for accountability
+
+#### AbstractCore Integration
+- **LLM_CALL Effect Handler**: Execute LLM calls via AbstractCore providers
+- **TOOL_CALLS Effect Handler**: Execute tool calls with support for multiple execution modes
+- **Three Execution Modes**:
+  - **Local**: In-process AbstractCore providers with local tool execution
+  - **Remote**: HTTP to AbstractCore server (`/v1/chat/completions`) with tool passthrough
+  - **Hybrid**: Remote LLM calls with local tool execution
+- **Convenience Factories**: `create_local_runtime()`, `create_remote_runtime()`, `create_hybrid_runtime()`
+- **Tool Execution Modes**:
+  - Executed mode (trusted local) with results
+  - Passthrough mode (untrusted/server) with waiting semantics
+- **Layered Coupling**: AbstractCore integration as opt-in module to keep kernel dependency-light
+
+#### Effect Policies & Reliability
+- **EffectPolicy Protocol**: Configurable retry and idempotency policies for effects
+- **DefaultEffectPolicy**: Default implementation with no retries
+- **RetryPolicy**: Configurable retry behavior with max_attempts and backoff
+- **NoRetryPolicy**: Explicit no-retry policy
+- **compute_idempotency_key()**: Ledger-based deduplication to prevent duplicate side effects after crashes
+
+#### Examples & Documentation
+- **7 Runnable Examples**:
+  - `01_hello_world.py`: Minimal workflow demonstration
+  - `02_ask_user.py`: Pause/resume with user input
+  - `03_wait_until.py`: Scheduled resumption with time-based waiting
+  - `04_multi_step.py`: Branching workflow with conditional logic
+  - `05_persistence.py`: File-based storage demonstration
+  - `06_llm_integration.py`: AbstractCore LLM call integration
+  - `07_react_agent.py`: Full ReAct agent implementation with tools
+- **Comprehensive Documentation**:
+  - Architecture Decision Records (ADRs) for key design choices
+  - Integration guides for AbstractCore
+  - Detailed documentation for snapshots and provenance
+  - Limits and constraints documentation
+  - ROADMAP with prioritized next steps
+
+### Technical Details
+
+#### Architecture
+- **Layered Design**: Clear separation between kernel, storage, integrations, and identity
+- **Dependency-Light Kernel**: Core runtime remains stable with minimal dependencies
+- **Graph-Based Execution**: All workflows represented as state machines/graphs for visualization and composition
+- **JSON-Serializable State**: All run state and vars must be JSON-serializable for persistence
+
+#### Testing
+- Run the test suite with `python -m pytest -q` (see `docs/manual_testing.md`).
+
+#### Compatibility
+- **Python 3.10+**: Supports Python 3.10, 3.11, 3.12, and 3.13
+
+### Known Limitations
+
+- Snapshot restore does not guarantee safety if workflow spec or node code has changed
+- Subworkflow support (`START_SUBWORKFLOW`) is implemented but undergoing refinement
+- Cryptographic signatures (non-forgeability) not yet implemented - current hash chain provides tamper-evidence only
+- Remote tool worker service not yet implemented
+
+### Design Decisions
+
+- **Kernel stays dependency-light**: Enables portability, stability, and clear integration boundaries
+- **AbstractCore integration is opt-in**: Layered coupling prevents kernel breakage when AbstractCore changes
+- **Hash chain before signatures**: Provides immediate value without key management complexity
+- **Built-in scheduler (not external)**: Zero-config UX for simple cases
+- **Graph representation for all workflows**: Enables visualization, checkpointing, and composition
+
+### Notes
+
+AbstractRuntime is the durable execution substrate designed to pair with AbstractCore, AbstractAgent, and AbstractFlow. It enables workflows to interrupt, checkpoint, and resume across process restarts, making it suitable for long-running agent workflows that need to wait for user input, scheduled events, or external job completion.
+
+## [0.0.1] - Initial Development
+
+Initial development version with basic proof-of-concept features.
+
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.1...HEAD
+[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.1/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to AbstractRuntime
+
+Thanks for your interest in contributing!
+
+AbstractRuntime is a **durable workflow runtime** (interrupt → checkpoint → resume) with an append-only execution ledger.
+
+## Quick start (dev setup)
+
+Prereqs: **Python 3.10+**.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+
+# Full dev install (kernel + optional integrations used by tests/examples)
+python -m pip install -e ".[abstractcore,mcp-worker]"
+
+python -m pytest -q
+```
+
+## Repo map (source of truth)
+
+- Public exports: `src/abstractruntime/__init__.py` (keep this consistent with `docs/api.md`)
+- Core kernel (durable semantics): `src/abstractruntime/core/`
+- Durability backends: `src/abstractruntime/storage/`
+- Driver loop (in-process): `src/abstractruntime/scheduler/`
+- Optional integrations (extras): `src/abstractruntime/integrations/`
+- Tests: `tests/`
+
+Docs entrypoints:
+- `README.md` → `docs/getting-started.md`
+- Docs index: `docs/README.md`
+- Architecture: `docs/architecture.md`
+
+## Change guidelines
+
+### Code
+
+- Preserve durability invariants: values stored in `RunState.vars` must stay JSON-serializable (`src/abstractruntime/core/models.py`).
+- Add/adjust tests for new behavior (see `tests/`).
+- If you touch effect semantics, update `docs/architecture.md` and ensure handlers and models stay aligned.
+
+### Documentation
+
+Docs should be **user-facing**, **actionable**, and anchored to code (prefer referencing `src/...` paths for claims).
+
+When behavior changes, update:
+- `docs/api.md` (public API surface + imports)
+- `docs/getting-started.md` (onboarding examples)
+- `docs/architecture.md` (semantics/invariants)
+- `CHANGELOG.md` (user-visible changes)
+
+## Releases
+
+- Bump `version` in `pyproject.toml`
+- Add a dated section to `CHANGELOG.md` (Keep a Changelog format)
+

abstractruntime-0.4.1/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: AbstractRuntime
+Version: 0.4.1
+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
+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.1
+Provides-Extra: abstractcore
+Requires-Dist: abstractcore>=2.6.8; extra == 'abstractcore'
+Provides-Extra: mcp-worker
+Requires-Dist: abstractcore[tools]>=2.6.8; extra == 'mcp-worker'
+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+
+
+## Install
+
+Core runtime:
+
+```bash
+pip install abstractruntime
+```
+
+AbstractCore integration (LLM + tools):
+
+```bash
+pip install "abstractruntime[abstractcore]"
+```
+
+MCP worker entrypoint (default toolsets over stdio):
+
+```bash
+pip install "abstractruntime[mcp-worker]"
+```
+
+## Quick start (pause + resume)
+
+```python
+from abstractruntime import Effect, EffectType, Runtime, StepPlan, WorkflowSpec
+from abstractruntime.storage import InMemoryLedgerStore, InMemoryRunStore
+
+
+def ask(run, ctx):
+    return StepPlan(
+        node_id="ask",
+        effect=Effect(
+            type=EffectType.ASK_USER,
+            payload={"prompt": "Continue?"},
+            result_key="user_answer",
+        ),
+        next_node="done",
+    )
+
+
+def done(run, ctx):
+    return StepPlan(node_id="done", complete_output={"answer": run.vars.get("user_answer")})
+
+
+wf = WorkflowSpec(workflow_id="demo", entry_node="ask", nodes={"ask": ask, "done": done})
+rt = Runtime(run_store=InMemoryRunStore(), ledger_store=InMemoryLedgerStore())
+
+run_id = rt.start(workflow=wf)
+state = rt.tick(workflow=wf, run_id=run_id)
+assert state.status.value == "waiting"
+
+state = rt.resume(
+    workflow=wf,
+    run_id=run_id,
+    wait_key=state.waiting.wait_key,
+    payload={"text": "yes"},
+)
+assert state.status.value == "completed"
+```
+
+## What’s included (v0.4.1)
+
+Kernel (dependency-light):
+- workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
+- durable execution: `Runtime.start/tick/resume` (`src/abstractruntime/core/runtime.py`)
+- 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`
+
+Durability + storage:
+- stores: in-memory, JSON/JSONL, SQLite (`src/abstractruntime/storage/*`)
+- artifacts + offloading (store large payloads by reference)
+- snapshots/bookmarks (`docs/snapshots.md`)
+- tamper-evident hash-chained ledger (`docs/provenance.md`)
+
+Drivers + distribution:
+- scheduler: `create_scheduled_runtime()` (`src/abstractruntime/scheduler/*`)
+- VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
+- run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
+
+Optional integrations:
+- AbstractCore (LLM + tools): `docs/integrations/abstractcore.md`
+- comms toolset gating (email/WhatsApp/Telegram): `docs/tools-comms.md`
+
+## Built-in scheduler (zero-config)
+
+```python
+from abstractruntime import create_scheduled_runtime
+
+sr = create_scheduled_runtime()
+run_id, state = sr.run(my_workflow)
+
+if state.status.value == "waiting":
+    state = sr.respond(run_id, {"answer": "yes"})
+
+sr.stop()
+```
+
+For persistent storage:
+
+```python
+from abstractruntime import create_scheduled_runtime, JsonFileRunStore, JsonlLedgerStore
+
+sr = create_scheduled_runtime(
+    run_store=JsonFileRunStore("./data"),
+    ledger_store=JsonlLedgerStore("./data"),
+)
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](docs/getting-started.md) | Install + first durable workflow |
+| [API Reference](docs/api.md) | Public API surface (imports + pointers) |
+| [Docs Index](docs/README.md) | Full docs map (guides + reference) |
+| [FAQ](docs/faq.md) | Common questions and gotchas |
+| [Architecture](docs/architecture.md) | Component map + diagrams |
+| [Overview](docs/proposal.md) | Design goals, core concepts, and scope |
+| [Integrations](docs/integrations/) | Integration guides (AbstractCore) |
+| [Snapshots](docs/snapshots.md) | Named checkpoints for run state |
+| [Provenance](docs/provenance.md) | Tamper-evident ledger documentation |
+| [Evidence](docs/evidence.md) | Artifact-backed evidence capture for web/command tools |
+| [Limits](docs/limits.md) | `_limits` namespace and RuntimeConfig |
+| [WorkflowBundles](docs/workflow-bundles.md) | `.flow` bundle format (VisualFlow distribution) |
+| [MCP Worker](docs/mcp-worker.md) | `abstractruntime-mcp-worker` CLI |
+| [Changelog](CHANGELOG.md) | Release notes |
+| [Contributing](CONTRIBUTING.md) | How to build/test and submit changes |
+| [Security](SECURITY.md) | Responsible vulnerability reporting |
+| [Acknowledgments](ACKNOWLEDGMENTS.md) | Credits |
+| [ROADMAP](ROADMAP.md) | Prioritized next steps |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[abstractcore,mcp-worker]"
+python -m pytest -q
+```
+
+See `CONTRIBUTING.md` for contribution guidelines and doc conventions.

abstractruntime-0.4.1/README.md

@@ -0,0 +1,150 @@
+# 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+
+
+## Install
+
+Core runtime:
+
+```bash
+pip install abstractruntime
+```
+
+AbstractCore integration (LLM + tools):
+
+```bash
+pip install "abstractruntime[abstractcore]"
+```
+
+MCP worker entrypoint (default toolsets over stdio):
+
+```bash
+pip install "abstractruntime[mcp-worker]"
+```
+
+## Quick start (pause + resume)
+
+```python
+from abstractruntime import Effect, EffectType, Runtime, StepPlan, WorkflowSpec
+from abstractruntime.storage import InMemoryLedgerStore, InMemoryRunStore
+
+
+def ask(run, ctx):
+    return StepPlan(
+        node_id="ask",
+        effect=Effect(
+            type=EffectType.ASK_USER,
+            payload={"prompt": "Continue?"},
+            result_key="user_answer",
+        ),
+        next_node="done",
+    )
+
+
+def done(run, ctx):
+    return StepPlan(node_id="done", complete_output={"answer": run.vars.get("user_answer")})
+
+
+wf = WorkflowSpec(workflow_id="demo", entry_node="ask", nodes={"ask": ask, "done": done})
+rt = Runtime(run_store=InMemoryRunStore(), ledger_store=InMemoryLedgerStore())
+
+run_id = rt.start(workflow=wf)
+state = rt.tick(workflow=wf, run_id=run_id)
+assert state.status.value == "waiting"
+
+state = rt.resume(
+    workflow=wf,
+    run_id=run_id,
+    wait_key=state.waiting.wait_key,
+    payload={"text": "yes"},
+)
+assert state.status.value == "completed"
+```
+
+## What’s included (v0.4.1)
+
+Kernel (dependency-light):
+- workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
+- durable execution: `Runtime.start/tick/resume` (`src/abstractruntime/core/runtime.py`)
+- 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`
+
+Durability + storage:
+- stores: in-memory, JSON/JSONL, SQLite (`src/abstractruntime/storage/*`)
+- artifacts + offloading (store large payloads by reference)
+- snapshots/bookmarks (`docs/snapshots.md`)
+- tamper-evident hash-chained ledger (`docs/provenance.md`)
+
+Drivers + distribution:
+- scheduler: `create_scheduled_runtime()` (`src/abstractruntime/scheduler/*`)
+- VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
+- run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
+
+Optional integrations:
+- AbstractCore (LLM + tools): `docs/integrations/abstractcore.md`
+- comms toolset gating (email/WhatsApp/Telegram): `docs/tools-comms.md`
+
+## Built-in scheduler (zero-config)
+
+```python
+from abstractruntime import create_scheduled_runtime
+
+sr = create_scheduled_runtime()
+run_id, state = sr.run(my_workflow)
+
+if state.status.value == "waiting":
+    state = sr.respond(run_id, {"answer": "yes"})
+
+sr.stop()
+```
+
+For persistent storage:
+
+```python
+from abstractruntime import create_scheduled_runtime, JsonFileRunStore, JsonlLedgerStore
+
+sr = create_scheduled_runtime(
+    run_store=JsonFileRunStore("./data"),
+    ledger_store=JsonlLedgerStore("./data"),
+)
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](docs/getting-started.md) | Install + first durable workflow |
+| [API Reference](docs/api.md) | Public API surface (imports + pointers) |
+| [Docs Index](docs/README.md) | Full docs map (guides + reference) |
+| [FAQ](docs/faq.md) | Common questions and gotchas |
+| [Architecture](docs/architecture.md) | Component map + diagrams |
+| [Overview](docs/proposal.md) | Design goals, core concepts, and scope |
+| [Integrations](docs/integrations/) | Integration guides (AbstractCore) |
+| [Snapshots](docs/snapshots.md) | Named checkpoints for run state |
+| [Provenance](docs/provenance.md) | Tamper-evident ledger documentation |
+| [Evidence](docs/evidence.md) | Artifact-backed evidence capture for web/command tools |
+| [Limits](docs/limits.md) | `_limits` namespace and RuntimeConfig |
+| [WorkflowBundles](docs/workflow-bundles.md) | `.flow` bundle format (VisualFlow distribution) |
+| [MCP Worker](docs/mcp-worker.md) | `abstractruntime-mcp-worker` CLI |
+| [Changelog](CHANGELOG.md) | Release notes |
+| [Contributing](CONTRIBUTING.md) | How to build/test and submit changes |
+| [Security](SECURITY.md) | Responsible vulnerability reporting |
+| [Acknowledgments](ACKNOWLEDGMENTS.md) | Credits |
+| [ROADMAP](ROADMAP.md) | Prioritized next steps |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[abstractcore,mcp-worker]"
+python -m pytest -q
+```
+
+See `CONTRIBUTING.md` for contribution guidelines and doc conventions.