Implementation Guide

Use this guide to choose the right entry point. HLP is the only complete protocol specification in this project. L1 and L0 pages are routing references for integrating with existing agent harness and capability ecosystems.

Document	Type	Meaning
HLP	Full protocol specification	The primary spec: schemas, state machine, operations, errors, and conformance.
Agent Protocol Routes	L1 routing reference	How HLP can delegate into existing harnesses, A2A, ACP, or AGNTCY-style meshes.
Capability Protocol Routes	L0 routing reference	How HLP records optional capability evidence from MCP, Agent Skills, local tools, or registries.
Integration Map	Implementation map	One-page ownership, operation, identity, and adapter boundary map.
Contracts	Cross-layer reference	The narrow contracts HLP expects harness adapters to preserve.

Path 0: Embed the HLP SDK

Start from the public Python surface when you are building an application or host process:

from loops import ArtifactPayload, CheckpointOption
from loops import CodexCLIAdapter, HLPHost

host = HLPHost.in_memory(adapter=CodexCLIAdapter())
client = host.client

task = await client.create_task(
    principal="user_alice",
    goal="Review PR #1234",
)
run = await client.delegate(task.id, "agent_codex")
await client.start(task.id)

checkpoint = await client.raise_checkpoint(
    task_id=task.id,
    kind="choice",
    prompt="Ship the patch?",
    options=(CheckpointOption(id="safe", label="Review first"),),
    raised_by=run.agent_id,
)
await client.resolve_checkpoint(
    checkpoint.id,
    by="user_alice",
    action="choose",
    choice="safe",
)

artifact = await client.commit_artifact(
    task_id=task.id,
    type="report",
    payload=ArtifactPayload(
        kind="inline",
        uri="mem://report-v1",
        checksum="sha256:report-v1",
    ),
    produced_by=run.agent_id,
)
review = await client.submit_review(
    task_id=task.id,
    artifact_id=artifact.id,
    reviewer="user_alice",
    verdict="approved",
)
await client.write_ledger(
    "project:web",
    "pr.1234",
    review.verdict,
    by=task.id,
)
audit = await client.replay_audit(task.id)

Use HLPHost to wire store, event bus, and harness adapters. Use HLPClient for task, checkpoint, artifact, review, ledger, audit, and human inbox operations. Public imports should come from loops or loops.hlp; internal package names are implementation details.

Path 1: Build a Human Loop Platform

Read HLP first.

You are building this path if your system needs to represent accountable work: assignments, human decision gates, artifact review, project ledger state, and audit replay.

Implementation checklist:

• Implement all seven HLP objects: Task, Checkpoint, Ownership, Review, Artifact, Ledger, and Audit.
• Implement the 23 required HLP operations.
• Enforce the Task state machine and operation preconditions.
• Persist immutable specs, artifact versions, reviews, ledger entries, and audit events.
• Bridge downward to your chosen agent harness for delegation, blocking, resuming, and handoff.

Expected work: large. HLP is a complete protocol surface.

Path 2: Wrap an Existing Agent Harness

Read Agent Protocol Routes, then Integration Contracts.

You are building this path if you already have an agent harness, A2A runtime, ACP broker, agent mesh, or multi-agent orchestrator and want HLP to provide the human interaction control plane around it.

Implementation checklist:

• Expose discover, delegate, block, resume, and handoff.
• Return a run handle immediately from delegate.
• Attach correlation_id to every run and event.
• Set Run.correlation_id = HLP TaskID.
• Treat block as authoritative: an agent run must not resume itself while blocked by a HLP checkpoint.
• Preserve correlation during handoff.
• Project human-facing harness events such as approvals, choices, input requests, and artifacts into HLP objects.

Expected work: small to medium. You are not implementing a new Loops harness or L1 protocol; you are preserving HLP correlation, pause/resume, and event projection semantics in the harness you already use.

Path 3: Connect a Capability Source

Read Capability Protocol Routes.

You are building this path if you provide tools, MCP servers, Skills, packaged automation, retrieval functions, or other agent-callable capabilities.

Implementation checklist:

• Map your existing discovery mechanism into stable external refs only when HLP needs capability evidence.
• Give every HLP-visible capability evidence ref a globally unique (namespace, id, version) tuple.
• Publish enough manifest or schema data for humans to understand task constraints.
• Preserve invocation results and errors as harness or host-platform evidence.
• Hide transport details from HLP and agent-level planning.

Expected work: minimal for MCP servers and Skills runtimes; moderate for plain function-calling registries that lack discovery.

Path 4: Assemble a HLP-Centered Stack

Read in this order:

1. HLP
2. Integration Contracts
3. Agent Protocol Routes
4. Capability Protocol Routes
5. Integration Map
6. HLP Conformance

Build from the human-loop boundary outward:

• Implement HLP objects and operations.
• Embed through HLPHost or an equivalent host process.
• Connect your agent harness through narrow command and event adapters.
• Connect capability sources through the agent harness or host platform.
• Verify that HLP task identity survives every harness and capability boundary.

Path 5: Evaluate an Existing Product

Use the Conformance page as an audit checklist.

Ask four questions:

1. Does the product represent human-agent work through HLP tasks, checkpoints, reviews, artifacts, ledger entries, and audit events?
2. Can every delegated agent run preserve the HLP TaskID as correlation?
3. Can checkpoints block and resume the corresponding agent run without letting the agent bypass the human decision?
4. Can harness approval/input/artifact events be projected into HLP objects?
5. If capability evidence is part of the claim, can HLP record it without exposing transport or invocation details?

If any answer is no, the product may still be useful, but it should not claim HLP compatibility.

Reference Demos (Offline)

Each demo runs without external services and prints its evidence as JSON:

Demo	Shows
uv run loops-hlp-demo	Full HLP workflow through the default Codex CLI adapter.
uv run loops-hlp-adapters-demo	Adapter compatibility checks without external services.
uv run loops-hlp-realtime-demo	HLP-realtime promotion: soft merge → amend provenance, BCI-alone high-risk deny.
uv run loops-hlp-bci-demo	BCI (brainwave) channel compatibility: soft promotion, low-risk resolve, D3 fail-closed, second factor.
uv run loops-hlp-soft-e2e	Soft-control harness E2E (multi soft → merge → amend/steer).
uv run loops-hlp-tui --adapter fake	Interactive host channel with checkpoints, reviews, and soft-buffer promotion.

Live variants against installed CLIs (Codex, Pi, Claude Code, Kimi) are opt-in via HLP_RUN_EXTERNAL_CLI_E2E=1; see the repository README's Verification section.

Recommended First Flow

For a reference implementation, start with a single task:

Human creates Task
  -> HLP task.assign
  -> Harness delegate with Run.correlation_id = TaskID
  -> Agent reaches a decision point
  -> Harness projects needs_approval to HLP checkpoint.raise
  -> Harness block
  -> Human resolves the checkpoint
  -> Harness resume
  -> Harness projects Artifact
  -> Human submits Review
  -> Task reaches completed
  -> Audit replay reconstructs the flow

If this flow works without losing correlation or mutating immutable records, the implementation has the core Loops shape.