agent-capabilities

Agent Capabilities

Maintain three related artifacts:

• agent-capabilities.json is the installed consumer contract: curated keys, versions, digests, status, evolution, typed C++ bindings, and partial-coverage semantics.
• agent-capability-surface.json is the maintenance ledger: every public header in the covered roots, its byte fingerprint, and its reviewed disposition.
• tools/agent-capabilities/contract-history.json is the repository-only, append-only evolution history checked against the protected Git tip. Shallow GitHub Actions checkouts fetch the immutable event base SHA when necessary.

The consumer manifest, its schema, and the handoff schema install into the SDK. Official release packaging stamps agent-capability-handoff.json only after installation; it binds the exact SDK source SHA and platform to the installed importer's SHA-256 plus the installed manifest's exact content and byte hash. The release archive verifier must require and revalidate that identity at the configured capability-handoff floor. The surface ledger, surface schema, legacy baseline, and contract history are maintenance artifacts and must not be installed.

When adding an installed SDK library in PulpInstallRules.cmake, register its archive stem in release_product_matrix.json and classify every newly covered public header here in the same change. A successful CMake export alone does not prove the release archive or installed agent-capability contract is complete.

Keep both separate from the unified runtime control platform. This contract may describe what an SDK can design or generate; it must never contain runtime operations, grants, policy, risk decisions, instances, activation, sessions, revocation, or receipts.

pulp authority list|query is the routing-only navigator across this and the other bounded machine authorities. For design-time capability questions it must point to agent-capabilities.json and this manifest checker; it must not copy capability rows into authority-navigation.json, treat an absent key as unsupported, or infer any live state. In a source checkout it binds its answer to the checkout registry. In a downstream project it resolves the exact SDK selected by pulp.toml without materializing it; otherwise an SDK-installed CLI may bind to its adjacent share/pulp/authority-navigation.json. Source-only routes report unavailable, and a missing selected SDK never falls back to another installed version. The standalone CLI-only release archive has no SDK registry and must fail clearly rather than search another checkout or SDK. A reported query_or_validator is descriptive guidance only and is never executed by the navigator.

The installed SDK also ships canonical runtime-control headers, CMake helpers, and control-authoring examples. Their presence in the same install tree does not make them agent-capability rows: keep runtime-control operations and policy out of agent-capabilities.json, and keep the capability surface ledger focused on the design-time public-header contract.

The A3 GPU startup-health surface is a concrete example. The installed ControlGpuHealthProvider, ControlGpuHealthViewAdapter, ControlGpuHealthReadExecutor, and pulp.gpu-health-read-result.v1 types are runtime control plumbing. Do not add dev.pulp.gpu/health.read@1, its grants, instances, receipts, measurement campaigns, or B4 disposition to agent-capabilities.json. A public-header ledger classification, where one is required by the covered roots, records only that the header was reviewed; it must not turn this runtime operation into a generator-facing design capability. The checkout-only gpu_first_visible_a3_campaign.py runner is also runtime acceptance tooling, not an installed SDK capability: do not add its adapter request/receipt schemas, 10+10 lifecycle ledger, or source-binding receipt to the design-time capability catalog.