How it works

From a single capability to a replayable record.

A walk through the mechanics: what a capability is, the contract a host declares, the guarantees the protocol makes, and the evidence every invocation leaves behind. For the formal surface see the protocol reference; for runnable code see the examples.

Concrete example first

A capability is something a host can do.

A field service company can expose technician scheduling as a hosted capability. An agent can discover it, a manager can govern it, and a workflow can compose it with inventory lookup and customer notification.

CHP notation

[Planning Agent] -> {schedule_technician} @ ServiceOpsHost | manager_approval | job_context -> Confirmed Appointment

notify_customerVerified

host: CustomerCommsHostpolicy: auditedv1.0.0

complete_service_visitDeclared

host: ServiceWorkflowpolicy: restrictedv0.3.0

Business process host

ServiceOpsHost

Available

Capabilities are exposed with ownership, lifecycle state, and policy before invocation.

schedule_technicianInvokable

Finds an available qualified technician and reserves a service window.

host: ServiceOpsHostpolicy: approval_requiredv1.0.0

query_inventoryDiscoverable

Checks required parts by SKU, location, and requested service date.

host: ServiceOpsHostpolicy: restrictedv1.2.0

Policy boundary

Approval required

manager_approval

A manager must approve technician scheduling before the hosted capability produces a confirmed appointment.

The protocol, drawn

One example, through every primitive.

The same field-service action — a planning agent scheduling a technician, gated by a manager's approval — drawn through the host, the invocation, the policy boundary, and the evidence it leaves.

A host exposes capabilities

A host declares what it can do — each capability with a version, a policy, and a lifecycle state — before anyone calls it.

Business process host

ServiceOpsHost

Available

High-value actions require approval; every invocation is evidenced.

schedule_technicianInvokable

Finds an available qualified technician and reserves a service window.

host: ServiceOpsHostpolicy: approval_requiredv1.0.0

query_inventoryDiscoverable

Checks required parts by SKU, location, and requested service date.

host: ServiceOpsHostpolicy: restrictedv1.2.0

An invocation crosses the boundary

A caller invokes through actor, capability, host, policy, and context — and the boundary returns a result.

Invocation trace

01 Actor
Planning Agent
02 Capability
schedule_technician
03 Host
ServiceOpsHost
04 Policy
manager_approval
05 Context
job_context
06 Result
Confirmed Appointment

Policy is visible before the action

Governance is part of the contract: a capability declares whether it is open, restricted, or needs approval — before it runs.

Policy boundary

Approval required

schedule_technician

Dispatching a technician needs manager approval. Without it, the boundary denies the action and records the denial.

Every attempt leaves evidence

The result is a replayable, tamper-evident trail — including the human approval — correlated by one id.

Audit trace

session-abc

01
execution_started
2026-06-16T15:14:20.001Z
success
Invocation admitted through the boundary; handler begins.
actor: agent://planning-assistant
02
approval_granted
2026-06-16T15:14:21.488Z
success
Manager approved the dispatch — a governed human decision in the trace.
actor: human://shift-manager
03
execution_completed
2026-06-16T15:14:22.104Z
success
Technician reserved; appointment confirmed.
actor: host://ServiceOpsHost

Concrete artifact

A host contract an agent can inspect.

CHP gives callers concrete manifests, invocation envelopes, and structured outcomes they can validate before trusting a capability.

See examples →

Manifest

Discover what exists before planning.

manifest.json

json

{
  "id": "service-ops-host",
  "version": "0.1.0",
  "protocol_version": "0.1",
  "kind": "service",
  "capabilities": [{
    "id": "schedule_technician",
    "version": "1.0.0",
    "description": "Reserve a qualified technician.",
    "status": "experimental",
    "modes": ["sync"],
    "emits": ["execution_started", "execution_completed", "execution_denied"],
    "policy": {
      "risk_tier": "high",
      "auth_required": true,
      "approval_required": true
    }
  }],
  "evidence": {
    "store": "local-append-only",
    "append_only": true
  }
}

Invocation

Carry subject, mode, payload, and correlation.

invocation.json

json

{
  "invocation_id": "inv_session_abc_001",
  "capability_id": "schedule_technician",
  "version": "1.0.0",
  "mode": "sync",
  "correlation": { "correlation_id": "session-abc" },
  "subject": { "id": "agent://planning-assistant" },
  "payload": {
    "job_id": "job_456",
    "window": "tomorrow"
  },
  "requested_at": "2026-06-16T15:14:20.000Z"
}

Outcome

Fail closed with a machine-readable result.

outcome.json

json

{
  "invocation_id": "inv_session_abc_001",
  "capability_id": "schedule_technician",
  "capability_version": "1.0.0",
  "correlation": { "correlation_id": "session-abc" },
  "outcome": "denied",
  "success": false,
  "data": null,
  "error": null,
  "denial": {
    "code": "entitlement_denied",
    "message": "service:dispatch is required",
    "retryable": false
  },
  "evidence_ids": ["evt_8f3a1c"],
  "started_at": null,
  "completed_at": "2026-06-16T15:14:22.104Z"
}

