loopexec

Overview

LoopExec is a deterministic runtime for bounded agentic execution loops. Work progresses through an external check and stops on a computed reason — never because an agent says it is done.

Supply a work command and an external check. LoopExec bounds execution, detects regression, no progress and oscillation, applies integrity guards, and records replayable receipts. Opt-in workflows add usage evidence, scoped model-call budgets and candidate restoration. Isolation orchestration composes with operator-provided container, egress and credential hooks.

The runtime governs execution; adapters supply models, checks and infrastructure. Synthetic creative examples prove runtime mechanics, not production model quality. Observed spending cannot enforce a provider-side cap, a signature file requires explicit verification, and retaining a candidate does not establish owner acceptance.

Getting Started begins with an offline deterministic proof. SMALL describes plans, constraints, progress and handoff; LoopExec drives one bounded loop. SMALL is optional for consumers.

The normative contract is SPEC.md. The current source implements bounded execution, determinism probing, integrity and regression guards, offline-verifiable receipts, and opt-in unattended workflows. See SPEC.md section 11 for the implemented scope and remaining sub-parts.

Current status

Source identity: v0.5.0-rc.1, a release candidate adding visible model profiles and task/role assignments. See candidate notes; the Releases page establishes publication status. Workflow thresholds remain supplied by each integration.

60-second proof

Run the built-in deterministic demo with no model, API key, Python runner, or network access:

loopexec demo

The command creates a red local fixture, sends it through the real bounded loop, repairs it, observes the external check turn green, writes a typed JSONL receipt, and verifies the recorded check fingerprint through the same verifier used by loopexec replay. It proves the execution/check/receipt/replay contract, not agent intelligence. For your own work command and check, follow Getting Started.

The receipt path in the output identifies the retained temporary workdir. To keep the proof at a known path, pass a fresh directory with --workdir <dir>; demo refuses to overwrite an existing .loopexec directory or status.txt fixture.