Loop Contracts

A machine-checkable control plane between agent harnesses and repeated agent loops.

简体中文 · Skill · Contract template

Agent harnesses expose context, tools, permissions, memory, and feedback. Agent loops decide when work repeats, changes state, recovers, stops, or asks for help. Loop Contracts binds those two layers into a vendor-neutral JSON artifact that can be reviewed before an autonomous workflow runs.

Loop Contract
  = Harness capabilities
  + Explicit state machine
  + Progress and repetition signals
  + Hard budgets and finite retries
  + Verification evidence
  + Recovery and escalation
  + Human gates and traces

This repository contains:

• engineer-agent-loops, an Agent Skill for designing and auditing loops;
• loop-contract, a dependency-free Python CLI for semantic validation, scoring, and Mermaid diagrams;
• a canonical contract template and reusable loop patterns;
• tests and CI that exercise both safe and intentionally broken contracts.

Why this exists

“Harness engineering” and “loop engineering” are emerging terms, not universally standardized disciplines. Their practical boundary is still blurry. Loop Contracts proposes one concrete boundary artifact:

Layer	Primary question	Typical output
Prompt	What should the model do now?	Instruction
Context	What should the model see now?	Context window
Harness	What can one run observe and do safely?	Runtime capabilities
Loop	When should work repeat or stop?	Temporal policy
Loop contract	Can that policy be inspected and checked before execution?	Versioned contract + findings

It is deliberately not another agent runtime. It does not call a model, execute verification commands, schedule jobs, or grant permissions. It checks whether a proposed loop declares the controls a runtime integration will need.

Quick start

Python 3.9+ is sufficient; there are no third-party dependencies.

python skills/engineer-agent-loops/scripts/loop_contract.py init my-loop.json
python skills/engineer-agent-loops/scripts/loop_contract.py validate my-loop.json
python skills/engineer-agent-loops/scripts/loop_contract.py score my-loop.json
python skills/engineer-agent-loops/scripts/loop_contract.py diagram my-loop.json

Strict mode treats warnings as a failing result:

python skills/engineer-agent-loops/scripts/loop_contract.py validate my-loop.json --strict

The score is a control-coverage heuristic. A high score is not evidence of model correctness, business correctness, or production safety.

Install the Skill

Clone the repository and copy the self-contained skill directory into the skill path used by your agent product. For Codex:

git clone https://github.com/Rowan2005321/loop-contracts.git
cp -R loop-contracts/skills/engineer-agent-loops ~/.codex/skills/

Then invoke it with a request such as:

Use $engineer-agent-loops to turn our recurring CI repair workflow into a
bounded loop contract. Require independent verification and escalation after
two no-progress attempts.

What the validator catches

• a while true design with fewer than two hard budgets;
• unreachable success or escalation states;
• terminal states with outgoing transitions;
• cycles without progress signals and repetition fingerprints;
• retries without finite, failure-specific limits;
• completion that bypasses verification evidence;
• recurring workflows that rely on ephemeral state;
• scheduled workers without per-item budgets, leases, cursors, quarantine, concurrency, or a disable switch;
• broad external-write permissions without human gates;
• missing trace events, redaction rules, rollback, or checkpoints.

Static validation cannot detect prompt injection, weak verifiers, incorrect business rules, a malicious runtime, or a model that ignores the contract. Those require runtime enforcement and evaluation.

Design principles

1. Evidence before completion. The producing agent is not the sole judge of its own work.
2. Bound every cycle. Use independent iteration, time, cost, or tool-call limits.
3. Recovery must change something. New evidence, strategy, context, or authority distinguishes recovery from repetition.
4. Externalize state. A loop should resume, explain itself, or explicitly admit that it cannot.
5. Escalation is a valid terminal. Lack of authority or evidence is not a reason to retry forever.
6. Keep the runtime replaceable. Contracts describe behavior without requiring one model or framework.

Project status

This is an early design and tooling proposal (contract_version: 0.1). Field names and scoring weights may change before 1.0. Contributions should bring a concrete failure trace, contract example, or validator case rather than only a new term.

Influences

• OpenAI, Harness engineering: leveraging Codex in an agent-first world
• OpenAI, The next evolution of the Agents SDK
• Zhong and Zhu, AI Harness Engineering: A Runtime Substrate for Foundation-Model Software Agents
• Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models

The phrase “loop contract” and this schema are this project's proposal, not an industry standard or a claim of ownership over the underlying engineering practices.

简体中文

Loop Contracts 试图补上 Harness Engineering 与 Loop Engineering 之间的一层：Harness 定义一次 Agent 运行能看见什么、调用什么；Loop 定义什么时候继续、恢复、停止或升级给人；Loop Contract 则把两者编译成一份可以进 Git、可以审查、可以静态检查的 JSON 契约。

它不是新的 Agent 框架，也不会替你执行模型。当前 MVP 提供 Agent Skill、契约模板、语义检查器、控制覆盖评分和 Mermaid 状态图。重点检查无限重试、假进展、无证据结束、不可恢复状态和高风险操作缺少人工闸门等问题。

License

MIT