Visible-Agent-Loop-Protocol
Visible Agent Loop Protocol
Agent says done. VALP asks for proof.
VALP is an open protocol for visible, evidence-backed autonomous and multi-agent work.
Start here:
- Repository README
- 中文注解
- Protocol specification
- RFC 0002: layered architecture and D01-D19 traceability
- v0.3 draft installation control plane and RFC
- Twelve-layer N/I/P audit matrix
- Quickstart
- Compound learning loop
- When Agent “Done” Is Not Done
- Minimal audit demo
- Visible dispatch process proof
- Failure gallery
- Correction cycle evidence
- Runtime adapter checklist
- Runtime adapters
- Community
- Maintainer governance
- Support
The core idea is narrow: a runtime saying completed is not enough. VALP
completion requires automation policy, dispatch receipts, expected evidence,
verification/review, approval gates when needed, final synthesis, and
task-local learning feedback that points to proof.
VALP is currently 0.2.0. It is an open protocol release plus a reference CLI,
not a hosted production platform.
Protocol 0.3 Layered Architecture
The public RFC 0002 package comprises SPEC.md, this documentation index, the
project status page, and RFC 0002. It separates the Protocol 0.3 target into
five explicit layers: the Human Intent And
Authority Boundary, Reference System, pure Protocol Kernel, Adapter Boundary,
and External Runtime And Ecosystem. The
specification
defines the normative ownership and proof boundaries; RFC 0002
records public D01-D19 traceability and the staged implementation boundary.
Pure Protocol Kernel Slice 1 implements the closed Layer 02 Task transition
graph across its 13 truth statuses, with typed Events, terminal-state closure,
canonical identities, closed enums, State and accepted / no_op /
rejected Result contract, deterministic duplicate behavior, and ordered
ReplayEntry(Event, EvidenceSet, accepted Result) reducer re-execution with
complete canonical Result equality from a validated Genesis Root. It also
defines a structural Checkpoint Root contract that binds State, prefix, tail,
checkpoint-Result, and trust-policy identities. MVP-H authenticates that root
against an independently supplied trust policy and exact EvidenceSet, then
recomputes an ordered suffix through the same reducer while emitting zero
obligations. The machine contract and negative tests reject bare State roots,
impossible revision/history combinations, malformed or mismatched checkpoint
authentication, identity drift, suffix gaps/reordering/duplicates, and tampered
Results. This remains Layer 02 local proof, not checkpoint storage, effect
reconciliation, wait/wake, Adapter continuation, or runtime recovery. The repository also
implements a pure v3 receipt-write reducer and digest-bound legacy/v2 migration
projection fixtures. A file-backed Reference System store performs cooperative
inter-process locking, canonical-prefix replay, CAS, atomic replacement, and
file plus directory synchronization. Its current evidence covers process-crash
recovery on the tested macOS/APFS host; it does not establish sudden-power-loss,
hostile-writer, or Windows parity. LangGraph is the only bounded Adapter path
that uses this canonical v3 store end to end. HERDR, Queue, Manual Mode, and
workflow observation/recovery remain legacy/v2 compatibility-only paths. This
remains a bounded Kernel and Reference System slice, not the complete Protocol
Kernel or complete third-layer implementation. No broader Adapter conformance,
cross-platform parity, or release support is claimed. The stable public release
remains 0.2.0.
v0.3 Draft Implementation
The current stable release remains 0.2.0. The
v0.3 installation control plane RFC
targets 0.3.0-draft. RFC 0001 remains incomplete and is not stable as a
whole. Its deterministic-wake and installation-core slices are implemented and
tested in the reference CLI, schemas, and conformance runner; the remaining
live-runtime work does not change current release or runtime-support claims.
The draft implementation extends VALP’s evidence discipline from individual tasks to the installation control plane: the user selects an Installation Leader; capability truth remains separated into declared, present, callable, and task-verified layers; messages, state, claims, failures, and review gain strict machine contracts; and provider plugins stay outside the deterministic core.
The first real non-HERDR end-to-end proof now exists for the local LangGraph API
development runtime. Stable 0.3.0 still requires the remaining implementation,
schema and migration work, negative/recovery conformance, and stronger restart
and continuation proof. See the project status matrix for
what is verified today and the RFC
for the proposed target.
First useful actions:
- Run
bin/valp audit examples/minimal-taskto inspect the evidence shape. - Read When Agent “Done” Is Not Done for the shortest public explanation.
- Run the minimal audit demo to see PASS -> FAIL -> PASS when expected evidence is removed and restored.
- Watch the visible dispatch process proof to see a real VALP/HERDR publish-and-dispatch run.
- Read the failure gallery to see what VALP catches.
- Use the adapter checklist before claiming runtime compatibility.
- Share a real false-done failure case in GitHub Discussions.
- Request or prototype a runtime adapter only after the receipt/evidence gates are clear.
Active discussions:
Good first tasks: