exec-kernel 0.1.0

Deterministic task lifecycle enforcement for multi-agent systems

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

pip install exec-kernel

Or from source:

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

CLI Usage

Validate a state transition:

exec-kernel validate todo in_progress
# VALID: Work started

Check for loops:

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

Check budget:

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):

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

Python API

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:

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

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

License

MIT — see LICENSE.