Esc
  • SuggestedWhat is HCP?
  • SuggestedBuild a pack
  • SuggestedPack classes
  • SuggestedSpecification
  • SuggestedCLI reference
.md

§1 Terminology

Normative definitions of every object in the protocol, and what each is explicitly not.

On this page

The following terms have the meanings given here throughout this specification.

1.1 Participants#

Harness: The system driving an agent. In HCP the harness is the runtime that installs packs. An MCP server, an agent's instruction file, and a dashboard are not harnesses.

Runtime: The component that loads packs, evaluates grants, mints Binding, executes Adapters, routes Sense, and reports availability. MAY be proprietary. The runtime is an implementation and is distinct from the protocol.

Host: An agent product that adopts HCP and presents pack commands to an agent loop. Examples: an IDE assistant, a coding agent, a tool-loop library. A host invokes the runtime and does not replace it.

Invoker: The party running a command: human, agent, API, or UI. An Invoker carries a Principal. An Invoker MUST NOT redefine Policy or Binding.

Principal: The acting identity on an exec. A runtime concept. Kinds (informative): human, service, agent, mothership. A Principal is never a pack field.

1.2 The unit#

Harness Pack (pack): A directory containing surface.json, policy.json, and HARNESS.md, identified by one pack_id. The install unit. A pack is not a connector, a UI surface, an MCP server, or an agent teaching pack.

Manifest: surface.json. Declares identity, adapter, Binding mode, commands, and optional triggers. The filename is retained for compatibility and does not refer to a UI surface.

Policy: policy.json. One entry per command and per trigger: operation, privacy.land, and optional confirm.

Skill: HARNESS.md. The pack's teaching document. Copied to a SKILL.md on activate.

Pack id (pack_id): The pack's stable identifier. Equal to manifest id and Policy surface_id. surface_id is a legacy alias of pack_id on the wire.

Plane: runtime (end-user capability, default) or control (operator capability). A control-plane pack is a distinct pack.

1.3 The loops#

Execute: The inbound loop: an Invoker runs a command. Announcements that the world changed belong to Sense.

Command: A closed, named operation the pack declares. Identified by verb_key. Manifest map verbs and wire field verb_key are retained names and mean command. A command is not a verb ontology, a PATH wrap, or a mega-command run.

Twin face: The property that a command's CLI form and JSON envelope are the same command under the same Policy, Binding, and Adapter.

Sense: The outbound loop: the pack announces a world change. Pull observation, polling, and uptime monitoring are not Sense.

Trigger (stimulus): One Sense declaration, identified by a stimulus ref. A trigger is not a command, a job table, or an inbox product.

Sink: Where a runtime records delivered triggers. A runtime concept.

1.4 Rules and credentials#

Operation: Policy side-effect class: read or write.

Land: Policy privacy scope: personal (actor-private), brain (shared project context), or local (a local workspace directory). Land is not a tenant id.

Confirm: Policy gate on a write. The runtime MUST refuse the command unless the envelope carries explicit confirmation.

Binding: The credential mode a pack requires and the path by which a runtime mints it. Binding is neither a secret in the pack nor a Principal.

Binding mode: public, user, local, mothership, mock.

Hub: The runtime component that mints credentials. Named in the manifest as keyring, local-credential, public, or none. Its implementation is not an HCP type.

Family: A manifest field grouping packs that share one consent.

Capability: A runtime grant axis: pack.install, pack.connect, verb.exec.read, verb.exec.write, sense.enable.

Tenant / Project: Runtime scope. Tenant comes from the Principal's session; Project is required when land is brain.

1.5 Execution#

Adapter: How a command reaches the world: wrap, composite, openapi, or sense_only. An implementation detail beneath the pack's identity.

Wrap: An Adapter that spawns an existing CLI with a rendered argv.

Pass-through: An HCP/1.1 wrap bootstrap declaring allowedSubcommands and maxArgv. Non-conforming as a destination.

Sandbox: The default execution posture: bin allow-list, cwd jail, no ambient credentials. Native-local is the explicit opt-out.

Envelope: The JSON exec request { pack_id, verb_key, args }.

Result envelope: { ok, pack_id, verb_key, result?, error? }.

1.6 Lifecycle#

Install: Placing a pack in the runtime store.

Activate: Placing an installed pack on a harness session.

Connect: Minting Binding for an activated pack.

Availability: The report of installed, activated, connected, and per-command executable.

Store: The runtime's pack storage. In the reference runtime, $HCP_HOME.

1.7 Projections#

Projection: Any surface generated from a pack: CLI face, JSON face, Skill copy, host tool catalog, MCP export. Projections are derived; the pack is the source of record.

Four faces: CLI, JSON, Skill, and optional MCP. They MUST share verb_key.

1.8 Terms that are not HCP types#

Informative. The following appear in products built on HCP and are explicitly outside the protocol: Connector, tenant id in the pack, inbox ledger, object-sync job, catalog SQL schema, credential hub table names, UI widget catalog, role table, IdP API.