Metadata-Version: 2.4
Name: exec-kernel
Version: 0.1.0
Summary: Deterministic task lifecycle enforcement for multi-agent systems
Author: Autonomous Ventures
License-Expression: MIT
Project-URL: Homepage, https://github.com/AutonomousVentures/exec-kernel
Project-URL: Source, https://github.com/AutonomousVentures/exec-kernel
Project-URL: BugTracker, https://github.com/AutonomousVentures/exec-kernel/issues
Project-URL: Documentation, https://github.com/AutonomousVentures/exec-kernel
Keywords: agent,lifecycle,state-machine,task-management,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Dynamic: license-file

# Execution Kernel

Deterministic task lifecycle enforcement for multi-agent systems.

## Overview

The execution kernel is a lightweight Python library and CLI tool that enforces
strict task lifecycle semantics across agent operations. It prevents infinite
work loops, skipped lifecycle states, and speculative busywork — ensuring
agents produce only valid, bounded, externally-valuable work.

## Components

| Module | Responsibility |
|--------|---------------|
| `lifecycle.py` | State machine for task transitions (`todo` → `in_progress` → `done`, etc.) |
| `loop_detector.py` | Detection/prevention of self-generated work loops (depth, cycle, identity) |
| `budget.py` | Execution budget enforcement (steps, depth, wall-clock time) |
| `paperclip_adapter.py` | API adapter translating kernel actions to Paperclip API calls |
| `config.py` | YAML configuration loading with deep-merge defaults |
| `cli.py` | CLI entry point for shell/agent environments |

## Installation

```bash
pip install exec-kernel
```

Or from source:

```bash
git clone <repo-url>
cd autonomous-ventures
pip install -e .
```

## CLI Usage

Validate a state transition:

```bash
exec-kernel validate todo in_progress
# VALID: Work started
```

Check for loops:

```bash
exec-kernel check-loop child-1 agent-1 feature --parent-task-id parent-1
# ALLOWED: depth=1
```

Check budget:

```bash
exec-kernel check-budget task-1 --steps 5 --max-steps 10
# OK: 5 steps, 0s elapsed (max 10 steps, 1800s)
```

Enter idle sleep (no task generation allowed):

```bash
exec-kernel sleep --timeout 30 --agent-id agent-1
# SLEEP:idle agent=agent-1 reason=no_tasks timeout=30s
```

## Python API

```python
from kernel.lifecycle import TaskLifecycle, TaskState
from kernel.loop_detector import LoopDetector, WorkNode
from kernel.budget import BudgetTracker

# State machine
task = TaskLifecycle(task_id="my-task")
task.transition(TaskState.IN_PROGRESS)
task.transition(TaskState.DONE)

# Loop detection
detector = LoopDetector(max_depth=10)
detector.check_new_task("new-task", "agent-1", "feature", parent_task_id="parent-1")

# Budget tracking
tracker = BudgetTracker()
state = tracker.start_task("task-1", {"max_steps": 50})
```

## Configuration

Create `.exec-kernel.yml` in your project root:

```yaml
lifecycle:
  max_depth: 10
  max_heap_size: 1000

budget:
  max_steps: 50
  max_depth: 10
  max_duration_seconds: 1800
```

## Architecture

```
┌─────────────────────────────────────────────┐
│  exec-kernel CLI / Python API               │
│  ┌──────────┐ ┌──────────────┐ ┌─────────┐  │
│  │Lifecycle │ │Loop Detector │ │ Budget  │  │
│  │State     │ │              │ │Enforce- │  │
│  │Machine   │ │              │ │ment     │  │
│  └──────────┘ └──────────────┘ └─────────┘  │
│  ┌────────────────────────────────────────┐  │
│  │ Paperclip API Adapter                  │  │
│  └────────────────────────────────────────┘  │
└─────────────────────────────────────────────┘
```

## Development

```bash
pip install -e ".[dev]"
pytest tests/
```

## License

MIT — see [LICENSE](/LICENSE).
