AbstractRuntime 0.0.1__tar.gz → 0.4.0__tar.gz

abstractruntime-0.4.0/CHANGELOG.md

@@ -0,0 +1,240 @@
+# 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
+- **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 (tool args + results untruncated).
+
+## [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
+
+#### Test Coverage
+- **81% Overall Coverage**: Comprehensive test suite with 57+ tests
+- **Integration Tests**: Tests for AbstractCore integration, subworkflows, trace propagation
+- **Core Tests**: Scheduler, snapshots, artifacts, pause/resume, retry/idempotency, ledger chain
+- **Storage Tests**: Queryable run store, durable toolsets
+
+#### Compatibility
+- **Python 3.10+**: Supports Python 3.10, 3.11, 3.12, and 3.13
+- **Development Status**: Planning/Alpha (moving toward Beta with 0.2.0)
+
+### 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.
+
+[0.2.0]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.2.0
+[0.0.1]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.0.1

{abstractruntime-0.0.1 → abstractruntime-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.0.1
+Version: 0.4.0
 Summary: AbstractRuntime: a durable graph runner designed to pair with AbstractCore.
 Project-URL: AbstractCore (website), https://www.abstractcore.ai/
 Project-URL: AbstractCore (GitHub), https://github.com/lpalbou/abstractruntime
@@ -18,6 +18,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
+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-0.0.1 → abstractruntime-0.4.0}/ROADMAP.md

@@ -90,19 +90,20 @@ sr.stop()
 
 ---
 
-### 2.2 Examples and Documentation
+### 2.2 Examples and Documentation ✅ COMPLETE
 **Priority: High** | **Effort: Low** | **Backlog: 010**
 
-**Why**: The MVP is functional but lacks concrete examples. Developers cannot understand how to build workflows without reading source code.
-
-**Deliverables**:
-- `examples/` directory with runnable workflows
-- ask_user interrupt example (pause for days, resume)
-- wait_until timer example
-- LLM call + tool execution example
-- Subworkflow composition example
+**What shipped**:
+- `examples/` directory with 7 runnable examples
+- 01_hello_world.py - Minimal workflow
+- 02_ask_user.py - Pause/resume with user input
+- 03_wait_until.py - Scheduled resumption
+- 04_multi_step.py - Branching workflow
+- 05_persistence.py - File-based storage
+- 06_llm_integration.py - AbstractCore LLM call
+- 07_react_agent.py - Full ReAct agent with tools
 
-**Success criteria**: A developer can copy an example and have a working workflow in 5 minutes.
+**Success criteria**: A developer can copy an example and have a working workflow in 5 minutes. ✅
 
 ---
 
@@ -227,8 +228,8 @@ AbstractCore (LLM calls, tool execution, server API)
 | 4.2 | Remote Worker | 3-4 days |
 
 **Phase 1 (Core Completeness)**: ✅ Complete
-**Phase 2 (Composition)**: ~3-5 days
+**Phase 2 (Composition)**: ✅ Examples complete, Subworkflow complete
 **Phase 3 (Production Readiness)**: ~1 week  
 **Phase 4 (Advanced Features)**: ~2 weeks
 
-Remaining: ~3-4 weeks for full roadmap.
+Remaining: ~2-3 weeks for full roadmap.

abstractruntime-0.4.0/docs/architecture.md

