KFD Agent Hub Conformance Profile

Five-minute packaged quickstart

Pin the prerelease channel explicitly because npm latest remains the bootstrap package. One command runs the packaged state-machine reference adapter against Hub 20, writes a rooted report, re-hashes the adapter, and verifies the report offline:

npx --yes --package @kungfu-tech/kfd@alpha kfd demo agent-hub \
  --output ./agent-hub-demo-report.json

Inspect the machine-readable command, language, exit-code, verifier-backend, claim, and recovery boundaries without a repository checkout:

npx --yes --package @kungfu-tech/kfd@alpha kfd capabilities agent-hub --json

The demo is an executable reference path, not adopter evidence. Its packaged adapter is non-product code and its passing report remains non-qualifying and non-certifying.

Verify the first-party Kungfu product

Kungfu ships this exact KFD package and exposes the fixed suite through its installed executable. A human or agent can run the product-owned semantics without a KFD repository checkout or a separate Node installation:

kungfu agent hub qualify --output-dir ./kungfu-agent-hub-check
kungfu agent hub verify --qualification-dir ./kungfu-agent-hub-check

The default projection says what passed, which responsibilities were exercised, what the result means, what it does not mean, whether the real ~/.kungfu state stayed unchanged, and where the rooted JSON evidence was written. Add --json for the stable machine projection.

KFD remains the authority for the fixed Hub 20 suite and offline report verifier. Kungfu remains the authority for its product semantics, two isolated local Hub domains, installed-artifact binding, and explanatory projection. A pass is exact-scope first-party product evidence; it is not KFD certification, a security assessment, production fitness, remote-network interoperability, or external adoption.

Scaffold an adopter adapter

Generate exactly one new starter directory:

npx --yes --package @kungfu-tech/kfd@alpha kfd scaffold agent-hub \
  --language python \
  --output ./my-agent-hub-adapter

Languages are cpp, node, python, and rust. KFD refuses an existing output path and never overwrites adopter files. Each starter has deterministic fixtures and a local envelope smoke; the smoke explicitly does not execute Hub 20. Implement product-owned semantics, build when required, and then run the fixed suite.

Run the fixed suite against an adopter

An adapter is an executable or JavaScript entry point that reads one JSON request per line from stdin and writes exactly one JSON response per line to stdout. It must answer one handshake plus the fixed 20 evaluation requests.

npx --yes --package @kungfu-tech/kfd@alpha kfd test agent-hub \
  --adapter ./my-agent-hub-adapter.mjs \
  --output ./agent-hub-report.json

npx --yes --package @kungfu-tech/kfd@alpha kfd verify agent-hub-report \
  ./agent-hub-report.json \
  --adapter ./my-agent-hub-adapter.mjs \
  --json

Omitting --adapter during verification still verifies the installed package cut, profile, protocol, suite, failure inventory, verifier, capability documents, responses, result closure, transcript root, and claim boundary. Supplying it additionally re-hashes the adapter bytes.

Fixed boundaries

• Profile: kfd-agent-hub-conformance@0.1.0-alpha.1
• Protocol: kfd-agent-hub@0.1.0-alpha.1
• Suite: kfd-agent-hub-20@0.1.0-alpha.1, exactly 20 vectors
• Report: kfd.agent-hub-report/v1
• Offline verifier result: kfd.agent-hub-report-verifier/v1
• Exit 0: pass or valid report; exit 1: completed but failed; exit 2: invalid invocation, JSON, adapter process, or envelope

The suite distinguishes transport delivery from semantic admission, preserves visible conflict, rejects authority amplification and root drift, and retains unavailable and intentionally withheld knowledge as different states.

Claim boundary

A passing report is exact-scope evidence for the named adapter artifact, two declared Hub capability documents, fixed suite, installed KFD package cut, platform, and retained residual risks. It is not KFD certification, a security assessment, production fitness, independent vendor adoption, or evidence that provisional semantics became normative.

KFD Runtime 100 remains a separate single-runtime evidence profile. Its 35 Core vectors cover a KFD-7 responsibility-separation subset; its 65 Experimental vectors are provisional and non-qualifying. Agent Hub 20 tests cross-Hub exchange behavior and does not replace Runtime 100.

