What Is the Peer-Agent Runtime v1 Protocol in LoopX? A Complete Technical Guide

The Peer-Agent Runtime v1 protocol is a rank-free execution model for multi-agent coordination in LoopX where every registered peer holds equal authority, and work ownership is determined by explicit claims, leases, and deterministic assignment rules rather than hierarchical agent roles.

This protocol eliminates the traditional "primary agent" pattern from earlier versions of huangruiteng/loopx. Instead of implicit hierarchy, the peer-agent runtime v1 protocol codifies how tasks are claimed, distributed, and continued across a swarm of equal-ranking agents. The specification lives in docs/reference/protocols/peer-agent-runtime-v1.md and is implemented in loopx/runtime/peer_v1.py.

Core Purpose: Eliminating Durable Agent Rank

The fundamental shift in the peer-agent runtime v1 protocol is the removal of durable agent rank from all runtime decisions.

In legacy models, a primary_agent field or rank-bearing role dictated who owned work. The v1 protocol explicitly forbids these fields. According to the source specification, valid peer identity JSON must not contain:

• primary_agent
• handoff_agent
• Any rank-bearing role field

Work ownership becomes purely functional: derived from claimed_by annotations, active leases, continuation policies, and deterministic hashing algorithms.

Canonical Identity Structure

A valid peer-agent identity in the v1 protocol follows a strict schema. The canonical identity JSON structure includes:

Field	Value	Description
schema_version	Protocol version	Identifies the runtime revision
agent_model	"peer_v1"	Fixed discriminator for this protocol
agent_id	Unique string	Persistent identifier for this peer
registered	true	Boolean flag for registry membership
registered_agents	Array of strings	Complete list of all peers in the swarm

This identity is declared in docs/reference/protocols/peer-agent-runtime-v1.md#canonical-identity. The complete peer set must be enumerated in every identity document, enabling deterministic assignment without central coordination.

Work Ownership Rules

The peer-agent runtime v1 protocol specifies four deterministic rules for task ownership, documented in docs/reference/protocols/peer-agent-runtime-v1.md#work-ownership:

1. Explicit claim or lease wins. Any todo with claimed_by or an active lease is owned by that peer.
2. Unclaimed todos must be claimed before delivery. No peer may execute unclaimed work.
3. Agent-scoped re-plan obligations stay fixed. If a re-plan is scoped to a specific agent, that agent retains ownership.
4. Unscoped re-plan obligations use deterministic assignment. The protocol hashes a canonical work key over the sorted set of registered peers. The resulting assignment is stable and never changes the agent's authority.

The hashing algorithm ensures that the same work key always maps to the same peer, even across restarts, without requiring leader election or consensus.

Task Completion and Review Policies

Continuation behavior in the peer-agent runtime v1 protocol is expressed through task policies, not implicit role inheritance. As specified in docs/reference/protocols/peer-agent-runtime-v1.md#completion-and-review:

• independent_handoff: The successor task remains unclaimed unless a peer is explicitly selected.
• same_agent_non_delivery: The successor stays with the completing peer.

Review is classified as an action_kind, not a continuation type. When exclusion lists are provided, claimed_by must never name an excluded peer—this is enforced by the runtime validator in loopx/runtime/peer_v1.py.

Workspace Isolation Model

All peers in the v1 protocol share the same workspace guard (agent_workspace_guard_v1). However, Git worktree isolation is triggered only under specific conditions, per docs/reference/protocols/peer-agent-runtime-v1.md#workspace-isolation:

• The todo declares write scopes
• The action kind is write-classified
• The todo explicitly requests isolation

Read-only monitoring operations do not trigger guard-based isolation. This differs from hierarchy-based models where identity alone determined workspace boundaries.

Task-Scoped Coordination

When multi-agent orchestration is enabled, the peer-agent runtime v1 protocol implements temporary coordination:

1. LoopX hashes the canonical task bundle.
2. One peer is selected as temporary coordinator.
3. A task_orchestration_contract_v1 is created.

The coordinator may write evidence for the accepted bundle but holds no durable leadership. This design prevents coordinator bottlenecking while allowing serialization of complex multi-step operations. The specification appears in docs/reference/protocols/peer-agent-runtime-v1.md#task-scoped-coordination.

Migration from Legacy Hierarchies

