agentskills-oci 0.8.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agentskills-oci
|
|
3
|
+
Version: 0.8.0
|
|
4
|
+
Summary: OCI registry provider for the Agent Skills format (https://agentskills.io)
|
|
5
|
+
License: MIT
|
|
6
|
+
Author: Pratik Panda
|
|
7
|
+
Requires-Python: >=3.12,<4.0
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
16
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
17
|
+
Requires-Dist: agentskills-core (>=0.8.0,<1.0)
|
|
18
|
+
Requires-Dist: oras (>=0.2.43,<0.3)
|
|
19
|
+
Requires-Dist: requests (>=2.31,<3.0)
|
|
20
|
+
Project-URL: Homepage, https://agentskills.io
|
|
21
|
+
Project-URL: Repository, https://github.com/pratikxpanda/agentskills-sdk
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
title: agentskills-oci
|
|
26
|
+
description: Read Agent Skills from OCI Distribution registries
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
Read-only OCI distribution support for progressive, digest-verified Agent
|
|
30
|
+
Skills files. Each skill occupies one registry tag. Its OCI image manifest uses
|
|
31
|
+
`application/vnd.agentskills.skill.v1` as `artifactType`, and each canonical
|
|
32
|
+
file is a raw layer labeled with `org.opencontainers.image.title`.
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pip install agentskills-oci
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Requires Python 3.12 or newer. The dependency is the ORAS Python SDK. You do not need the
|
|
41
|
+
separate ORAS CLI to read skills with this provider.
|
|
42
|
+
|
|
43
|
+
## Read Skills
|
|
44
|
+
|
|
45
|
+
The repository must already contain skill artifacts in the format described below. Replace
|
|
46
|
+
the repository and skill ID with yours:
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
import asyncio
|
|
50
|
+
|
|
51
|
+
from agentskills_oci import OCISkillProvider
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
async def main() -> None:
|
|
55
|
+
async with OCISkillProvider("ghcr.io/acme/skills") as provider:
|
|
56
|
+
print(await provider.discover())
|
|
57
|
+
print(await provider.list_files("incident-response"))
|
|
58
|
+
print(await provider.read_file("incident-response", "SKILL.md"))
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
asyncio.run(main())
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Discovery and listing fetch tags and manifests, not file layers. `read_file` downloads only
|
|
65
|
+
the requested layer and verifies its size and SHA-256 digest. The provider caches manifests
|
|
66
|
+
per instance, so use immutable tags or recreate the provider when updating a source.
|
|
67
|
+
|
|
68
|
+
## Artifact Format
|
|
69
|
+
|
|
70
|
+
This provider is read-only. Publishing is handled by your registry tooling, which must produce
|
|
71
|
+
the following format. An arbitrary container image or a default ORAS file push is not sufficient.
|
|
72
|
+
|
|
73
|
+
| Field | Required value |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| Tag | Skill ID, such as `incident-response` |
|
|
76
|
+
| `schemaVersion` | `2` |
|
|
77
|
+
| Manifest `mediaType` | `application/vnd.oci.image.manifest.v1+json` |
|
|
78
|
+
| Manifest `artifactType` | `application/vnd.agentskills.skill.v1` |
|
|
79
|
+
| Manifest title annotation | `org.opencontainers.image.title` must equal the tag |
|
|
80
|
+
| Layer `mediaType` | `application/vnd.agentskills.file.v1` for every file |
|
|
81
|
+
| Layer title annotation | Relative POSIX path, such as `SKILL.md` or `references/guide.md` |
|
|
82
|
+
| Layer descriptor | Exact byte size and `sha256:` digest of the uploaded file |
|
|
83
|
+
|
|
84
|
+
Include `SKILL.md` as a layer and preserve its original YAML frontmatter and body. Duplicate
|
|
85
|
+
paths, traversal, missing skill files, unsupported digests, and oversized descriptors are rejected.
|
|
86
|
+
Defaults are 512 files, 10 MiB per file, and 16 MiB declared total size per skill. Configure
|
|
87
|
+
`max_files`, `max_file_bytes`, and `max_total_bytes` in the constructor.
|
|
88
|
+
|
|
89
|
+
## Authentication and Cleanup
|
|
90
|
+
|
|
91
|
+
ORAS uses its token auth backend and local Docker-compatible credentials by
|
|
92
|
+
default. Pass a configured ORAS client for other registry auth, TLS, or signing
|
|
93
|
+
controls. Layer descriptors are checked against the fetched bytes. Registry
|
|
94
|
+
digests establish consistency, not publisher identity. Use the core trust
|
|
95
|
+
policy after capturing a complete skill snapshot when publisher verification
|
|
96
|
+
is required.
|
|
97
|
+
|
|
98
|
+
The async context manager closes the HTTP session only when the provider created the ORAS
|
|
99
|
+
client. Injected clients remain caller-owned. TLS verification is enabled by default. Keep
|
|
100
|
+
`insecure=False` and `tls_verify=True` for production registries.
|
|
101
|
+
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: agentskills-oci
|
|
3
|
+
description: Read Agent Skills from OCI Distribution registries
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Read-only OCI distribution support for progressive, digest-verified Agent
|
|
7
|
+
Skills files. Each skill occupies one registry tag. Its OCI image manifest uses
|
|
8
|
+
`application/vnd.agentskills.skill.v1` as `artifactType`, and each canonical
|
|
9
|
+
file is a raw layer labeled with `org.opencontainers.image.title`.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pip install agentskills-oci
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Requires Python 3.12 or newer. The dependency is the ORAS Python SDK. You do not need the
|
|
18
|
+
separate ORAS CLI to read skills with this provider.
|
|
19
|
+
|
|
20
|
+
## Read Skills
|
|
21
|
+
|
|
22
|
+
The repository must already contain skill artifacts in the format described below. Replace
|
|
23
|
+
the repository and skill ID with yours:
|
|
24
|
+
|
|
25
|
+
```python
|
|
26
|
+
import asyncio
|
|
27
|
+
|
|
28
|
+
from agentskills_oci import OCISkillProvider
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
async def main() -> None:
|
|
32
|
+
async with OCISkillProvider("ghcr.io/acme/skills") as provider:
|
|
33
|
+
print(await provider.discover())
|
|
34
|
+
print(await provider.list_files("incident-response"))
|
|
35
|
+
print(await provider.read_file("incident-response", "SKILL.md"))
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
asyncio.run(main())
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Discovery and listing fetch tags and manifests, not file layers. `read_file` downloads only
|
|
42
|
+
the requested layer and verifies its size and SHA-256 digest. The provider caches manifests
|
|
43
|
+
per instance, so use immutable tags or recreate the provider when updating a source.
|
|
44
|
+
|
|
45
|
+
## Artifact Format
|
|
46
|
+
|
|
47
|
+
This provider is read-only. Publishing is handled by your registry tooling, which must produce
|
|
48
|
+
the following format. An arbitrary container image or a default ORAS file push is not sufficient.
|
|
49
|
+
|
|
50
|
+
| Field | Required value |
|
|
51
|
+
| --- | --- |
|
|
52
|
+
| Tag | Skill ID, such as `incident-response` |
|
|
53
|
+
| `schemaVersion` | `2` |
|
|
54
|
+
| Manifest `mediaType` | `application/vnd.oci.image.manifest.v1+json` |
|
|
55
|
+
| Manifest `artifactType` | `application/vnd.agentskills.skill.v1` |
|
|
56
|
+
| Manifest title annotation | `org.opencontainers.image.title` must equal the tag |
|
|
57
|
+
| Layer `mediaType` | `application/vnd.agentskills.file.v1` for every file |
|
|
58
|
+
| Layer title annotation | Relative POSIX path, such as `SKILL.md` or `references/guide.md` |
|
|
59
|
+
| Layer descriptor | Exact byte size and `sha256:` digest of the uploaded file |
|
|
60
|
+
|
|
61
|
+
Include `SKILL.md` as a layer and preserve its original YAML frontmatter and body. Duplicate
|
|
62
|
+
paths, traversal, missing skill files, unsupported digests, and oversized descriptors are rejected.
|
|
63
|
+
Defaults are 512 files, 10 MiB per file, and 16 MiB declared total size per skill. Configure
|
|
64
|
+
`max_files`, `max_file_bytes`, and `max_total_bytes` in the constructor.
|
|
65
|
+
|
|
66
|
+
## Authentication and Cleanup
|
|
67
|
+
|
|
68
|
+
ORAS uses its token auth backend and local Docker-compatible credentials by
|
|
69
|
+
default. Pass a configured ORAS client for other registry auth, TLS, or signing
|
|
70
|
+
controls. Layer descriptors are checked against the fetched bytes. Registry
|
|
71
|
+
digests establish consistency, not publisher identity. Use the core trust
|
|
72
|
+
policy after capturing a complete skill snapshot when publisher verification
|
|
73
|
+
is required.
|
|
74
|
+
|
|
75
|
+
The async context manager closes the HTTP session only when the provider created the ORAS
|
|
76
|
+
client. Injected clients remain caller-owned. TLS verification is enabled by default. Keep
|
|
77
|
+
`insecure=False` and `tls_verify=True` for production registries.
|
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
"""Read Agent Skills stored as per-file OCI artifact layers."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import hashlib
|
|
7
|
+
import re
|
|
8
|
+
import threading
|
|
9
|
+
from copy import deepcopy
|
|
10
|
+
from pathlib import PurePosixPath
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
import requests
|
|
14
|
+
from oras.auth import AuthenticationException
|
|
15
|
+
from oras.client import OrasClient
|
|
16
|
+
|
|
17
|
+
from agentskills_core import (
|
|
18
|
+
RESOURCE_KINDS,
|
|
19
|
+
AgentSkillsError,
|
|
20
|
+
ResourceNotFoundError,
|
|
21
|
+
SkillNotFoundError,
|
|
22
|
+
SkillProvider,
|
|
23
|
+
SkillUnavailableError,
|
|
24
|
+
split_frontmatter,
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
OCI_IMAGE_MANIFEST = "application/vnd.oci.image.manifest.v1+json"
|
|
28
|
+
OCI_SKILL_ARTIFACT = "application/vnd.agentskills.skill.v1"
|
|
29
|
+
OCI_SKILL_FILE_LAYER = "application/vnd.agentskills.file.v1"
|
|
30
|
+
OCI_TITLE_ANNOTATION = "org.opencontainers.image.title"
|
|
31
|
+
DEFAULT_MAX_FILES = 512
|
|
32
|
+
DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024
|
|
33
|
+
DEFAULT_MAX_TOTAL_BYTES = 16 * 1024 * 1024
|
|
34
|
+
_SKILL_TAG = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
|
|
35
|
+
_SHA256 = re.compile(r"^sha256:[0-9a-f]{64}$")
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class OCISkillProvider(SkillProvider):
|
|
39
|
+
"""Read skills from OCI artifacts without pulling unrelated file content.
|
|
40
|
+
|
|
41
|
+
Each skill is one tag in the configured repository. Its OCI image manifest
|
|
42
|
+
uses ``artifactType`` ``application/vnd.agentskills.skill.v1`` and stores
|
|
43
|
+
each canonical file as a raw layer. The standard
|
|
44
|
+
``org.opencontainers.image.title`` layer annotation contains the POSIX path
|
|
45
|
+
relative to the skill root. The same annotation on the manifest must match
|
|
46
|
+
the skill tag.
|
|
47
|
+
|
|
48
|
+
ORAS authentication and TLS settings remain registry-owned. By default,
|
|
49
|
+
ORAS uses its token auth backend and local Docker-compatible credentials.
|
|
50
|
+
A configured ORAS client can be injected for other registry controls. File
|
|
51
|
+
descriptor digests are verified when blobs are read; publisher signatures
|
|
52
|
+
remain host-verified through ``agentskills-core`` trust policies.
|
|
53
|
+
|
|
54
|
+
Args:
|
|
55
|
+
repository: OCI repository, such as ``ghcr.io/acme/agent-skills``.
|
|
56
|
+
client: Optional configured ORAS client. The caller retains ownership.
|
|
57
|
+
insecure: Allow plain HTTP when constructing the default ORAS client.
|
|
58
|
+
tls_verify: TLS verification setting or custom CA bundle path.
|
|
59
|
+
auth_backend: ORAS authentication backend name.
|
|
60
|
+
max_files: Maximum number of file layers in one skill.
|
|
61
|
+
max_file_bytes: Maximum size of an individual file layer.
|
|
62
|
+
max_total_bytes: Maximum aggregate size declared by the manifest.
|
|
63
|
+
|
|
64
|
+
Raises:
|
|
65
|
+
ValueError: If the repository or configured limits are invalid.
|
|
66
|
+
"""
|
|
67
|
+
|
|
68
|
+
supports_discovery = True
|
|
69
|
+
supports_resource_listing = True
|
|
70
|
+
supports_file_access = True
|
|
71
|
+
|
|
72
|
+
def __init__(
|
|
73
|
+
self,
|
|
74
|
+
repository: str,
|
|
75
|
+
*,
|
|
76
|
+
client: OrasClient | None = None,
|
|
77
|
+
insecure: bool = False,
|
|
78
|
+
tls_verify: bool | str = True,
|
|
79
|
+
auth_backend: str = "token",
|
|
80
|
+
max_files: int = DEFAULT_MAX_FILES,
|
|
81
|
+
max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
|
|
82
|
+
max_total_bytes: int = DEFAULT_MAX_TOTAL_BYTES,
|
|
83
|
+
) -> None:
|
|
84
|
+
if (
|
|
85
|
+
not repository
|
|
86
|
+
or "://" in repository
|
|
87
|
+
or "@" in repository
|
|
88
|
+
or any(character in repository for character in "?# \t\r\n\x00")
|
|
89
|
+
):
|
|
90
|
+
raise ValueError("repository must be a registry/repository without URL credentials")
|
|
91
|
+
if max_files < 1 or max_file_bytes < 0 or max_total_bytes < 0:
|
|
92
|
+
raise ValueError("OCI skill limits must be non-negative and max_files must be positive")
|
|
93
|
+
if client is not None and (insecure or tls_verify is not True or auth_backend != "token"):
|
|
94
|
+
raise ValueError("Configure TLS and authentication on the supplied ORAS client")
|
|
95
|
+
self.repository = repository
|
|
96
|
+
self._owns_client = client is None
|
|
97
|
+
self._client = client or OrasClient(
|
|
98
|
+
insecure=insecure,
|
|
99
|
+
tls_verify=tls_verify,
|
|
100
|
+
auth_backend=auth_backend,
|
|
101
|
+
)
|
|
102
|
+
self._max_files = max_files
|
|
103
|
+
self._max_file_bytes = max_file_bytes
|
|
104
|
+
self._max_total_bytes = max_total_bytes
|
|
105
|
+
self._manifest_cache: dict[str, dict[str, Any]] = {}
|
|
106
|
+
self._file_cache: dict[str, dict[str, dict[str, Any]]] = {}
|
|
107
|
+
self._lock = threading.RLock()
|
|
108
|
+
|
|
109
|
+
async def __aenter__(self) -> OCISkillProvider:
|
|
110
|
+
return self
|
|
111
|
+
|
|
112
|
+
async def __aexit__(self, *_: object) -> None:
|
|
113
|
+
await self.aclose()
|
|
114
|
+
|
|
115
|
+
async def aclose(self) -> None:
|
|
116
|
+
"""Close the ORAS HTTP session when this provider created it."""
|
|
117
|
+
if self._owns_client:
|
|
118
|
+
await asyncio.to_thread(self._client.session.close)
|
|
119
|
+
|
|
120
|
+
async def discover(self) -> list[str]:
|
|
121
|
+
"""Return skill IDs for tags that identify supported skill artifacts."""
|
|
122
|
+
return await asyncio.to_thread(self._discover_sync)
|
|
123
|
+
|
|
124
|
+
async def get_metadata(self, skill_id: str) -> dict[str, Any]:
|
|
125
|
+
"""Parse and return the skill's YAML frontmatter."""
|
|
126
|
+
metadata, _ = split_frontmatter(await self._read_skill_markdown(skill_id))
|
|
127
|
+
return metadata
|
|
128
|
+
|
|
129
|
+
async def get_body(self, skill_id: str) -> str:
|
|
130
|
+
"""Return the Markdown body after the skill's frontmatter."""
|
|
131
|
+
_, body = split_frontmatter(await self._read_skill_markdown(skill_id))
|
|
132
|
+
return body
|
|
133
|
+
|
|
134
|
+
async def get_script(self, skill_id: str, name: str) -> bytes:
|
|
135
|
+
"""Read one script layer as original bytes."""
|
|
136
|
+
return await self.read_file(skill_id, f"scripts/{name}")
|
|
137
|
+
|
|
138
|
+
async def get_asset(self, skill_id: str, name: str) -> bytes:
|
|
139
|
+
"""Read one asset layer as original bytes."""
|
|
140
|
+
return await self.read_file(skill_id, f"assets/{name}")
|
|
141
|
+
|
|
142
|
+
async def get_reference(self, skill_id: str, name: str) -> bytes:
|
|
143
|
+
"""Read one reference layer as original bytes."""
|
|
144
|
+
return await self.read_file(skill_id, f"references/{name}")
|
|
145
|
+
|
|
146
|
+
async def list_resources(self, skill_id: str) -> dict[str, list[str]]:
|
|
147
|
+
"""List direct resources in the standard skill directories."""
|
|
148
|
+
files = await self.list_files(skill_id)
|
|
149
|
+
resources = {kind: [] for kind in RESOURCE_KINDS}
|
|
150
|
+
for path in files:
|
|
151
|
+
parts = path.split("/")
|
|
152
|
+
if len(parts) == 2 and parts[0] in resources:
|
|
153
|
+
resources[parts[0]].append(parts[1])
|
|
154
|
+
return {kind: sorted(names) for kind, names in resources.items()}
|
|
155
|
+
|
|
156
|
+
async def list_files(self, skill_id: str) -> list[str]:
|
|
157
|
+
"""List canonical file paths from the skill manifest without fetching layers."""
|
|
158
|
+
descriptors = await asyncio.to_thread(self._file_descriptors_sync, skill_id)
|
|
159
|
+
return sorted(descriptors)
|
|
160
|
+
|
|
161
|
+
async def read_file(self, skill_id: str, path: str) -> bytes:
|
|
162
|
+
"""Fetch one file layer and verify its declared size and SHA-256 digest."""
|
|
163
|
+
relative = self._validate_path(path)
|
|
164
|
+
descriptors = await asyncio.to_thread(self._file_descriptors_sync, skill_id)
|
|
165
|
+
descriptor = descriptors.get(relative)
|
|
166
|
+
if descriptor is None:
|
|
167
|
+
raise ResourceNotFoundError(f"Skill '{skill_id}' has no file '{relative}'")
|
|
168
|
+
return await asyncio.to_thread(self._read_blob_sync, skill_id, relative, descriptor)
|
|
169
|
+
|
|
170
|
+
async def _read_skill_markdown(self, skill_id: str) -> str:
|
|
171
|
+
raw = await self.read_file(skill_id, "SKILL.md")
|
|
172
|
+
try:
|
|
173
|
+
return raw.decode("utf-8")
|
|
174
|
+
except UnicodeDecodeError as exc:
|
|
175
|
+
raise AgentSkillsError("OCI SKILL.md must contain UTF-8 text") from exc
|
|
176
|
+
|
|
177
|
+
def _discover_sync(self) -> list[str]:
|
|
178
|
+
with self._lock:
|
|
179
|
+
container = self._client.get_container(self.repository)
|
|
180
|
+
try:
|
|
181
|
+
tags = self._client.get_tags(container)
|
|
182
|
+
except requests.exceptions.HTTPError as exc:
|
|
183
|
+
status = exc.response.status_code if exc.response is not None else None
|
|
184
|
+
if status in {408, 429} or (status is not None and status >= 500):
|
|
185
|
+
raise self._unavailable_error(exc) from exc
|
|
186
|
+
raise AgentSkillsError("OCI tag listing request failed") from exc
|
|
187
|
+
except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as exc:
|
|
188
|
+
raise self._unavailable_error(exc) from exc
|
|
189
|
+
except requests.exceptions.RequestException as exc:
|
|
190
|
+
raise AgentSkillsError("OCI tag listing request failed") from exc
|
|
191
|
+
except AuthenticationException as exc:
|
|
192
|
+
raise AgentSkillsError("OCI registry authentication failed") from exc
|
|
193
|
+
|
|
194
|
+
skills = []
|
|
195
|
+
for tag in tags:
|
|
196
|
+
if not _SKILL_TAG.fullmatch(tag):
|
|
197
|
+
continue
|
|
198
|
+
try:
|
|
199
|
+
manifest = self._manifest_sync(tag)
|
|
200
|
+
except SkillNotFoundError:
|
|
201
|
+
continue
|
|
202
|
+
if manifest.get("artifactType") == OCI_SKILL_ARTIFACT:
|
|
203
|
+
self._file_descriptors_from_manifest(tag, manifest)
|
|
204
|
+
skills.append(tag)
|
|
205
|
+
return sorted(set(skills))
|
|
206
|
+
|
|
207
|
+
def _manifest_sync(self, skill_id: str) -> dict[str, Any]:
|
|
208
|
+
if not _SKILL_TAG.fullmatch(skill_id):
|
|
209
|
+
raise SkillNotFoundError(f"Invalid OCI skill tag: {skill_id!r}")
|
|
210
|
+
with self._lock:
|
|
211
|
+
cached = self._manifest_cache.get(skill_id)
|
|
212
|
+
if cached is not None:
|
|
213
|
+
return deepcopy(cached)
|
|
214
|
+
container = self._client.get_container(f"{self.repository}:{skill_id}")
|
|
215
|
+
try:
|
|
216
|
+
manifest = self._client.get_manifest(
|
|
217
|
+
container, allowed_media_type=[OCI_IMAGE_MANIFEST]
|
|
218
|
+
)
|
|
219
|
+
except requests.exceptions.HTTPError as exc:
|
|
220
|
+
status = exc.response.status_code if exc.response is not None else None
|
|
221
|
+
if status == 404:
|
|
222
|
+
raise SkillNotFoundError(f"OCI skill not found: {skill_id!r}") from exc
|
|
223
|
+
if status in {408, 429} or (status is not None and status >= 500):
|
|
224
|
+
raise self._unavailable_error(exc) from exc
|
|
225
|
+
raise AgentSkillsError("OCI manifest request failed") from exc
|
|
226
|
+
except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as exc:
|
|
227
|
+
raise self._unavailable_error(exc) from exc
|
|
228
|
+
except AuthenticationException as exc:
|
|
229
|
+
raise AgentSkillsError("OCI registry authentication failed") from exc
|
|
230
|
+
|
|
231
|
+
if (
|
|
232
|
+
manifest.get("schemaVersion") != 2
|
|
233
|
+
or manifest.get("mediaType") != OCI_IMAGE_MANIFEST
|
|
234
|
+
or manifest.get("artifactType") != OCI_SKILL_ARTIFACT
|
|
235
|
+
):
|
|
236
|
+
raise SkillNotFoundError(f"OCI tag is not an Agent Skills artifact: {skill_id!r}")
|
|
237
|
+
annotations = manifest.get("annotations")
|
|
238
|
+
if (
|
|
239
|
+
not isinstance(annotations, dict)
|
|
240
|
+
or annotations.get(OCI_TITLE_ANNOTATION) != skill_id
|
|
241
|
+
):
|
|
242
|
+
raise AgentSkillsError("OCI skill manifest title must match its tag")
|
|
243
|
+
self._manifest_cache[skill_id] = deepcopy(manifest)
|
|
244
|
+
return deepcopy(manifest)
|
|
245
|
+
|
|
246
|
+
def _file_descriptors_sync(self, skill_id: str) -> dict[str, dict[str, Any]]:
|
|
247
|
+
with self._lock:
|
|
248
|
+
cached = self._file_cache.get(skill_id)
|
|
249
|
+
if cached is not None:
|
|
250
|
+
return deepcopy(cached)
|
|
251
|
+
manifest = self._manifest_sync(skill_id)
|
|
252
|
+
descriptors = self._file_descriptors_from_manifest(skill_id, manifest)
|
|
253
|
+
self._file_cache[skill_id] = descriptors
|
|
254
|
+
return deepcopy(descriptors)
|
|
255
|
+
|
|
256
|
+
def _file_descriptors_from_manifest(
|
|
257
|
+
self, skill_id: str, manifest: dict[str, Any]
|
|
258
|
+
) -> dict[str, dict[str, Any]]:
|
|
259
|
+
layers = manifest.get("layers")
|
|
260
|
+
if not isinstance(layers, list) or not 1 <= len(layers) <= self._max_files:
|
|
261
|
+
raise AgentSkillsError("OCI skill manifest has an invalid layer count")
|
|
262
|
+
descriptors: dict[str, dict[str, Any]] = {}
|
|
263
|
+
total_size = 0
|
|
264
|
+
for layer in layers:
|
|
265
|
+
if not isinstance(layer, dict) or layer.get("mediaType") != OCI_SKILL_FILE_LAYER:
|
|
266
|
+
raise AgentSkillsError("OCI skill layer has an unsupported media type")
|
|
267
|
+
annotations = layer.get("annotations")
|
|
268
|
+
path = annotations.get(OCI_TITLE_ANNOTATION) if isinstance(annotations, dict) else None
|
|
269
|
+
if not isinstance(path, str):
|
|
270
|
+
raise AgentSkillsError("OCI skill layer is missing its file path annotation")
|
|
271
|
+
try:
|
|
272
|
+
relative = self._validate_path(path)
|
|
273
|
+
except ResourceNotFoundError as exc:
|
|
274
|
+
raise AgentSkillsError("OCI skill manifest contains an unsafe file path") from exc
|
|
275
|
+
digest = layer.get("digest")
|
|
276
|
+
size = layer.get("size")
|
|
277
|
+
if not isinstance(digest, str) or not _SHA256.fullmatch(digest):
|
|
278
|
+
raise AgentSkillsError("OCI skill layer has an unsupported digest")
|
|
279
|
+
if type(size) is not int or size < 0 or size > self._max_file_bytes:
|
|
280
|
+
raise AgentSkillsError("OCI skill layer has an invalid or oversized file size")
|
|
281
|
+
if relative in descriptors:
|
|
282
|
+
raise AgentSkillsError("OCI skill manifest contains duplicate file paths")
|
|
283
|
+
total_size += size
|
|
284
|
+
if total_size > self._max_total_bytes:
|
|
285
|
+
raise AgentSkillsError("OCI skill manifest exceeds the total file size limit")
|
|
286
|
+
descriptors[relative] = deepcopy(layer)
|
|
287
|
+
if "SKILL.md" not in descriptors:
|
|
288
|
+
raise AgentSkillsError("OCI skill manifest must include SKILL.md")
|
|
289
|
+
return descriptors
|
|
290
|
+
|
|
291
|
+
def _read_blob_sync(self, skill_id: str, path: str, descriptor: dict[str, Any]) -> bytes:
|
|
292
|
+
with self._lock:
|
|
293
|
+
container = self._client.get_container(f"{self.repository}:{skill_id}")
|
|
294
|
+
response: requests.Response | None = None
|
|
295
|
+
try:
|
|
296
|
+
response = self._client.get_blob(container, descriptor["digest"], stream=True)
|
|
297
|
+
status = response.status_code
|
|
298
|
+
if status == 404:
|
|
299
|
+
raise AgentSkillsError("OCI skill layer referenced by the manifest is missing")
|
|
300
|
+
if status in {408, 429} or status >= 500:
|
|
301
|
+
raise SkillUnavailableError("OCI registry could not return a skill layer")
|
|
302
|
+
if status != 200:
|
|
303
|
+
raise AgentSkillsError("OCI layer request failed")
|
|
304
|
+
chunks: list[bytes] = []
|
|
305
|
+
digest = hashlib.sha256()
|
|
306
|
+
size = 0
|
|
307
|
+
for chunk in response.iter_content(chunk_size=64 * 1024):
|
|
308
|
+
if not chunk:
|
|
309
|
+
continue
|
|
310
|
+
size += len(chunk)
|
|
311
|
+
if size > self._max_file_bytes:
|
|
312
|
+
raise AgentSkillsError("OCI skill layer exceeds the file size limit")
|
|
313
|
+
digest.update(chunk)
|
|
314
|
+
chunks.append(chunk)
|
|
315
|
+
actual_digest = "sha256:" + digest.hexdigest()
|
|
316
|
+
if size != descriptor["size"] or actual_digest != descriptor["digest"]:
|
|
317
|
+
raise AgentSkillsError(f"OCI skill layer integrity check failed: {path}")
|
|
318
|
+
return b"".join(chunks)
|
|
319
|
+
except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as exc:
|
|
320
|
+
raise self._unavailable_error(exc) from exc
|
|
321
|
+
except requests.exceptions.RequestException as exc:
|
|
322
|
+
raise AgentSkillsError("OCI layer request failed") from exc
|
|
323
|
+
except AuthenticationException as exc:
|
|
324
|
+
raise AgentSkillsError("OCI registry authentication failed") from exc
|
|
325
|
+
finally:
|
|
326
|
+
if response is not None:
|
|
327
|
+
response.close()
|
|
328
|
+
|
|
329
|
+
@staticmethod
|
|
330
|
+
def _validate_path(path: str) -> str:
|
|
331
|
+
candidate = PurePosixPath(path)
|
|
332
|
+
if (
|
|
333
|
+
not path
|
|
334
|
+
or "\\" in path
|
|
335
|
+
or "\x00" in path
|
|
336
|
+
or candidate.is_absolute()
|
|
337
|
+
or any(part in {"", ".", ".."} for part in path.split("/"))
|
|
338
|
+
):
|
|
339
|
+
raise ResourceNotFoundError(f"Unsafe OCI skill file path: {path!r}")
|
|
340
|
+
return candidate.as_posix()
|
|
341
|
+
|
|
342
|
+
@staticmethod
|
|
343
|
+
def _unavailable_error(exc: Exception) -> SkillUnavailableError:
|
|
344
|
+
return SkillUnavailableError(f"OCI registry request failed ({type(exc).__name__})")
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# PEP 561 typed package.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
[tool.poetry]
|
|
2
|
+
name = "agentskills-oci"
|
|
3
|
+
version = "0.8.0"
|
|
4
|
+
description = "OCI registry provider for the Agent Skills format (https://agentskills.io)"
|
|
5
|
+
license = "MIT"
|
|
6
|
+
authors = ["Pratik Panda"]
|
|
7
|
+
readme = "README.md"
|
|
8
|
+
homepage = "https://agentskills.io"
|
|
9
|
+
repository = "https://github.com/pratikxpanda/agentskills-sdk"
|
|
10
|
+
packages = [{include = "agentskills_oci"}]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 3 - Alpha",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Topic :: Software Development :: Libraries",
|
|
15
|
+
"Programming Language :: Python :: 3.12",
|
|
16
|
+
"Programming Language :: Python :: 3.13",
|
|
17
|
+
"Programming Language :: Python :: 3.14",
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
[tool.poetry.dependencies]
|
|
21
|
+
python = ">=3.12,<4.0"
|
|
22
|
+
agentskills-core = ">=0.8.0,<1.0"
|
|
23
|
+
oras = ">=0.2.43,<0.3"
|
|
24
|
+
requests = ">=2.31,<3.0"
|
|
25
|
+
|
|
26
|
+
[build-system]
|
|
27
|
+
requires = ["poetry-core"]
|
|
28
|
+
build-backend = "poetry.core.masonry.api"
|