Repository navigation
feat(onboard): add portable capability provisioning contract #8393
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from 2 commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
788516f
feat(onboard): define capability provisioning schemas
apurvvkumaria 0b02076
feat(onboard): resolve portable capability BOMs
apurvvkumaria 780f3db
fix(onboard): stabilize capability BOM ordering
apurvvkumaria 5426d12
merge(main): refresh capability provisioning contract
apurvvkumaria 8c907d6
merge(main): refresh PR #8393
cjagwani 2069d05
merge(main): refresh capability provisioning contract
apurvvkumaria b9c0d6c
merge(main): refresh capability provisioning contract
apurvvkumaria 9499363
merge(main): refresh capability provisioning contract
apurvvkumaria fa609f2
Merge branch 'main' into codex/capability-provisioning-contract
apurvvkumaria ec9f955
merge(main): refresh PR #8393
apurvvkumaria 70b32f1
Merge branch 'main' into codex/capability-provisioning-contract
cv 85c992c
Merge branch 'main' into codex/capability-provisioning-contract
cv File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| <!-- | ||
| SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| SPDX-License-Identifier: Apache-2.0 | ||
| --> | ||
|
|
||
| # Capability provisioning contract | ||
|
|
||
| This internal, dormant contract replaces Dockerfile-shaped customization intent with a portable capability manifest. A trusted catalog resolves requested tools, runtimes, and skills into an exact, secret-free bill of materials (BOM) for one agent and platform. | ||
|
|
||
| The first slice intentionally has no onboarding caller and no runtime-provider implementation. It accepts only digest-pinned OCI artifacts, fixed managed install prefixes, relative `PATH` entries, named policy presets, and catalog-owned dependencies. It does not accept package-manager commands, shell scripts, mutable image tags, credentials, arbitrary destinations, or provider identities. | ||
|
|
||
| A later runtime-provider facet will consume the resolved BOM through explicit supported or unsupported declarations. Docker and candidate Podman must implement and qualify the same facet before the feature becomes user-visible. An MXC-style provider must remain representable without adding a central runtime switch. | ||
121 changes: 121 additions & 0 deletions
121
src/lib/onboard/capability-provisioning/contract.test.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,121 @@ | ||
| // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| // SPDX-License-Identifier: Apache-2.0 | ||
|
|
||
| import { describe, expect, it } from "vitest"; | ||
| import { | ||
| CAPABILITY_CATALOG_SCHEMA_VERSION, | ||
| CAPABILITY_MANIFEST_SCHEMA_VERSION, | ||
| CapabilityProvisioningContractError, | ||
| parseCapabilityCatalogV1, | ||
| parseCapabilityManifestV1, | ||
| } from "./contract"; | ||
|
|
||
| const RUNTIME_DIGEST = "a".repeat(64); | ||
| const TOOL_DIGEST = "b".repeat(64); | ||
|
|
||
| function manifest(capabilities: Array<{ id: string; version: string | null }> = []) { | ||
| return { | ||
| schemaVersion: CAPABILITY_MANIFEST_SCHEMA_VERSION, | ||
| agent: "hermes", | ||
| capabilities, | ||
| }; | ||
| } | ||
|
|
||
| function catalog() { | ||
| return { | ||
| schemaVersion: CAPABILITY_CATALOG_SCHEMA_VERSION, | ||
| capabilities: [ | ||
| { | ||
| id: "rust-runtime", | ||
| displayName: "Rust runtime", | ||
| kind: "runtime", | ||
| version: "1.90.0", | ||
| agents: ["openclaw", "hermes", "langchain-deepagents-code"], | ||
| requires: [], | ||
| policyPresets: [], | ||
| artifacts: [ | ||
| { | ||
| platform: "linux/amd64", | ||
| reference: `oci://ghcr.io/nvidia/nemoclaw-capabilities/rust-runtime@sha256:${RUNTIME_DIGEST}`, | ||
| installPrefix: "/opt/nemoclaw/capabilities/rust-runtime", | ||
| pathEntries: ["bin"], | ||
| }, | ||
| { | ||
| platform: "linux/arm64", | ||
| reference: `oci://ghcr.io/nvidia/nemoclaw-capabilities/rust-runtime@sha256:${TOOL_DIGEST}`, | ||
| installPrefix: "/opt/nemoclaw/capabilities/rust-runtime", | ||
| pathEntries: ["bin"], | ||
| }, | ||
| ], | ||
| }, | ||
| { | ||
| id: "switchyard", | ||
| displayName: "Switchyard", | ||
| kind: "tool", | ||
| version: "2.4.1", | ||
| agents: ["hermes"], | ||
| requires: ["rust-runtime"], | ||
| policyPresets: ["switchyard"], | ||
| artifacts: [ | ||
| { | ||
| platform: "linux/amd64", | ||
| reference: `oci://ghcr.io/nvidia/nemoclaw-capabilities/switchyard@sha256:${TOOL_DIGEST}`, | ||
| installPrefix: "/opt/nemoclaw/capabilities/switchyard", | ||
| pathEntries: ["bin"], | ||
| }, | ||
| ], | ||
| }, | ||
| ], | ||
| }; | ||
| } | ||
|
|
||
| describe("capability provisioning contracts", () => { | ||
| it("rejects duplicate capability requests", () => { | ||
| expect(() => | ||
| parseCapabilityManifestV1( | ||
| manifest([ | ||
| { id: "switchyard", version: null }, | ||
| { id: "switchyard", version: null }, | ||
| ]), | ||
| ), | ||
| ).toThrow(/must not contain duplicates/u); | ||
| }); | ||
|
|
||
| it("rejects mutable artifacts, arbitrary destinations, and executable instructions", () => { | ||
| const mutable = catalog(); | ||
| mutable.capabilities[0]!.artifacts[0]!.reference = | ||
| "oci://ghcr.io/nvidia/nemoclaw-capabilities/rust-runtime:latest"; | ||
| expect(() => parseCapabilityCatalogV1(mutable)).toThrow(/reference has an unsupported format/u); | ||
|
|
||
| const destination = catalog(); | ||
| destination.capabilities[0]!.artifacts[0]!.installPrefix = "/usr/local"; | ||
| expect(() => parseCapabilityCatalogV1(destination)).toThrow( | ||
| /installPrefix has an unsupported format/u, | ||
| ); | ||
|
|
||
| const executable = catalog() as unknown as { capabilities: Array<Record<string, unknown>> }; | ||
| executable.capabilities[0]!.command = "apt-get install rustc"; | ||
| expect(() => parseCapabilityCatalogV1(executable)).toThrow(/must contain exactly/u); | ||
| }); | ||
|
|
||
| it("rejects catalog dependency gaps and cycles", () => { | ||
| const missing = catalog(); | ||
| missing.capabilities[1]!.requires = ["missing-runtime"]; | ||
| expect(() => parseCapabilityCatalogV1(missing)).toThrow(/requires unknown capability/u); | ||
|
|
||
| const cyclic = catalog(); | ||
| cyclic.capabilities[0]!.requires = ["switchyard"]; | ||
| expect(() => parseCapabilityCatalogV1(cyclic)).toThrow(/dependency cycle/u); | ||
| }); | ||
|
|
||
| it("rejects inherited objects and malformed relative path entries", () => { | ||
| const inherited = Object.create({ schemaVersion: CAPABILITY_MANIFEST_SCHEMA_VERSION }); | ||
| inherited.agent = "hermes"; | ||
| inherited.capabilities = []; | ||
| expect(() => parseCapabilityManifestV1(inherited)).toThrow(CapabilityProvisioningContractError); | ||
|
|
||
| const traversal = catalog(); | ||
| traversal.capabilities[0]!.artifacts[0]!.pathEntries = ["../bin"]; | ||
| expect(() => parseCapabilityCatalogV1(traversal)).toThrow(/pathEntries\[0\]/u); | ||
| }); | ||
| }); |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.