@@ -0,0 +1,165 @@
+# AbstractRuntime — Architecture (Current)
+
+> Updated: 2026-01-07  
+> Scope: this describes **what is implemented today** in this monorepo.
+
+AbstractRuntime is the **durable execution kernel** of the AbstractFramework. It runs workflow graphs as a persisted state machine:
+- **tick** a run forward until it completes or blocks
+- persist **checkpoints** (RunState) + an append-only **ledger** (StepRecord)
+- represent blocking as durable **WaitState** (USER / EVENT / UNTIL / SUBWORKFLOW)
+- resume with an external payload (human input, event envelope, job completion)
+
+AbstractRuntime is intentionally dependency-light in the core (`abstractruntime/core/*`):
+- higher-level integrations (LLM providers, tool execution, event bus bridging) live in `abstractruntime/integrations/*`
+
+## High-level runtime loop (data flow)
+
+```
+WorkflowSpec (in-memory handlers)
+   │
+   ▼
+Runtime.tick(run_id)
+   │ loads + updates
+   ▼
+RunStore  (checkpoint RunState.vars + waiting)
+   │ append
+   ▼
+LedgerStore (StepRecords: started/completed/waiting/failed)
+   │ large payloads
+   ▼
+ArtifactStore (JSON blobs referenced from vars/ledger)
+```
+
+## Core Types (Durable, JSON-Safe)
+
+Defined in `abstractruntime/src/abstractruntime/core/models.py`:
+
+- `WorkflowSpec`
+  - `workflow_id`, `entry_node`, `nodes: Dict[node_id, handler]`
+- `RunState`
+  - `run_id`, `workflow_id`, `status`, `current_node`
+  - `vars` (**JSON-safe** dictionary, persisted by RunStore)
+  - `waiting: WaitState | None`
+  - `output` / `error`
+  - optional provenance: `actor_id`, `session_id`, `parent_run_id`
+- `StepPlan`
+  - returned by node handlers: `{effect?, next_node?, complete_output?}`
+- `Effect` + `EffectType`
+  - requests for side effects / waits (LLM_CALL, TOOL_CALLS, ASK_USER, WAIT_EVENT, …)
+- `WaitState` + `WaitReason`
+  - durable blocking representation
+- `StepRecord`
+  - append-only audit log entries (STARTED/COMPLETED/WAITING/FAILED)
+
+## Runtime Semantics (start / tick / resume)
+
+Implemented in `abstractruntime/src/abstractruntime/core/runtime.py`:
+
+- `Runtime.start(workflow, vars, actor_id?, session_id?, parent_run_id?) -> run_id`
+  - creates a `RunState` checkpoint (RUNNING, current_node=entry)
+- `Runtime.tick(workflow, run_id, max_steps=...) -> RunState`
+  - executes node handlers in a loop:
+    - handler returns `StepPlan`
+    - if `StepPlan.effect` exists → dispatch to the effect handler registry
+    - if effect outcome blocks → persist `RunState.waiting` and return WAITING
+    - if `next_node` exists → advance cursor and continue
+    - if `complete_output` exists → set run output and finish
+- `Runtime.resume(workflow, run_id, wait_key, payload, max_steps=...) -> RunState`
+  - validates the run is waiting for `wait_key`
+  - writes `payload` to the waiting node’s `result_key`
+  - clears `waiting`, transitions to RUNNING, continues via `tick`
+
+### Run Control (pause/resume/cancel)
+Run control is runtime-owned (also in `abstractruntime/core/runtime.py`):
+- pause uses a synthetic WAIT_USER (`wait_key = pause:<run_id>`) and a durable flag in `vars["_runtime"]["control"]["paused"]`
+- resume clears the pause wait and continues ticking
+- cancel marks the run CANCELLED (and can cancel subflows via host orchestration)
+
+## Persistence Layer (RunStore / LedgerStore / ArtifactStore)
+
+Storage interfaces are defined in `abstractruntime/src/abstractruntime/storage/base.py` and implemented in:
+- `abstractruntime/src/abstractruntime/storage/in_memory.py` (in-memory stores)
+- `abstractruntime/src/abstractruntime/storage/json_files.py` (file-based stores)
+  - `JsonFileRunStore`: `run_<run_id>.json`
+  - `JsonlLedgerStore`: `ledger_<run_id>.jsonl`
+- `abstractruntime/src/abstractruntime/storage/artifacts.py`
+  - `ArtifactStore` + `FileArtifactStore` + helpers (`artifact_ref`, `resolve_artifact`, …)
+- `abstractruntime/src/abstractruntime/storage/observable.py`
+  - `ObservableLedgerStore` adds subscriptions for live UI streaming
+
+**Key invariant:** `RunState.vars` must remain JSON-safe. Large payloads should be stored in `ArtifactStore` and referenced.
+
+## Effect System (Handlers)
+
+The runtime executes side effects by dispatching `EffectType` to handler callables. The core runtime ships with the effect protocol; hosts wire concrete handlers.
+
+### Memory effects (runtime-owned, durable)
+The runtime ships a small, provenance-first memory surface (no embeddings):
+- `EffectType.MEMORY_COMPACT`: archive older `context.messages` into an artifact + insert a summary handle
+- `EffectType.MEMORY_NOTE`: store a durable note with tags + sources
+  - supports `payload.scope = run|session|global` (scope is routing: it selects the index-owner run)
+- `EffectType.MEMORY_QUERY`: recall spans/notes by id/tags/time/query
+  - supports `payload.scope = run|session|global|all`
+  - supports `payload.return = rendered|meta|both` (meta enables deterministic workflows without parsing text)
+- `EffectType.MEMORY_TAG`: apply/merge tags onto existing span index entries
+- `EffectType.MEMORY_REHYDRATE`: rehydrate archived `conversation_span` artifacts into `context.messages` deterministically (deduped)
+
+Global scope uses a stable run id (default `global_memory`, override via `ABSTRACTRUNTIME_GLOBAL_MEMORY_RUN_ID`, validated as filesystem-safe).
+
+### AbstractCore Integration (LLM + Tools)
+`abstractruntime/src/abstractruntime/integrations/abstractcore/*` provides:
+- an AbstractCore-backed LLM client (`llm_client.py`)
+- tool execution boundary (`tool_executor.py`)
+  - `MappingToolExecutor` (recommended)
+  - `AbstractCoreToolExecutor` (legacy adapter path)
+  - `PassthroughToolExecutor` (host executes tools externally)
+- effect handler wiring (`effect_handlers.py`)
+- convenience factories (`factory.py`)
+  - `create_local_runtime(...)` (local execution)
+  - `create_remote_runtime(...)` (passthrough tools / host-mediated)
+
+This keeps the kernel independent of AbstractCore while enabling LLM/tool workflows when a host opts in.
+
+## Observability (Ledger + Runtime-Owned Node Traces)
+
+### Ledger (Source of Truth)
+Every node transition produces `StepRecord` entries appended to the `LedgerStore`.
+When using `ObservableLedgerStore`, hosts can subscribe to appends for real-time UI updates.
+
+### Runtime-Owned Node Traces
+In addition to the ledger, the runtime stores bounded, JSON-safe per-node traces under:
+`run.vars["_runtime"]["node_traces"]` (see `abstractruntime/src/abstractruntime/core/runtime.py:_record_node_trace` and helpers in `abstractruntime/src/abstractruntime/core/vars.py`).
+
+These traces support host UX needs (scratchpad/trace views) without inventing host-specific persistence formats.
+
+### Optional Event Bus Bridge
+`abstractruntime.integrations.abstractcore.observability` can bridge ledger events to `abstractcore.events.GlobalEventBus` when desired.
+
+## Scheduling (Time-Based Waits)
+
+Time-based waits (`WAIT_UNTIL`) are durable. To advance them, a host needs to tick due runs. AbstractRuntime provides:
+- `create_scheduled_runtime(...)` and a `Scheduler` (`abstractruntime/src/abstractruntime/scheduler/*`)
+
+Hosts can run a scheduler loop to periodically:
+- query due `WAIT_UNTIL` runs (requires a queryable run store)
+- tick them forward
+
+## Eventing (WAIT_EVENT / EMIT_EVENT)
+
+Custom eventing is implemented as:
+- listeners block on `WAIT_EVENT` (`WaitReason.EVENT`)
+- emitters request `EffectType.EMIT_EVENT`, handled by the runtime (`Runtime._handle_emit_event`) which resumes matching `WAIT_EVENT` runs via `Runtime.resume(...)`
+  - requires a `QueryableRunStore` to find waiting runs and a `workflow_registry` to load target `WorkflowSpec`s
+
+Notes:
+- The emitted event **payload is normalized to a dict** for network-safe stability. If a non-dict is provided, it is wrapped as `{ "value": <payload> }`.
+- `WAIT_EVENT` waits can optionally include UX metadata (`prompt`, `choices`, `allow_free_text`) so hosts can render interactive prompts while remaining fully durable.
+
+For **host-driven external signals**, use the scheduler API:
+- `Scheduler.emit_event(...)` (finds waiting runs and resumes them)
+
+Event envelopes (scope/session/workflow) are encoded via stable wait keys (see `abstractruntime/src/abstractruntime/core/event_keys.py`).
+
+## Deviations / near-term work
+- **Client-agnostic run history contract**: today, some hosts implement bespoke “ledger → UI events” replay logic. A runtime-owned, versioned `RunHistoryBundle` contract (planned: backlog 311) should become the shared format so any client can render consistent history and achieve stronger reproducibility.
+