Protocol guarantees

Interoperability needs more than a tool schema.

CHP treats malformed inputs, unavailable capabilities, lifecycle violations, authorization failures, and version mismatches as first-class protocol outcomes.

Explore the protocol →

discover

validate

authorize

invoke

record

Manifest-first discovery

Hosts declare identity, capabilities, versions, modes, policy metadata, and evidence behavior before invocation.

Version compatibility

Protocol and capability versions are explicit so agents can fail closed on incompatible surfaces.

Permissioned invocation

Invocation envelopes carry subject identity, correlation context, mode, payload, requested time, and host-enforced policy checks.

Lifecycle enforcement

Unavailable hosts, disabled capabilities, malformed frames, and premature calls are protocol outcomes.

Structured errors

Denials, validation failures, timeouts, and host errors return machine-readable codes and details.

Evidence and replay

Every execution attempt emits ordered evidence for audit, debugging, telemetry, and compliance.

The evidence foundation

Every capability invocation — across any group — runs through the same three-step protocol.

Register

Wrap any function as a capability with a stable ID, version, and description. The host manages the registry.

@capability(id="payments.transfer", version="1.0.0")

Invoke

Call through the host with a correlation ID. Evidence is emitted automatically — started, completed, failed, or denied.

host.invoke("payments.transfer", payload, correlation_id=...)

Replay

Ask the host for the ordered evidence stream for any correlation ID. Every invocation is queryable locally, without a backend.

events = host.replay("session-abc")

Structured evidence, not logs.

Every invocation emits typed evidence events with stable fields: capability ID, version, correlation, sequence, outcome, and timing. Payloads for sensitive keys are redacted by default. The store is queryable by correlation ID without any backend.

SHA256 hash-chained events

Every evidence event includes prev_hash and hash — forming a tamper-detectable chain across the session. No external signing required.

$ chp verify-evidence <session_id>
→ 47 events verified · chain intact

execution_started

execution_completed

execution_failed

execution_denied

evidence event

{
  "event_id": "evt_8f3a1c",
  "event_type": "execution_completed",
  "invocation_id": "inv_session_abc_001",
  "capability_id": "payments.transfer",
  "capability_version": "1.0.0",
  "host_id": "my-host",
  "correlation": { "correlation_id": "session-abc" },
  "sequence": 2,
  "timestamp": "2026-06-03T00:14:22.104Z",
  "outcome": "success",
  "payload": { "duration_ms": 43 },
  "redacted": true,
  "assurance": { "level": "S1" }
}

Minimal example

from chp_core import LocalCapabilityHost, capability

host = LocalCapabilityHost("my-host")

@capability(id="payments.transfer", version="1.0.0", description="Transfer funds.")
def transfer(amount: float, to: str):
    execute_transfer(amount, to)
    return {"status": "ok", "amount": amount}

host.register(transfer)

result = host.invoke(
    "payments.transfer",
    {"amount": 100.0, "to": "acct_456"},
    correlation_id="session-abc",
)

events = host.replay("session-abc")
# → execution_started, execution_completed

Positioning

The boundary between hosted capability and real-world use.

CHP is deliberately narrow: it standardizes how independent systems expose, call, govern, and audit capabilities without choosing the model, framework, cloud, or policy engine for you.

CHP is

A protocol boundary for capabilities exposed by independent hosts.

A manifest, invocation, lifecycle, error, permission, and evidence contract.

A conformance target for hosts, agents, apps, and infrastructure providers.

CHP is not

A model provider, agent framework, workflow engine, or policy vendor.

A replacement for OpenAPI, MCP, OpenTelemetry, or application authorization.

A requirement to centralize every tool behind one runtime or cloud service.

Common objections

Questions a protocol has to answer early.

Why not just use an agent framework tool schema?

Tool schemas describe callable shapes. CHP describes the host boundary around those calls: manifests, versions, availability, permission checks, structured outcomes, and replayable evidence.

Why not just use OpenAPI?

OpenAPI is useful for HTTP APIs. CHP focuses on agent capability hosts where discovery, authorization, lifecycle, invocation results, and evidence must be handled consistently across local, remote, and managed runtimes.

Why not just log everything?

Logs are implementation artifacts. CHP evidence is part of the invocation contract, with stable fields that callers and infrastructure can replay, verify, export, and test.

Who should implement CHP?

Capability hosts, agent frameworks, products that expose reusable abilities, applications that route sensitive work, and infrastructure providers building validation, policy, observability, or conformance layers.

Go deeper.

Read the protocol surface, the conformance model, or the full documentation.

Protocol surface Documentation