SDK

@harnesscontextprotocol/sdk (TypeScript, ESM, Zod schemas) is the reference implementation of the Specification, and the spec governs wherever the two differ. Most hosts need only the Hcp facade to load, activate and run packs, and the sections after it list the lower-level exports.

bun add @harnesscontextprotocol/sdk

The package is a private preview on GitHub Packages, and Install the CLI shows the .npmrc it needs.

Hcp facade#

import { Hcp } from '@harnesscontextprotocol/sdk'

const hcp = await Hcp.create({
  packDirs: ['./packs/transit', './packs/ledger'],
  sandbox: true,
  grants: [{ capability: 'verb.exec.read' }],
  principal: { id: 'u_1', kind: 'human' },
  tenant_id: 't_1',
  project_id: null,
})

await hcp.activate(['transit'])
const res = await hcp.exec('transit', 'plan', { from: 'Zurich', to: 'Bern' })

Hcp.create(opts): Promise<Hcp>#

Methods#

Runtime drivers#

type HcpRuntimeDriver = {
  id: string
  kind: 'reference-local' | 'proprietary-stub' | string
  listPacks(): Promise<LoadedHcpPack[]>
  getPack(pack_id: string): Promise<LoadedHcpPack | null>
  connect?(pack_id: string, authz: HcpAuthzContext): Promise<{ ok: boolean; error?: string }>
  exec(args: {
    pack_id: string; verb_key: string; args?: Record<string, unknown>
    authz: HcpAuthzContext; sandbox: HcpSandboxMode
    approval?: HcpHostApproval
  }): Promise<HcpExecResult>
}

• createReferenceLocalRuntime({ packDirs, allowBins?, projectDir?, access?, approvals?, audit?, views? }) runs wrap and composite adapters with a process allow-list, a cwd jail, and HCP_SANDBOX set in the child, implementing the pipeline in §6.3.
• createProprietaryStubRuntime({ packs, grants, principal, access?, approvals?, audit?, views? }) runs the same authorization pipeline with a stubbed adapter step, as the starting point for a hosted runtime (Build runtimes).

Both come wrapped in access control. Hcp.create({ runtime: myDriver }) wraps your own driver the same way.

type HcpExecResult = {
  ok: boolean; pack_id: string; verb_key: string
  result?: unknown; error?: string; stdout?: string; stderr?: string
  code?: string                // stable reason when ok is false: unknown_argument, confirm_required, …
  hint?: string                // what to do next, written for an agent
  preview?: { command: string; args: Record<string, unknown>; cli?: string }   // on confirm_required
  approval?: HcpApprovalRequest                                                 // on confirm_required
  approval_id?: string
  access?: { mode: string; reason: string; approvals: string }
}

Loading and linting#

type LoadedHcpPack = {
  pack_id: string; dir: string
  manifest: HcpPackManifest; policy: HcpPolicyFile
  harness_md: string; harness_present: boolean
  adapter_kind: HarnessAdapterKind; binding?: HarnessBinding; wrap?: HarnessWrapTarget
  verb_keys: string[]
}

Schemas#

These Zod schemas validate input and generate JSON Schema:

HarnessPackMetaSchema, HarnessBindingSchema, HarnessAdapterKindSchema, HarnessWrapTargetSchema, HarnessPassThroughSchema, HarnessOpenApiRefSchema, HcpPolicyFileSchema, HcpPolicyEntrySchema, HcpPolicyOperationSchema, HcpPrivacyLandSchema.

The constants are HCP_PROTOCOL_ID = 'hcp' and HCP_VERSION = 1, and Schemas prints the JSON Schema generated from them.

Grants#

const HCP_CAPABILITIES = ['pack.install', 'pack.connect', 'verb.exec.read', 'verb.exec.write', 'sense.enable'] as const

type HcpGrant = { capability: HcpCapability; pack_id?: string; verb_keys?: string[] }
type HcpPrincipal = { id: string; kind: 'human' | 'service' | 'agent' | 'mothership' }
type HcpAuthzContext = { principal: HcpPrincipal; tenant_id: string; project_id: string | null; grants: HcpGrant[] }
type HcpAuthorize = (ctx: HcpAuthzContext, req: HcpExecRequest) => HcpAuthzDecision

defaultAuthorize implements §9.4 and §9.5: land brain requires project_id, the Policy operation picks the capability, and grant matching narrows by pack_id and then by verb_keys. permissiveGrants() returns one unscoped grant per capability.

Access and approvals#

These exports implement the access layer of draft RFC 0006 and the approval options of draft RFC 0007, and Access explains the behaviour.

Command titles#

Titles explains how a pack declares them.

Check and eval#

The check entry point exposes hcpx check and hcpx eval as functions:

import { checkPack, formatCheckForAgent, initEvalFile } from '@harnesscontextprotocol/sdk/check'

await initEvalFile('./packs/gh')                    // { written, file, cases }; never overwrites
const report = await checkPack('./packs/gh', { probe: true })
if (!report.ok) console.log(formatCheckForAgent(report))

type EvalCase = {
  name: string
  verb: string
  args?: Record<string, unknown>
  expect?: { ok?: boolean; error?: string; contains?: string[]; not_contains?: string[]
             json?: boolean; max_ms?: number; max_tokens?: number }
}

Check and evaluate lists the rules and how cases are graded.

Availability#

buildPackAvailability({ pack, installed, activated, connected, grants, source_available }) returns HcpPackAvailability with a per-command executable and a reason (not installed, not activated, missing <capability>). hcpx availability is built on it.

Generation and adoption#

Host intake#

A host that consumes a generated surface manifest, and does not embed the runtime, uses loadSurfaceManifest(cwd), loadHostIntake(cwd, opts?), resolveSurfaceTool(manifest, toolName) and execVerbViaCli(pack_id, verb_key, { args, cli, home, cwd }). The last runs hcpx exec, or the command in cli, and parses the JSON, failing with non-json cli output when stdout is not JSON.

HarnessAgent#

import { HarnessAgent } from '@harnesscontextprotocol/sdk'

const agent = await HarnessAgent.create({
  runtime: 'ai-sdk', model, packDirs: ['./packs/transit'],
  grants: [{ capability: 'verb.exec.read' }],
})
for await (const ev of agent.run('Plan Zurich → Bern at 9')) { … }

AI SDK covers the options, the events and the approval flow.

Store helpers#

resolveHcpHome(env?), ensureHcpHome(), ensureBootstrapPack(dir, layout), installPackFromDir(src, layout), uninstallPack(id, layout), listInstalledPackDirs(layout), readCliState(layout), writeCliState(state, layout) and installPackSkill(pack, layout) back the CLI store.

Deprecated aliases#

Systems* policy schema names and parseSystemsSurfacePolicyFile / lintSystemsSurfacePolicy remain exported and map to their Hcp* equivalents.