AbstractRuntime 0.0.1__tar.gz → 0.2.0__tar.gz

abstractruntime-0.2.0/CHANGELOG.md

@@ -0,0 +1,132 @@
+# 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).
+
+## [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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AbstractRuntime
-Version: 0.0.1
+Version: 0.2.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

{abstractruntime-0.0.1 → abstractruntime-0.2.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.2.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
+

abstractruntime-0.2.0/docs/backlog/completed/016_runtime_aware_parameters.md

@@ -0,0 +1,240 @@
+## 016_runtime_aware_parameters (completed)
+
+**Status**: Completed
+**Completed**: 2025-12-16
+
+---
+
+## Final Report
+
+### What Was Implemented
+
+Refactored AbstractRuntime to be aware of runtime parameters (max_iterations, max_tokens, max_history_messages) with a canonical `_limits` namespace in RunState.vars.
+
+**Approach**: Hybrid enforcement (runtime provides info/warnings, workflow nodes enforce)
+**Rollout**: Phased migration (3 phases)
+
+| Component | Description |
+|-----------|-------------|
+| `RuntimeConfig` | Frozen dataclass for runtime limits and model capabilities |
+| `LimitWarning` | Dataclass for limit warnings (warning/exceeded) |
+| `LIMITS` constant | `"_limits"` namespace constant in vars.py |
+| `ensure_limits()` | Helper to create/get `_limits` namespace with defaults |
+| `Runtime.config` | Property to access RuntimeConfig |
+| `Runtime.get_limit_status()` | Get structured limit status for a run |
+| `Runtime.check_limits()` | Check if limits approaching/exceeded, returns warnings |
+| `Runtime.update_limits()` | Update limits mid-session |
+| `Agent.get_limit_status()` | Agent-level delegate to runtime |
+| `Agent.update_limits()` | Agent-level delegate to runtime |
+
+### Key Features
+
+1. **Canonical `_limits` Namespace**: Single source of truth in RunState.vars
+   ```python
+   run.vars["_limits"] = {
+       "max_iterations": 25,
+       "current_iteration": 0,
+       "max_tokens": 32768,
+       "max_history_messages": -1,
+       "estimated_tokens_used": 0,
+       "warn_iterations_pct": 80,
+       "warn_tokens_pct": 80,
+   }
+   ```
+
+2. **Hybrid Enforcement Model**:
+   - Runtime provides limit info and warnings
+   - Workflow nodes enforce (check and transition)
+   - Clear separation of concerns
+
+3. **Model Capabilities Integration**:
+   - Factory queries LLM client for model capabilities
+   - Capabilities flow through RuntimeConfig to `_limits`
+   - max_tokens defaults to model's context window
+
+4. **Backward Compatibility**:
+   - Falls back to scratchpad if `_limits` missing
+   - All new parameters have sensible defaults
+   - No breaking changes to existing APIs
+
+### Files Added
+
+| File | Description |
+|------|-------------|
+| `src/abstractruntime/core/config.py` | RuntimeConfig dataclass with to_limits_dict() and with_capabilities() |
+
+### Files Modified
+
+| File | Changes |
+|------|---------|
+| `abstractruntime/core/vars.py` | Added LIMITS constant, ensure_limits(), get_limits() |
+| `abstractruntime/core/models.py` | Added LimitWarning dataclass |
+| `abstractruntime/core/runtime.py` | Added config property and 3 limit methods |
+| `abstractruntime/core/__init__.py` | Exported new classes and functions |
+| `abstractruntime/integrations/abstractcore/factory.py` | Config parameter, model capabilities |
+| `abstractruntime/integrations/abstractcore/__init__.py` | Exported RuntimeConfig |
+| `abstractagent/adapters/react_runtime.py` | Uses _limits namespace |
+| `abstractagent/adapters/codeact_runtime.py` | Uses _limits namespace |
+| `abstractagent/agents/react.py` | Added get_limit_status(), update_limits() |
+| `abstractagent/agents/codeact.py` | Added get_limit_status(), update_limits() |
+| `abstractagent/logic/react.py` | build_request() accepts vars parameter |
+| `abstractagent/logic/codeact.py` | build_request() accepts vars parameter |
+| `abstractflow/adapters/agent_adapter.py` | Populates _limits namespace |
+
+### Test Coverage
+
+| Test Suite | Result |
+|------------|--------|
+| Phase 1: RuntimeConfig tests | PASS |
+| Phase 1: vars.py tests | PASS |
+| Phase 1: LimitWarning tests | PASS |
+| Phase 1: Runtime limit methods | PASS |
+| Phase 1: Exports tests | PASS |
+| Phase 2: Factory exports | PASS |
+| Phase 3: react_runtime | PASS |
+| Phase 3: codeact_runtime | PASS |
+| Phase 3: Logic classes | PASS |
+| Backward compatibility | PASS |
+| AbstractRuntime unit tests | 147 passed |
+| AbstractAgent unit tests | 5 passed |
+
+### Usage Examples
+
+#### Basic Usage
+```python
+from abstractruntime.core import RuntimeConfig
+
+# Create runtime with custom limits
+config = RuntimeConfig(
+    max_iterations=50,
+    max_tokens=65536,
+    max_history_messages=100,
+    warn_iterations_pct=75,
+)
+
+runtime = create_local_runtime(
+    provider="ollama",
+    model="qwen3:4b",
+    config=config,
+)
+```
+
+#### Checking Limit Status
+```python
+# Get limit status mid-run
+status = runtime.get_limit_status(run_id)
+print(f"Iterations: {status['iterations']['current']}/{status['iterations']['max']}")
+# Output: Iterations: 5/50
+
+if status['iterations']['warning']:
+    print("Approaching iteration limit!")
+```
+
+#### Updating Limits Dynamically
+```python
+# Update limits mid-session (e.g., from /max-tokens command)
+runtime.update_limits(run_id, {"max_tokens": 131072})
+```
+
+#### Agent-Level Access
+```python
+agent = ReactAgent(runtime=runtime, max_iterations=25)
+run_id = agent.start("Solve this problem")
+
+# Check status through agent
+status = agent.get_limit_status()
+
+# Update limits through agent
+agent.update_limits(max_tokens=65536)
+```
+
+### Architecture
+
+```
+                    ┌─────────────────────────────────────┐
+                    │           RuntimeConfig             │
+                    │  (frozen dataclass with defaults)   │
+                    └─────────────────┬───────────────────┘
+                                      │
+                    ┌─────────────────▼───────────────────┐
+                    │              Runtime                 │
+                    │  - config property                   │
+                    │  - start() initializes _limits       │
+                    │  - get_limit_status()                │
+                    │  - check_limits() → LimitWarning[]   │
+                    │  - update_limits()                   │
+                    └─────────────────┬───────────────────┘
+                                      │
+                    ┌─────────────────▼───────────────────┐
+                    │         RunState.vars               │
+                    │  {                                   │
+                    │    "_limits": {                      │
+                    │      "max_iterations": 25,           │
+                    │      "current_iteration": 0,         │
+                    │      "max_tokens": 32768,            │
+                    │      ...                             │
+                    │    }                                 │
+                    │  }                                   │
+                    └─────────────────┬───────────────────┘
+                                      │
+         ┌────────────────────────────┼────────────────────────────┐
+         │                            │                            │
+         ▼                            ▼                            ▼
+┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
+│  react_runtime  │         │ codeact_runtime │         │  agent_adapter  │
+│  (reads _limits,│         │  (reads _limits,│         │  (populates     │
+│   enforces)     │         │   enforces)     │         │   _limits)      │
+└─────────────────┘         └─────────────────┘         └─────────────────┘
+```
+
+---
+
+## Original Proposal
+
+### Goal
+Make AbstractRuntime aware of runtime parameters (max_iterations, max_tokens, max_history_messages) with:
+- Canonical storage in RunState.vars
+- Runtime-level introspection and control
+- Mid-session updates capability
+
+### Context / Problem
+Parameters were scattered with no single source of truth:
+
+| Parameter | Location | Problem |
+|-----------|----------|---------|
+| `max_iterations` | `scratchpad` | Only in one place, but not runtime-managed |
+| `max_tokens` | `Logic._max_tokens` | Lost on resume, not in RunState |
+| `max_history_messages` | `Logic._max_history_messages` | Lost on resume, not in RunState |
+
+The Runtime class had **zero awareness** of these limits.
+
+### Non-goals
+- No automatic enforcement by runtime (nodes enforce)
+- No observability events in this phase (future work)
+- No token counting (estimated_tokens_used is placeholder)
+
+---
+
+### Proposed Design
+
+1. **New `_limits` namespace** in RunState.vars as canonical storage
+2. **RuntimeConfig dataclass** for configuration and defaults
+3. **Runtime enhancements**: config property, limit methods
+4. **Hybrid enforcement**: runtime provides info, nodes enforce
+5. **Phased migration**: backward compatibility with scratchpad
+
+---
+
+### Acceptance Criteria
+
+- [x] RuntimeConfig with to_limits_dict() method
+- [x] Runtime accepts config parameter
+- [x] Runtime.start() initializes _limits from config
+- [x] Runtime.get_limit_status() returns structured status
+- [x] Runtime.check_limits() returns LimitWarning list
+- [x] Runtime.update_limits() persists changes
+- [x] Adapters read from _limits with scratchpad fallback
+- [x] Logic classes accept vars for limit overrides
+- [x] Agent classes expose limit methods
+- [x] All unit tests pass
+- [x] Backward compatibility verified

abstractruntime-0.2.0/docs/backlog/planned/015_agent_integration_improvements.md

@@ -0,0 +1,111 @@
+## 015_agent_integration_improvements (planned)
+
+> Update (2025-12-15): Much of this item has been addressed by the framework-wide durable tool execution work:
+> - AbstractAgent's ReAct workflow now uses `EffectType.TOOL_CALLS` (ledger-recorded, retry/idempotency-capable).
+> - Tool execution is via host-configured `ToolExecutor` (durable; no callables in `RunState.vars`).
+> - BaseAgent save/load is reference-only and delegates to RunStore.
+>
+> Remaining work is mostly *ergonomics* (a tiny convenience constructor in the integration layer), not core correctness.
+
+### Goal
+Improve the integration experience between AbstractRuntime and agent implementations (like AbstractAgent's ReactAgent).
+
+### Context
+Based on building AbstractAgent on top of AbstractRuntime, several friction points were identified:
+
+1. **Verbose agent setup** - Creating an agent requires multiple steps:
+   ```python
+   from abstractruntime.integrations.abstractcore import MappingToolExecutor, create_local_runtime
+   from abstractagent.agents.react import ReactAgent
+   from abstractagent.tools import ALL_TOOLS
+
+   tools = list(ALL_TOOLS)
+   runtime = create_local_runtime(
+       provider="ollama",
+       model="...",
+       tool_executor=MappingToolExecutor.from_tools(tools),
+   )
+   agent = ReactAgent(runtime=runtime, tools=tools)
+   ```
+
+2. **Tool execution durability** - Tool callables must never be stored in `RunState.vars` (must be JSON-safe across resume).
+
+3. **No run_id persistence at agent level** - Resuming an agent across process restarts requires manually tracking the run_id.
+
+### Proposed Improvements
+
+#### 1. Agent Factory Pattern
+Add a convenience factory in the AbstractCore integration:
+
+```python
+# Current (still a little verbose, but correct)
+from abstractruntime.integrations.abstractcore import MappingToolExecutor, create_local_runtime
+from abstractagent.agents.react import ReactAgent
+
+tools = [...]
+runtime = create_local_runtime(
+    provider="ollama",
+    model="...",
+    tool_executor=MappingToolExecutor.from_tools(tools),
+)
+agent = ReactAgent(runtime=runtime, tools=tools)
+
+# Proposed (simple)
+from abstractruntime.integrations.abstractcore import create_agent_runtime
+
+runtime = create_agent_runtime(
+    provider="ollama",
+    model="qwen3:4b-instruct-2507-q4_K_M",
+    tools=[list_files, read_file],  # Direct tool functions
+)
+```
+
+#### 2. TOOL_CALLS Effect for Agent Tool Execution
+Modify the ReAct workflow to use TOOL_CALLS effect instead of direct execution (now implemented):
+
+```python
+# Previous (pre-effect): direct execution in act_node
+# result = tool_registry.execute_tool(tool_call)
+
+# Proposed: Via effect system
+return StepPlan(
+    node_id="act",
+    effect=Effect(
+        type=EffectType.TOOL_CALLS,
+        payload={"tool_calls": pending_tool_calls},
+        result_key="tool_results",
+    ),
+    next_node="observe",
+)
+```
+
+Benefits:
+- Tool calls recorded in ledger
+- Retry/idempotency support
+- Consistent architecture
+
+#### 3. Agent State Persistence
+Add optional run_id persistence to ReactAgent (now supported via BaseAgent.save_state/load_state):
+
+```python
+agent = ReactAgent(runtime=runtime, state_file="agent_state.json")
+agent.start("task")  # Saves run_id to file
+# ... process restart ...
+agent = ReactAgent(runtime=runtime, state_file="agent_state.json")
+agent.resume_from_file()  # Loads run_id and continues
+```
+
+### Acceptance Criteria
+- [ ] Agent creation requires ≤3 lines of code for simple cases
+- [x] Tool execution is recorded in the ledger
+- [x] Agent can resume across process restarts with minimal code
+
+### Dependencies
+- AbstractCore tool registry
+- Existing TOOL_CALLS effect handler
+
+### Priority
+Medium - Improves developer experience but not blocking
+
+### Effort
+Medium - 2-3 days