Metadata-Version: 2.4
Name: letitloop
Version: 0.2.0
Summary: Deterministic verification harness and crash-safe execution gate for AI coding agents
Author-email: sdageltc <sdageltc@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://sdageltc.github.io/letitloop/
Project-URL: Documentation, https://github.com/sdageltc/letitloop#readme
Project-URL: Repository, https://github.com/sdageltc/letitloop
Project-URL: Bug Tracker, https://github.com/sdageltc/letitloop/issues
Project-URL: Discussions, https://github.com/sdageltc/letitloop/discussions
Keywords: autonomous-agents,agent-loop,mcp,mcp-server,docker-sandbox,worktree,process-guard,tui,prometheus,webhooks,claude-code,cursor,antigravity,hermes-agent,opencode,cline,windsurf,codex,openai-codex,dag-planner,coding-agent,orchestration,zero-trust-verification,quality-plane,local-llm,ollama
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: jsonschema>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: bandit>=1.7.5; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-generativeai>=0.4.0; extra == "google"
Provides-Extra: all-providers
Requires-Dist: openai>=1.0.0; extra == "all-providers"
Requires-Dist: anthropic>=0.18.0; extra == "all-providers"
Requires-Dist: google-generativeai>=0.4.0; extra == "all-providers"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.20; extra == "telemetry"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "telemetry"
Requires-Dist: prometheus-client>=0.19; extra == "telemetry"
Dynamic: license-file

<p align="center">
  <img src="assets/logo.png" alt="let it loop (LIL)" width="340" style="border-radius: 20px;">
</p>

<div align="center">

# let it loop (LIL)

**Autonomous macro-task orchestration & verification control loop for AI coding agents: 2ms WAL crash durability, source-span AST self-evolution, and deterministic proof gates.**