See implementer-guide.md for the adapter and report workflow.

Executable onboarding surfaces

• kungfu agent hub qualify --output-dir <new-directory> runs the fixed suite against the product-owned Kungfu Hub implementation and explains the exact result to a human; --json exposes the same bounded result to an agent.
• kungfu agent hub verify --qualification-dir <directory> independently rechecks the retained KFD report, adapter bytes, product binding, and qualification closure without rerunning the suite.
• kfd demo agent-hub --output <report.json> runs one packaged reference adapter, executes Hub 20, and immediately performs bound offline verification.
• kfd scaffold agent-hub --language <cpp|node|python|rust> --output <new-directory> copies a deterministic, fail-closed starter without overwriting an existing path.
• kfd capabilities agent-hub --json exposes commands, contracts, exit codes, supported scaffold languages, verification backend, claim boundary, and recovery as packaged JSON.
• kfd test agent-hub --adapter ... remains the adopter evidence path. Demo and scaffold smoke results do not substitute for it.

The C++ and Rust starters deliberately use fixture-scoped, dependency-free JSON field readers so clean-pack CI can compile them offline. Adopters must replace those readers with their production JSON boundary. Node.js and Python starters use their standard JSON libraries. All four starters return scenario-not-implemented until product-owned semantics are supplied.

Adapter binding

The binding is jsonl-stdio/v1. The runner starts one process with KFD_AGENT_HUB_OFFLINE=1, preserves the caller’s working directory, sends 21 lines, closes stdin, and requires 21 JSON response lines with no stderr output. Package resources are resolved from the installed KFD package; adopter configuration may remain relative to the consumer project.

The first request has operation handshake. A successful response uses code adapter-ready, verdict not-applicable, and includes at least two Hubs. Every Hub entry contains a capability document and its canonical SHA-256 semantic root. Hub IDs must be unique.

The remaining requests use operation evaluate. An adapter must return the exact request ID plus status, code, verdict, and observations. Machine interpretation always uses the three-field outcome, not the code alone. In particular:

• conflicted / conflict-visible / conflicted means the adapter correctly retained a visible conflict.
• rejected / conflict-visible / rejected means the adapter correctly rejected a policy that would hide a visible conflict.

Both are negative-polarity vectors because neither claims semantic admission.

Reports and roots

The runner binds:

• the installed npm package manifest and release anchor;
• the conformance and protocol manifests;
• the fixed vector registry and failure inventory;
• the verifier and adapter bytes;
• two or more Hub capability documents;
• every adapter response, the complete result inventory, and the reconstructed transcript.

Roots use SHA-256. File roots hash the exact packaged bytes. Semantic roots hash canonical JSON followed by one newline; object keys are sorted recursively, array order is retained, and numbers are non-negative safe integers.

Fail-closed verification

The offline verifier independently recomputes public package roots and fixed-suite outcomes. Unknown, missing, duplicate, or mutated results fail. Claim widening (qualifying: true or certification: true) fails. A report may be valid only when all 20 fixed outcomes pass and the entire root closure agrees.

Use --adapter during verification when the original adapter bytes are available. This turns the declared adapter digest into a recomputed check.

Agent Hub report verification remains in the single packaged host-side JavaScript verifier. No Agent Hub report checks are duplicated in the Rust/WASM verifier, so there is no partial parity set that could drift. This boundary is machine-readable in cli-capabilities.json and checked by the profile test. Process spawning is also host-only. Moving report semantics into the shared core requires a new versioned verification-bundle kind and byte-for-byte native/WASM parity before this host authority can be retired.

Starter claim and recovery

Every generated kfd-scaffold.json lists what its smoke executes and what remains untested. A starter must not be described as a conforming Hub until its compiled or interpreted adapter itself passes the retained Hub 20 runner. To recover from generation, remove only the newly generated directory; generation never mutates an existing destination. Reports are created with exclusive-write semantics and are safe to regenerate only at a new path or after the adopter intentionally removes its own prior report.

Reference adapters

The package includes two intentionally different examples:

• profiles/agent-hub/adapters/state-machine-adapter.mjs
• profiles/agent-hub/adapters/rule-table-adapter.mjs

They demonstrate the wire contract, not a production Hub implementation.