Agent Hub Demo

Agent Hub Demo is a small reference project for shipping a KFD-compatible Agent Hub as Buildchain-managed standalone binaries.

This branch migrates to exactly two workflow callers: buildchain.yml for normal delivery and buildchain-recover.yml for recovery of an exact attempt. Product commands, archive outputs and protected channel routes are declared in buildchain.toml.

Signed publication is blocked upstream. The published Buildchain 4.1.3 dual-entry contract does not yet deliver native signing/finalization evidence. Linux x64 still requires a detached signature, macOS arm64 still requires Developer ID signing and notarization, and Windows x64 retains its explicit unsigned exception. The verifier rejects absent evidence before packaging; this migration is not proof of a new release. See release qualification and migration blockers.

The implementation uses two independent Hubs backed by separate file-based content-addressed stores. KFD enters through the public npm package at build time; its exact public profile facts are embedded into the executables, so released binaries do not require Node.js, npm, a source checkout, or private packages.

The repository is deliberately small, but the implementation is real. Each Hub owns a distinct Ed25519 identity, capability document, content-addressed store, admission state, revocation set, and export bundle. The file binding records transport receipts while the Hub keeps delivery, admission, and completion as independent facts.

Animation scenario:

$ agent-hub-demo demo --root ./agent-hub-demo-run --output ./agent-hub-demo-run/report.json --presentation

Native renditions: 1080p MP4 · 1080p WebM · 720p MP4 · 720p WebM

Static poster / reduced-motion fallback

Existing GitHub Releases provide the executable for your platform. Download and run:

./agent-hub-demo-linux-x64 self-describe --json
./agent-hub-demo-linux-x64 self-verify --json
./agent-hub-demo-linux-x64 demo --root .demo/release

On Windows, use agent-hub-demo-windows-x64.exe; on macOS, use agent-hub-demo-macos-arm64.

Building from source requires Node.js 24 or newer and npm:

git clone https://github.com/kungfu-systems/agent-hub-demo.git
cd agent-hub-demo
npm ci --registry=https://registry.npmjs.org/
npm run check
npm run demo

npm run demo creates a new ignored .demo/ run. The printed report shows:

• Hub A and Hub B capability documents and roots;
• admitted Fact and Episode objects;
• an idempotent duplicate and a visible semantic conflict;
• rejected authority amplification, expiry, revocation, unknown required features, and disclosure-state conflation;
• a verified export/import recovery and a rejected drifted bundle;
• distinct delivery, object, verdict, and completion state.

Run the product-local 100-delivery soak separately:

npm run runtime100

This soak does not replace or qualify the separate KFD Runtime 100 profile.

Run the public Buildchain first-class Agent Hub gate separately:

node node_modules/@kungfu-tech/buildchain/bin/buildchain.mjs kfd hub test --for agent

The gate reads .buildchain/kfd/agent-hub.json, runs the fixed public KFD Hub suite against the real adapter, and writes its lock and verified report under .buildchain/artifacts/kfd-agent-hub/. The local verifier is the public npm CLI pinned in package-lock.json. Hosted orchestration remains owned by the standard Buildchain v4 entrypoints.

Run the release qualification after that positive gate:

npm run qualify:release

The qualification oracle performs twelve deliberate offline mutations across the declaration, adapter artifact, report and roots, policy scope, and export/import result. Every case must fail closed with a stable machine error and an explicit owner, evidence pointer, and next action. See docs/RELEASE_QUALIFICATION.md.

The source CLI and released binary expose the same public KFD Agent Hub JSONL stdio envelopes:

node src/adapter.js inspect
node src/adapter.js jsonl --root .demo/adapter
./agent-hub-demo-linux-x64 adapter inspect
./agent-hub-demo-linux-x64 adapter jsonl --root .demo/adapter-binary

Example handshake request:

{"schemaVersion":1,"contract":"kfd.agent-hub-adapter-request/v1","requestId":"hello","operation":"handshake","input":{}}

Each response is one kfd.agent-hub-adapter-response/v1 JSON object on stdout. Adapter inspection and the Hub capability documents are computed from the same live implementation, so their roots can be checked rather than copied.

This repository is a first-party clean-room consumer and a structural- independence witness. It demonstrates that a builder-owned product can use the public KFD package, a public black-box adapter boundary, and Buildchain without depending on Kungfu Core, private packages, local paths, Git submodules, a copied KFD evaluator, or private Buildchain scripts.

The reference release demonstrates three bounded adoption layers:

• KFD-1 binds every platform executable and product contract artifact byte-for-byte to its release-candidate evidence;
• KFD-2 publishes the explicit structural-independence claim, responsibility, exclusions, and residual risk;
• KFD-3 declares the participant-facing CLI plus its three-platform distribution tasks and artifacts.

The new product packaging command preserves executable and KFD evidence bytes in one platform archive. The executable remains under dist/ after extraction. Existing published releases retain their original assets and Release Passports; this branch has not qualified a new hosted release or Passport. Signature and KFD verification must pass before npm run package:product is reached.

It is not KFD certification, a production security assessment, independent vendor adoption, plural-vendor interoperability, or proof of production fitness. The file binding is the tested transport in this release; HTTP and hosted operation are outside the current claim.

• docs/MAP.md routes product users and reviewers.
• docs/versioning.md records the Buildchain release line and version-impact decisions.
• CONTRIBUTING.md covers local development and DCO.
• .buildchain/kfd/agent-hub.json is the one builder-owned adoption declaration.
• .buildchain/kfd/kfd-2/registry.json declares the limited public release claim and residual risk.
• .buildchain/kfd/kfd-3/surfaces.json declares the CLI and cross-platform distribution surface.
• .buildchain/auditable-demo.json declares the retained standalone-binary animation scenario. Existing media above is historical evidence; automatic regeneration is not wired into the two callers.
• scripts/build-binary.mjs owns the per-platform Node SEA build and binary smoke checks.
• scripts/package-product.mjs assembles each product archive with an explicit evidence inventory.
• src/hub.js is the product implementation.
• src/adapter.js is the black-box KFD adapter.

Apache-2.0. See LICENSE. Project names and marks are addressed in TRADEMARK.md.