Migration to the peer-agent runtime v1 protocol follows a controlled cut-over path, detailed in docs/reference/protocols/peer-agent-runtime-v1.md#migration:

• Legacy hierarchy fields are ignored by the peer runtime.
• A migration ID is projected through quota or upgrade-plan checks.
• Acknowledgment occurs via loopx configure-goal.
• The runtime must pass the peer-agent canary profile and the full smoke suite before the public v0.2 cut-over.

Two smoke tests validate this path:

• examples/control_plane/peer-agent-migration-smoke.py — migration contract validation
• examples/control_plane/peer-agent-workspace-guard-smoke.py — workspace guard enforcement

Running the Peer-Agent Runtime: Code Example

The minimal smoke test demonstrating the peer-agent runtime v1 protocol is located at examples/control_plane/peer-agent-runtime-v1-smoke.py:

# examples/control_plane/peer-agent-runtime-v1-smoke.py

"""
Run the durable peer-agent runtime and migration contract suite.
"""
import pathlib, json, tempfile
from loopx import loopx_cli

# 1. Load a peer-agent task-orchestration registry (example JSON)

registry_path = pathlib.Path(__file__).parent / "peer-agent-task-orchestration.registry.example.json"
registry = json.load(registry_path.open())

# 2. Execute the runtime against a goal (the goal includes peer-agent settings)

goal_id = "peer-agent-runtime-demo"
result = loopx_cli.run_goal(goal_id, registry=registry)

# 3. Verify that the heartbeat reports the peer role

assert result["heartbeat"]["agent_role"] == "peer-agent"
print("peer-agent-runtime-v1-smoke ok")

Key verification points:

• The registry file enumerates all registered_agents in the swarm.
• The run_goal invocation activates the peer runtime via loopx_cli.
• The heartbeat payload confirms agent_role: "peer-agent", proving the protocol is active.

Key Implementation Files

File Path	Purpose
docs/reference/protocols/peer-agent-runtime-v1.md	Complete protocol specification with all rules and identity schemas
loopx/runtime/peer_v1.py	Concrete implementation of the peer_v1 model used by the runtime engine
examples/control_plane/peer-agent-runtime-v1-smoke.py	Runnable smoke test for basic runtime validation
examples/control_plane/peer-agent-migration-smoke.py	Migration path validation from hierarchy to peer model
examples/control_plane/peer-agent-workspace-guard-smoke.py	Workspace isolation and guard enforcement testing

Summary

• The peer-agent runtime v1 protocol replaces hierarchical agent models with rank-free peer coordination in LoopX.
• Canonical identity requires agent_model: "peer_v1" and forbids primary_agent or rank-bearing roles.
• Work ownership derives from explicit claims, leases, and deterministic hashing—not implicit hierarchy.
• Continuation policies (independent_handoff, same_agent_non_delivery) control task handoff behavior.
• Workspace isolation is scope-driven, not identity-driven.
• Temporary coordinators enable multi-agent orchestration without durable leaders.
• Migration requires canary validation and explicit acknowledgment before cut-over.

Frequently Asked Questions

How does the peer-agent runtime v1 protocol assign tasks without a leader?

The protocol uses deterministic hashing over the sorted set of registered peers. For any unscoped re-plan obligation, LoopX computes a canonical work key, hashes it, and maps the result to a peer. The same work key always produces the same assignment, eliminating the need for leader election or consensus rounds.

What happens to legacy primary_agent fields when migrating to v1?

The peer-agent runtime v1 protocol ignores all legacy hierarchy fields. Migration requires projecting a migration ID through quota checks, acknowledging via loopx configure-goal, and passing both the peer-agent canary profile and full smoke suite. Fields like primary_agent are stripped or ignored by the runtime engine in loopx/runtime/peer_v1.py.

When does workspace isolation trigger in the peer model?

Isolation occurs only when a todo explicitly requires it: declared write scopes, write-classified action kinds, or explicit isolation requests. Read-only monitoring does not trigger guard-based isolation regardless of peer identity. All peers share agent_workspace_guard_v1 by default.

Can a peer refuse or be excluded from specific tasks?

Yes. Exclusion lists may be provided for review actions, but the protocol enforces that claimed_by must never name an excluded peer. The runtime validator in loopx/runtime/peer_v1.py rejects any claim violating this constraint. Deterministic assignment automatically respects the registered peer set.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}