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

Expected result: command exit 0, behavior 20/20, evidence valid, qualifying=false, and certification=false. The demo is an executable reference path, not adopter evidence. Its packaged adapter is non-product code.

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, two structurally complete rooted capability documents, and a local envelope smoke.

Before you implement Hub semantics, the expected result is deliberately:

Scaffold            exit 0
Smoke               exit 0
Hub behavior        exit 1, 0/20, report.valid=false
Evidence verify     exit 0, verification.valid=true, adapter bytes checked
Authority           qualifying=false, certification=false

The smoke proves only that the process and JSONL envelope work. Hub 20 then produces a trustworthy negative baseline rather than pretending that the starter is a working Hub.

Implement Hub semantics

“Hub semantics” means the product decisions made inside evaluate(): whether each request is admitted, rejected, conflicted, or retained as unavailable, and which stable code and verdict explain that result. The fixed 20 scenarios protect eight user-visible boundaries:

• negotiation: exact profile and capability agreement;
• delivery: receipts, admission, duplicates, and idempotency;
• authority: attenuation, amplification rejection, and revocation;
• conflict: conflicts remain visible instead of being silently erased;
• knowledge: causal gaps, disclosure limits, and unavailable facts stay distinct;
• completion: settlement requires sufficient proof;
• recovery: reconnect does not revive invalid authority;
• portability: the same semantic outcomes survive implementation and topology changes.

Start in the generated adapter file (adapter.py, adapter.mjs, src/main.rs, or adapter.cpp). Preserve the request/response envelope and rooted capability documents, replace the fail-closed scenario-not-implemented branch, and use the per-category report counts to advance from 0/20 to 20/20.

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

On an untouched starter, test is expected to exit 1 with 0/20; after all fixed semantics are implemented it exits 0 with 20/20. In both cases it writes a report. The verifier answers a different question: it exits 0 when that report’s evidence closure is valid, even if behavior is 0/20. Add --json only when a machine needs the complete structured result.

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
• Scaffold and smoke exit 0 when generation and the local envelope succeed.
• Test exits 0 only at 20/20; a completed run below that threshold exits 1 and still writes its report.
• Verify exits 0 when report evidence is internally valid; this does not mean behavior passed.
• Exit 2 means invalid invocation, unsafe path, malformed JSON, adapter process failure, or envelope failure.

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 20/20 report is exact-scope behavior evidence for the named adapter artifact, two declared Hub capability documents, fixed suite, installed KFD package cut, platform, and retained residual risks. A verifier result of valid means those recorded facts and roots close; it does not change 0/20 into a pass. Neither result is 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.

An untouched starter is a supported negative state, not a broken product: smoke exits 0, Hub 20 exits 1 at 0/20, and bound offline verification exits 0 with valid: true. Qualification and certification remain false throughout.

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.

Report verification

The offline verifier independently recomputes public package roots, capability roots, fixed-suite outcomes, response roots, result closure, transcript root, and claim boundary. Unknown, missing, duplicate, or mutated results fail. Claim widening (qualifying: true or certification: true) fails.

Verifier validity is evidence validity, not behavior conformance. A structurally sound 0/20 starter report verifies successfully because it truthfully records all 20 failed outcomes. A 20/20 report also verifies successfully when the same evidence closure agrees. The CLI therefore presents three lines:

Behavior: 0/20 (not conforming)
Evidence: valid (adapter bytes checked)
Authority: qualifying=false; certification=false

Use --json for the complete machine result. Its dimensions.behavior, dimensions.evidence, and dimensions.authority fields preserve the same separation.

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, the expected 0/20 negative baseline, evidence-verification result, and authority boundary. 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.