HLP Integration Contracts

This page defines the narrow contracts HLP expects when it wraps an existing agent harness and capability ecosystem. These contracts do not define a new L1 or L0 protocol; they define the adapter invariants HLP relies on.

Contract Summary

Contract	Cross-boundary object	Rule
External evidence reference	Optional ExternalRef profile	Capability evidence may be recorded without exposing transport or invocation details.
TaskID correlation	Task and agent run identity	HLP Task.id must survive every delegated run and event.
Checkpoint-to-Block	Checkpoint and run state	checkpoint.raise blocks the corresponding run; checkpoint.resolve resumes it.
Harness event projection	Harness event and HLP object	Human-facing harness events become checkpoints, artifacts, and inbox items.
Ownership-to-Handoff	Ownership transfer and run handoff	ownership.transfer preserves task correlation through handoff.

Contract 1: External Evidence Reference

HLP core does not define capabilities. When a human decision, task constraint, artifact provenance, or audit replay needs external capability evidence, HLP may carry an opaque ExternalRef.

ExternalRef:
  kind: "capability"
  namespace: string
  id: string
  version: string | null
  label: string | null

Required behavior:

• External identities are created and interpreted by the host, harness, or L0 capability ecosystem.
• HLP stores the reference only as evidence; it does not resolve manifests, authorize use, invoke tools, or inspect transport.
• Capability integrations may define a CapabilityRef profile over ExternalRef(kind="capability") using (namespace, id, version).

Non-compatible behavior:

external_refs:
  - transport: "stdio"
    command: "node server.js"

Compatible behavior:

external_refs:
  - kind: "capability"
    namespace: "mcp"
    id: "cap:code-review"
    version: "2.1.0"
    label: "Code review tool"

Contract 2: TaskID Correlation

TaskID correlation is the most important integration invariant.

When HLP assigns a task to an agent, the resulting agent run must carry the same identity:

Task:
  id: "task_01J0K7..."

AgentRun:
  run_id: "run_01J0K8..."
  correlation_id: "task_01J0K7..."

Required behavior:

• task.assign delegates work through the L1 adapter.
• The adapter stores the mapping from HLP Task.id to harness run_id.
• Every run event includes the same correlation id.
• Child delegations and handoffs preserve the original correlation unless a new HLP task is explicitly created.

This invariant lets audit replay reconstruct the complete lifecycle of a human task across agent runs, subdelegations, checkpoints, and artifact commits.

Contract 3: Checkpoint-to-Block

HLP checkpoints are human decision points. The L1 route is responsible for making that decision point affect the executing agent run.

Agent reaches a decision point
  -> HLP checkpoint.raise
  -> Task state becomes blocked
  -> L1 adapter blocks the run
  -> Human resolves the checkpoint
  -> HLP checkpoint.resolve
  -> L1 adapter resumes the run with the resolution

Required behavior:

• checkpoint.raise identifies the affected task and corresponding run.
• The adapter blocks the run with the checkpoint id.
• A blocked run must not resume itself.
• checkpoint.resolve passes the human resolution to the run.
• Resolution and resume should be auditable as one logical transition.

Contract 4: Harness Event Projection

HLP does not require a harness to expose its internal planning loop, prompt state, memory, or tool traces. A harness only needs to project human-facing events into HLP semantics.

HarnessEvent:
  kind: "needs_approval"
  task_id: "task_01J0K7..."
  run_id: "run_01J0K8..."
  agent_id: "agent_reviewer"
  prompt: "Apply the generated patch?"

Required behavior:

• needs_approval, needs_choice, and needs_input become pending HLP checkpoints.
• artifact events commit immutable HLP artifacts and make them available for human review.
• Projected events must preserve task_id, run_id, and agent_id.
• Event projection must not leak harness-specific internal state into HLP objects unless that state is required for a human decision or audit.

Contract 5: Ownership-to-Handoff

HLP ownership expresses who is responsible for a task. The L1 route expresses how execution moves to another agent or human-operated worker.

Required behavior:

• ownership.transfer changes the HLP assignee and appends an ownership chain record.
• When the new assignee requires a different agent run, the adapter performs the harness-specific handoff.
• The receiving run keeps the original HLP task correlation id.
• The old run should remain visible as read-only history if the harness supports it.

Example:

OwnershipTransfer:
  from: "agent_reviewer"
  to: "agent_security"
  via: "handoff"

NewRun:
  agent_id: "agent_security"
  correlation_id: "task_01J0K7..."

Event Responsibilities

Boundary	Emits	Consumed by
Capability route	Capability invocation results and capability errors	Agent harness or host platform
Agent harness	Run and human-facing events with HLP task correlation	HLP adapter and host platform
HLP	Task, checkpoint, review, artifact, ledger, and audit events	Channels, UIs, project systems

HLP produces events, but it does not define how those events are rendered in chat, web, mobile, or CLI channels. Delivery belongs to the host platform.