[![PyPI version](https://img.shields.io/pypi/v/letitloop.svg?color=blue)](https://pypi.org/project/letitloop/)
[![CI Matrix](https://github.com/sdageltc/letitloop/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sdageltc/letitloop/actions/workflows/ci.yml)
[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-LetItLoop_Action-blue?logo=github)](https://github.com/marketplace/actions/letitloop-proof-carrying-pr-verification-gate)
[![Benchmark](https://img.shields.io/badge/DCP--1.0-Durability_Bench-green)](https://github.com/sdageltc/agent-durability-bench)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Architecture](docs/index.html) • [Quickstart](#quickstart) • [Marketplace Action](https://github.com/sdageltc/letitloop-action) • [Crash Benchmark](https://github.com/sdageltc/agent-durability-bench) • [Worker Adapters](#supported-worker-adapters--gateways) • [Cookbook](#recipes--cookbooks)

</div>

---

## The LetItLoop Tripartite Ecosystem

LetItLoop solves the central failure mode of autonomous AI coding agents: **the lack of deterministic verification, uncatchable mid-task SIGKILL crashes, and destructive whole-file rewrites**.

```mermaid
graph TD
    subgraph "The Tripartite Ecosystem"
        LL["<b>letitloop</b> (Core Engine)<br/>Deterministic WAL plumbing, AST node splicer and FastSandbox"]
        LLA["<b>letitloop-action</b> (Marketplace)<br/>Drop-in CI gate signing proof bundles on Pull Requests"]
        ADB["<b>agent-durability-bench</b> (DCP-1.0)<br/>Open benchmark measuring agent recovery under SIGKILL faults"]
    end

    LL -.->|"bridges to"| ADB
    LL -.->|"scaffolds"| LLA
```

1. **[`letitloop`](https://github.com/sdageltc/letitloop)**: The core engine providing sub-2ms Write-Ahead Logging (WAL) state journals, source-span AST node splicing (0% comment loss), in-memory Zero-Copy fast sandboxing, and deterministic verification gates.
2. **[`letitloop-action`](https://github.com/sdageltc/letitloop-action)**: Standalone GitHub Action for CI that validates AI pull requests, enforces strict AST signatures, and posts machine-verifiable proof bundles directly to PR comments.
3. **[`agent-durability-bench`](https://github.com/sdageltc/agent-durability-bench)**: An open benchmark suite implementing Durability Challenge Protocol 1.0 (DCP-1.0) with zero-API synthetic simulation to measure how well agents recover from uncatchable SIGKILL crashes.

---

## Key Capabilities

- **Source-Span AST Node Splicer**: Replaces targeted functions and class methods with surgical precision. **0% Comment Loss**: Guarantees module docstrings, file comments, licensing headers, and class indentation are never stripped or altered.
- **In-Memory Fast Sandbox**: Zero-Copy `sys.modules` evaluation and Windows Job Object containment that verifies code hypotheses in-memory before writing anything to disk.
- **Fault-Tolerant WAL Supervisor Loop**: State journal with WAL (Write-Ahead Logging), crash recovery, atomic Win32/POSIX file locking, and bounded 3-strike retries with strategy mutation.
- **Cognitive Feasibility Gate & Multi-Source Research**: Deliberates whether a refactor is safe to perform autonomously or requires background research across arXiv, GitHub, and DuckDuckGo.
- **Human-in-the-Loop Proposal Ledger**: Automatically stages deferred, high-risk architectural proposals as structured markdown artifacts (`PROP-*.md`) for human review rather than executing unverified mutations.
- **Zero-Trust Verification Engine**: Deterministic acceptance check kinds (AST syntax parsers, command exit-code assertions, regex matchers, file validators, size bounds, and undeclared output detectors).
- **12 Pluggable Worker Adapters**: Native interfaces for Claude Code, OpenAI Codex, Google Antigravity (`agy`), OpenCode, Hermes Agent, Cline, Aider, Docker Sandboxes, Local LLMs (Ollama/vLLM), Omniroute gateways, local scripts, and direct LLMs.
- **Native Model Context Protocol (MCP) Server & Client**: 8 stdio JSON-RPC tools connecting directly with Claude Code, OpenAI Codex, Cursor, Google Antigravity, and Hermes Agent.
- **Cross-Platform Process Orphan Guard**: Windows Job Objects (`win32job`) and POSIX session process-group containment ensuring complete cleanup of child/grandchild processes.
- **Prometheus Observability & Signed Webhooks**: Native Prometheus metrics exporter, lifecycle event bus, SSE streaming, and HMAC-SHA256 signed webhook dispatcher.

---

## Quickstart

### 1. Installation

```bash
# Install letitloop core engine
pip install letitloop

# Or install with all development and worker dependencies
pip install "letitloop[dev]"
```

### 2. Basic CLI Usage

```bash
# Propose a contract DAG from a natural language objective
lil propose "Build a rate limiter middleware with unit tests" --run

# Bridge to the agent durability benchmark
lil bench --steps 5

# Scaffold a production GitHub Action PR verification workflow
lil action --init

# Inspect live supervisor status, WAL journal, and active checkpoints
lil status

# Run deterministic reconciliation audit across workspace files
lil reconcile <goal_id>
```

---

## Supported Worker Adapters & Gateways

| Worker Adapter | Identifier | Description | Tier |
|---|---|---|---|
| **Google Antigravity CLI** | `antigravity-cli` | Invokes the official `agy` agent runner safely | **Tier-1 (Core)** |
| **Claude Code CLI** | `claude-code` | Autonomous task execution via Claude Code CLI | **Tier-1 (Core)** |
| **OpenAI Codex CLI** | `codex` | Autonomous task execution via OpenAI Codex CLI | **Tier-1 (Core)** |
| **Mock Worker** | `mock` | Deterministic simulation worker for CI and offline tests | **Tier-1 (Core)** |
| **OpenCode CLI** | `opencode` | Autonomous execution via OpenCode agent CLI | Tier-2 (Contrib) |
| **Hermes Agent CLI** | `hermes` | Autonomous execution via Nous Research Hermes agent CLI | Tier-2 (Contrib) |
| **Cline CLI** | `cline` | Headless execution via Cline autonomous coding runner | Tier-2 (Contrib) |
| **Aider Pair Programmer** | `aider` | Pair programming execution via Aider CLI | Tier-2 (Contrib) |
| **Docker Sandbox Worker** | `docker` | Isolated execution inside container runtime with workspace scoping | Tier-2 (Contrib) |
| **Local LLM Tool Caller** | `local-tool` | Local tool-calling model adapter for offline Ollama/vLLM loops | Tier-2 (Contrib) |
| **Omniroute Gateway** | `omniroute` | Multi-model fallback routing through local/remote gateways | Tier-2 (Contrib) |
| **Script Worker** | `script` | Executes local shell/Python automation scripts with env isolation | Tier-2 (Contrib) |
| **Direct LLM APIs** | `direct` | In-process calls to Gemini, OpenAI, Anthropic, DeepSeek, or Ollama | Tier-2 (Contrib) |

---

## Model Context Protocol (MCP) Integration

LetItLoop runs natively as an MCP server providing 8 JSON-RPC tools to AI agent runners:

```json
{
  "mcpServers": {
    "letitloop": {
      "command": "letitloop-mcp",
      "env": {
        "WORKER_MODEL": "gemini:gemini-3.7-flash",
        "QC_MODEL": "gemini:gemini-3.1-pro"
      }
    }
  }
}
```

#### Add to Claude Code
```bash
claude mcp add letitloop -- python -m orchestrator.mcp_server
```

---

## Recipes & Cookbooks

The [`recipes/`](recipes/README.md) cookbook provides end-to-end, schema-validated walkthroughs:

| Recipe | Focus |
|---|---|
| [**01 - Legacy Codebase Refactor**](recipes/01-legacy-codebase-refactor/README.md) | Refactor under `pytest` + `ruff` acceptance gates with scope fencing and bounded retries |
| [**02 - FastAPI CRUD Generator**](recipes/02-fastapi-crud-generator/README.md) | Feature decomposition into a 4-contract DAG chained with `depends_on` |
| [**03 - Offline Local LLM Loop**](recipes/03-offline-local-llm-loop/README.md) | Zero-cloud-key runs via Ollama (`local-tool`) and the `docker` sandbox adapter |
| [**04 - Multi-Agent QC Audit**](recipes/04-multi-agent-qc-audit/README.md) | Multi-lens quality plane: panels, arbitration, budgets, and `quality_spec` |

Validate all embedded example contracts anytime with `pytest tests/test_recipes.py -q`.

---

## Living Architecture Decision Records (ADRs)

Following the Michael Nygard ADR convention, all core design invariants and architectural decisions are codified:

| ADR | Focus | Status |
|---|---|---|
| [**ADR-0001**](docs/adr/0001-write-ahead-logging.md) | **Write-Ahead Logging (WAL) & Zero-State Recovery** | `accepted` |
| [**ADR-0002**](docs/adr/0002-deterministic-verifiers.md) | **Deterministic AST, Regex & Exit-Code Verification Gates** | `accepted` |
| [**ADR-0003**](docs/adr/0003-headless-cli-adapters.md) | **Zero-API-Key Headless Agent CLI Wrapper Failovers** | `accepted` |
| [**ADR-0004**](docs/adr/0004-format-aware-acceptance-checks.md) | **Format-Aware Acceptance Check & Markdown Injection** | `accepted` |

---

## Security & Sandboxing Architecture

`letitloop` operates under a zero-trust execution model:
- **Redaction Firewall**: Automatic masking of PATs, OAuth keys, AWS credentials, GCP tokens, and PEM private keys.
- **Environment Scrubbing**: Sensitive parent environment variables are stripped prior to worker execution.
- **Scope Checking**: Userland filesystem snapshot diffing (`scope.py`) enforcing directory bounds and declared output paths.
- **Process Isolation**: Process tree containment with Windows Job Objects (`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`) and POSIX session leadership.

---

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for more details.