abstractruntime-0.4.0/docs/backlog/completed/010_examples_and_composition.md

@@ -0,0 +1,59 @@
+## 010_examples_and_composition (COMPLETED 2025-12-13)
+
+### Goal
+Provide concrete, runnable examples demonstrating the simplified API:
+- Zero-config setup with `create_scheduled_runtime()`
+- `run()` and `respond()` for simple workflows
+- `ask_user` interrupt (pause for user input)
+- `wait_until` (scheduled resumption)
+- Tool passthrough (for AbstractCore integration)
+- Workflow-as-node composition (after 011 is complete)
+
+### Deliverables
+- `examples/` directory with runnable Python scripts
+- Each example should be self-contained and copy-pasteable
+
+### Proposed Examples
+
+1. **01_hello_world.py** — Minimal workflow with zero-config
+2. **02_ask_user.py** — Pause for user input, resume with response
+3. **03_wait_until.py** — Schedule a task for later
+4. **04_multi_step.py** — Multi-node workflow with branching
+5. **05_persistence.py** — File-based storage, survive restart
+6. **06_llm_integration.py** — AbstractCore LLM call (requires abstractcore)
+7. **07_react_agent.py** — Full ReAct agent with tools (requires abstractcore + abstractagent)
+
+### Acceptance criteria
+- A developer can copy an example and have it running in < 5 minutes
+- Examples use the simplified API (`run()`, `respond()`)
+- Each example has clear comments explaining what's happening
+- Examples 1-5 work without external dependencies
+- Examples 6-7 require abstractcore/abstractagent but are clearly documented
+
+### Priority
+**HIGH** - This is the most impactful improvement for adoption. Without examples, developers cannot understand how to use the library.
+
+---
+
+## Completion Notes
+
+**Completed:** 2025-12-13
+
+**Deliverables:**
+- Created `examples/` directory with 7 runnable examples
+- All examples tested and working
+
+**Examples implemented:**
+1. `01_hello_world.py` - Minimal workflow with zero-config ✅
+2. `02_ask_user.py` - Pause for user input, resume with response ✅
+3. `03_wait_until.py` - Schedule a task for later ✅
+4. `04_multi_step.py` - Multi-node workflow with branching ✅
+5. `05_persistence.py` - File-based storage, survive restart ✅
+6. `06_llm_integration.py` - AbstractCore LLM call ✅
+7. `07_react_agent.py` - Full ReAct agent with tools ✅
+
+**Additional improvements made:**
+- AbstractAgent now uses TOOL_CALLS effect for ledger recording
+- Created RegistryToolExecutor for agent-specific tool execution
+- Added observe_node to ReAct workflow for proper effect-based architecture
+