agentskills-http 0.3.0__tar.gz → 0.4.0__tar.gz

{agentskills_http-0.3.0 → agentskills_http-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentskills-http
-Version: 0.3.0
+Version: 0.4.0
 Summary: HTTP-based skill providers for the Agent Skills format (https://agentskills.io)
 License: MIT
 Author: Pratik Panda
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
-Requires-Dist: agentskills-core (>=0.3.0,<1.0)
+Requires-Dist: agentskills-core (>=0.4.0,<1.0)
 Requires-Dist: httpx (>=0.27,<1.0)
 Requires-Dist: pyyaml (>=6.0,<7.0)
 Project-URL: Homepage, https://agentskills.io
@@ -108,6 +108,7 @@ provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=
 | `max_response_bytes` | `int` | `10_485_760` | Maximum allowed response size in bytes |
 | `revalidate` | `bool` | `False` | Re-check cached `SKILL.md` on every access with `If-None-Match` / `If-Modified-Since` |
 | `resource_manifest` | `bool` | `False` | Enable `list_resources()` by reading a per-skill `index.json` |
+| `skill_manifest` | `bool` | `False` | Enable `discover()` by reading a root `index.json` |
 | `timeout` | `float` | `30.0` | Request timeout in seconds (ignored when you supply `client`) |
 | `max_retries` | `int` | `2` | Retries after the initial attempt, for retryable failures only |
 | `retry_backoff` | `float` | `0.5` | Base delay in seconds for exponential backoff |
@@ -123,6 +124,7 @@ provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=
 | `get_asset(skill_id, name)` | `bytes` | Raw asset content |
 | `get_reference(skill_id, name)` | `bytes` | Raw reference content |
 | `list_resources(skill_id)` | `dict[str, list[str]]` | Resource names from `index.json` (requires `resource_manifest=True`) |
+| `discover()` | `list[str]` | Skill IDs from the root `index.json` (requires `skill_manifest=True`) |
 | `invalidate(skill_id=None)` | `None` | Drop cached `SKILL.md` content for one skill, or all skills |
 | `aclose()` | `None` | Close the HTTP client (if owned by the provider) |
 
@@ -151,6 +153,27 @@ listing = await provider.list_resources("incident-response")
 
 Missing categories default to empty lists. A manifest is host-supplied data whose entries are later interpolated into URLs, so names failing the identifier-safety check are dropped. If a given skill has no `index.json`, `list_resources()` raises `ResourceListingNotSupportedError` for that skill — again, not an empty result.
 
+## Skill Discovery
+
+The same problem one level up: nothing on a static host says which skills exist. Publish the same
+file at the root, listing skills instead of resources:
+
+```json
+{ "skills": ["incident-response", "api-style-guide"] }
+```
+
+Then opt in and register the whole host at once:
+
+```python
+async with HTTPStaticFileSkillProvider(BASE, skill_manifest=True) as provider:
+    await registry.register_all(provider)
+```
+
+One filename and one shape — an object mapping a category to a list of names — at two depths,
+rather than two manifest formats to keep in step. Unsafe and duplicate IDs are dropped as above.
+Without `skill_manifest=True`, or when the root publishes no manifest, `discover()` raises
+`DiscoveryNotSupportedError`.
+
 ## Caching
 
 `SKILL.md` responses are cached per provider instance. Without it a single skill costs up to five round-trips per agent session — twice during registration, once per catalog build, and again on each tool call. Scripts, assets and references are not cached.

{agentskills_http-0.3.0 → agentskills_http-0.4.0}/README.md

@@ -86,6 +86,7 @@ provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=
 | `max_response_bytes` | `int` | `10_485_760` | Maximum allowed response size in bytes |
 | `revalidate` | `bool` | `False` | Re-check cached `SKILL.md` on every access with `If-None-Match` / `If-Modified-Since` |
 | `resource_manifest` | `bool` | `False` | Enable `list_resources()` by reading a per-skill `index.json` |
+| `skill_manifest` | `bool` | `False` | Enable `discover()` by reading a root `index.json` |
 | `timeout` | `float` | `30.0` | Request timeout in seconds (ignored when you supply `client`) |
 | `max_retries` | `int` | `2` | Retries after the initial attempt, for retryable failures only |
 | `retry_backoff` | `float` | `0.5` | Base delay in seconds for exponential backoff |
@@ -101,6 +102,7 @@ provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=
 | `get_asset(skill_id, name)` | `bytes` | Raw asset content |
 | `get_reference(skill_id, name)` | `bytes` | Raw reference content |
 | `list_resources(skill_id)` | `dict[str, list[str]]` | Resource names from `index.json` (requires `resource_manifest=True`) |
+| `discover()` | `list[str]` | Skill IDs from the root `index.json` (requires `skill_manifest=True`) |
 | `invalidate(skill_id=None)` | `None` | Drop cached `SKILL.md` content for one skill, or all skills |
 | `aclose()` | `None` | Close the HTTP client (if owned by the provider) |
 
@@ -129,6 +131,27 @@ listing = await provider.list_resources("incident-response")
 
 Missing categories default to empty lists. A manifest is host-supplied data whose entries are later interpolated into URLs, so names failing the identifier-safety check are dropped. If a given skill has no `index.json`, `list_resources()` raises `ResourceListingNotSupportedError` for that skill — again, not an empty result.
 
+## Skill Discovery
+
+The same problem one level up: nothing on a static host says which skills exist. Publish the same
+file at the root, listing skills instead of resources:
+
+```json
+{ "skills": ["incident-response", "api-style-guide"] }
+```
+
+Then opt in and register the whole host at once:
+
+```python
+async with HTTPStaticFileSkillProvider(BASE, skill_manifest=True) as provider:
+    await registry.register_all(provider)
+```
+
+One filename and one shape — an object mapping a category to a list of names — at two depths,
+rather than two manifest formats to keep in step. Unsafe and duplicate IDs are dropped as above.
+Without `skill_manifest=True`, or when the root publishes no manifest, `discover()` raises
+`DiscoveryNotSupportedError`.
+
 ## Caching
 
 `SKILL.md` responses are cached per provider instance. Without it a single skill costs up to five round-trips per agent session — twice during registration, once per catalog build, and again on each tool call. Scripts, assets and references are not cached.

{agentskills_http-0.3.0 → agentskills_http-0.4.0}/agentskills_http/static.py

@@ -16,11 +16,15 @@ Expected URL layout::
     └── another-skill/
         └── SKILL.md
 
-The provider is a pure content accessor — it does not enumerate or
-discover skills.  Registration is handled explicitly by the application
-via :meth:`SkillRegistry.register <agentskills_core.SkillRegistry.register>`.
-Resource names (scripts, assets, references) are discovered by the agent
-from the skill body rather than from a manifest.
+The provider is a pure content accessor by default — a plain static host
+cannot be enumerated, so registration is explicit via
+:meth:`SkillRegistry.register <agentskills_core.SkillRegistry.register>` and
+resource names come from the skill body.  A host that publishes
+``index.json`` manifests can enable both optional capabilities: a manifest
+at ``{base_url}/index.json`` lists the skills, and one at
+``{base_url}/{skill_id}/index.json`` lists that skill's resources.  Same
+filename, same shape — a JSON object mapping a category to a list of names
+— at two depths, rather than two manifest formats to keep in step.
 
 All methods are ``async`` and use `httpx <https://www.python-httpx.org/>`_
 for non-blocking HTTP requests.
@@ -44,6 +48,7 @@ import httpx
 from agentskills_core import (
     RESOURCE_KINDS,
     AgentSkillsError,
+    DiscoveryNotSupportedError,
     ResourceListingNotSupportedError,
     ResourceNotFoundError,
     SkillNotFoundError,
@@ -83,8 +88,12 @@ _NOT_FOUND_STATUS_CODES: frozenset[int] = frozenset({404, 410})
 #: Non-5xx statuses worth retrying.
 _RETRYABLE_STATUS_CODES: frozenset[int] = frozenset({408, 425, 429})
 
-#: Per-skill manifest filename used for resource listing.
-RESOURCE_MANIFEST_NAME: str = "index.json"
+#: Manifest filename.  Served at the root it lists skills; served inside a
+#: skill it lists that skill's resources.
+MANIFEST_NAME: str = "index.json"
+
+#: Manifest key holding skill IDs in a root manifest.
+SKILLS_MANIFEST_KEY: str = "skills"
 
 
 def _parse_retry_after(value: str | None) -> float | None:
@@ -120,7 +129,9 @@ class HTTPStaticFileSkillProvider(SkillProvider):
     GitHub Pages, etc.) that hosts skill files at predictable URL paths.
     Resource names (scripts, assets, references) are discovered by the
     agent from the skill body, or from an optional per-skill
-    ``index.json`` manifest -- see *resource_manifest*.
+    ``index.json`` manifest -- see *resource_manifest*.  The set of
+    skills is likewise unknowable over plain HTTP unless the host
+    publishes a root ``index.json`` -- see *skill_manifest*.
 
     The provider owns an :class:`httpx.AsyncClient` for connection
     pooling.  If you supply your own client the provider will use it
@@ -158,6 +169,13 @@ class HTTPStaticFileSkillProvider(SkillProvider):
             plain static host cannot be enumerated and claiming
             otherwise would make missing manifests look like skills with
             no resources.
+        skill_manifest: Set ``True`` if the host publishes a root
+            ``index.json`` with a ``"skills"`` list.  Enables
+            :meth:`discover`, and so
+            :meth:`SkillRegistry.register_all
+            <agentskills_core.SkillRegistry.register_all>`.  Defaults to
+            ``False`` for the same reason: without a manifest, "no
+            skills found" would be a lie.
         timeout: Request timeout in seconds.  Ignored when you supply
             your own *client*.
         max_retries: Retries after the initial attempt, for retryable
@@ -199,6 +217,7 @@ class HTTPStaticFileSkillProvider(SkillProvider):
         max_response_bytes: int = DEFAULT_MAX_RESPONSE_BYTES,
         revalidate: bool = False,
         resource_manifest: bool = False,
+        skill_manifest: bool = False,
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = DEFAULT_MAX_RETRIES,
         retry_backoff: float = DEFAULT_RETRY_BACKOFF_SECONDS,
@@ -237,6 +256,7 @@ class HTTPStaticFileSkillProvider(SkillProvider):
         self._revalidate = revalidate
         self._skill_md_cache: dict[str, _CachedSkillMd] = {}
         self.supports_resource_listing = resource_manifest
+        self.supports_discovery = skill_manifest
         self._max_retries = max_retries
         self._retry_backoff = retry_backoff
         self._max_retry_delay = max_retry_delay
@@ -277,14 +297,20 @@ class HTTPStaticFileSkillProvider(SkillProvider):
     # ------------------------------------------------------------------
 
     @staticmethod
-    def _validate_identifier(value: str, label: str) -> None:
-        """Raise :class:`ValueError` if *value* is not a safe URL path segment.
+    def _validate_identifier(value: str, label: str, error: type[AgentSkillsError]) -> None:
+        """Raise *error* if *value* is not a safe URL path segment.
 
         Prevents path-traversal attacks (e.g. ``../``) and other
         injection via ``skill_id`` or resource ``name``.
+
+        *error* is the exception the calling method documents — a
+        rejected identifier is indistinguishable from a missing one from
+        the caller's side, and raising something outside the
+        :class:`~agentskills_core.AgentSkillsError` hierarchy would force
+        callers to special-case this provider.
         """
         if not _SAFE_IDENTIFIER_RE.match(value):
-            raise ValueError(
+            raise error(
                 f"Invalid {label}: {value!r} — must start with an "
                 f"alphanumeric character and contain only alphanumeric "
                 f"characters, hyphens, dots, and underscores"
@@ -413,58 +439,121 @@ class HTTPStaticFileSkillProvider(SkillProvider):
             ResourceListingNotSupportedError: If the provider was built
                 without ``resource_manifest=True``, or the skill has no
                 published manifest.
+            SkillNotFoundError: If the skill itself does not exist.
             AgentSkillsError: If the manifest is not a JSON object.
         """
         if not self.supports_resource_listing:
             raise ResourceListingNotSupportedError(
                 "This provider was not configured with a resource manifest. "
                 "A static HTTP host cannot be enumerated. Pass "
-                "resource_manifest=True if the host publishes "
-                f"{RESOURCE_MANIFEST_NAME} per skill, otherwise take resource "
-                "names from the skill body."
+                f"resource_manifest=True if the host publishes {MANIFEST_NAME} "
+                "per skill, otherwise take resource names from the skill body."
             )
 
-        self._validate_identifier(skill_id, "skill_id")
-        url = f"{self._base_url}/{quote(skill_id, safe='')}/{RESOURCE_MANIFEST_NAME}"
+        self._validate_identifier(skill_id, "skill_id", SkillNotFoundError)
+        url = f"{self._base_url}/{quote(skill_id, safe='')}/{MANIFEST_NAME}"
+        subject = f"Resource manifest for skill {skill_id!r}"
         try:
-            raw = await self._get_bytes(url)
+            manifest = await self._fetch_manifest(url, subject)
         except ResourceNotFoundError as exc:
+            # A 404 here means either "this skill publishes no manifest" or
+            # "there is no such skill", and only SKILL.md can tell them
+            # apart. The extra request is on the failure path, and its
+            # result is cached for the caller who asks next.
+            await self._get_skill_md(skill_id)
             raise ResourceListingNotSupportedError(
-                f"No {RESOURCE_MANIFEST_NAME} manifest published for skill "
+                f"No {MANIFEST_NAME} manifest published for skill "
                 f"{skill_id!r}. Take resource names from the skill body instead."
             ) from exc
 
-        try:
-            manifest = json.loads(raw)
-        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
-            raise AgentSkillsError(
-                f"Resource manifest for skill {skill_id!r} is not valid JSON"
-            ) from exc
+        return {kind: self._manifest_names(manifest, kind, subject) for kind in RESOURCE_KINDS}
 
-        if not isinstance(manifest, dict):
-            raise AgentSkillsError(
-                f"Resource manifest for skill {skill_id!r} must be a JSON object"
-            )
+    # ------------------------------------------------------------------
+    # Skill discovery
+    # ------------------------------------------------------------------
 
-        listing: dict[str, list[str]] = {}
-        for kind in RESOURCE_KINDS:
-            entries = manifest.get(kind) or []
-            if not isinstance(entries, list):
-                raise AgentSkillsError(
-                    f"Resource manifest for skill {skill_id!r} has a non-list value for {kind!r}"
-                )
-            listing[kind] = sorted(
-                name
-                for name in entries
-                if isinstance(name, str) and _SAFE_IDENTIFIER_RE.match(name)
+    async def discover(self) -> list[str]:
+        """List the host's skills from the root ``index.json`` manifest.
+
+        Requires ``skill_manifest=True``.  The manifest is a JSON object
+        at ``{base_url}/index.json`` with a ``"skills"`` list::
+
+            {"skills": ["incident-response", "api-style-guide"]}
+
+        It is the same file format as the per-skill resource manifest,
+        one level up, so a host publishing both has one shape to
+        generate rather than two.  Other keys are ignored, and entries
+        that are not valid skill IDs are dropped -- a manifest is
+        host-supplied data and an ID is later interpolated into a URL.
+
+        Returns:
+            Sorted skill IDs.  Empty when the manifest lists none.
+
+        Raises:
+            DiscoveryNotSupportedError: If the provider was built
+                without ``skill_manifest=True``, or the host publishes
+                no root manifest.
+            AgentSkillsError: If the manifest is not a JSON object.
+        """
+        if not self.supports_discovery:
+            raise DiscoveryNotSupportedError(
+                "This provider was not configured with a skill manifest. "
+                "A static HTTP host cannot be enumerated. Pass "
+                f"skill_manifest=True if the host publishes a root {MANIFEST_NAME}, "
+                "otherwise register skills explicitly."
             )
 
-        return listing
+        url = f"{self._base_url}/{MANIFEST_NAME}"
+        subject = "Skill manifest"
+        try:
+            manifest = await self._fetch_manifest(url, subject)
+        except ResourceNotFoundError as exc:
+            raise DiscoveryNotSupportedError(
+                f"No {MANIFEST_NAME} manifest published at {self._describe(url)}. "
+                "Register skills explicitly instead."
+            ) from exc
+
+        skill_ids = self._manifest_names(manifest, SKILLS_MANIFEST_KEY, subject)
+        _logger.debug("Discovered %d skills from %s", len(skill_ids), self._describe(url))
+        return skill_ids
 
     # ------------------------------------------------------------------
     # Internal helpers
     # ------------------------------------------------------------------
 
+    async def _fetch_manifest(self, url: str, subject: str) -> dict[str, Any]:
+        """Fetch and parse an ``index.json`` manifest.
+
+        Raises:
+            ResourceNotFoundError: If no manifest is published there.
+                Callers translate this into the "cannot enumerate"
+                error their own capability documents.
+            AgentSkillsError: If the manifest is not a JSON object.
+        """
+        raw = await self._get_bytes(url)
+        try:
+            manifest = json.loads(raw)
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise AgentSkillsError(f"{subject} is not valid JSON") from exc
+        if not isinstance(manifest, dict):
+            raise AgentSkillsError(f"{subject} must be a JSON object")
+        return manifest
+
+    @staticmethod
+    def _manifest_names(manifest: dict[str, Any], key: str, subject: str) -> list[str]:
+        """Return the safe, sorted, de-duplicated names under *key*.
+
+        A missing key means an empty list.  Unsafe entries are dropped
+        rather than raising: one bad name in a host-supplied manifest
+        should not make the whole listing unavailable.
+        """
+        entries = manifest.get(key) or []
+        if not isinstance(entries, list):
+            raise AgentSkillsError(f"{subject} has a non-list value for {key!r}")
+        return sorted(
+            {name for name in entries if isinstance(name, str) and _SAFE_IDENTIFIER_RE.match(name)}
+        )
+
     def _describe(self, url: str) -> str:
         """Describe *url* for an error message or log record without leaking secrets.
 
@@ -611,7 +700,7 @@ class HTTPStaticFileSkillProvider(SkillProvider):
 
     async def _get_skill_md(self, skill_id: str) -> str:
         """Fetch a skill's ``SKILL.md``, serving from cache when possible."""
-        self._validate_identifier(skill_id, "skill_id")
+        self._validate_identifier(skill_id, "skill_id", SkillNotFoundError)
         url = f"{self._base_url}/{quote(skill_id, safe='')}/SKILL.md"
 
         cached = self._skill_md_cache.get(skill_id)
@@ -644,7 +733,7 @@ class HTTPStaticFileSkillProvider(SkillProvider):
 
     async def _get_resource(self, skill_id: str, subdir: str, name: str) -> bytes:
         """Fetch a single resource file from a skill subdirectory."""
-        self._validate_identifier(skill_id, "skill_id")
-        self._validate_identifier(name, "resource name")
+        self._validate_identifier(skill_id, "skill_id", SkillNotFoundError)
+        self._validate_identifier(name, "resource name", ResourceNotFoundError)
         url = f"{self._base_url}/{quote(skill_id, safe='')}/{subdir}/{quote(name, safe='')}"
         return await self._get_bytes(url)

{agentskills_http-0.3.0 → agentskills_http-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agentskills-http"
-version = "0.3.0"
+version = "0.4.0"
 description = "HTTP-based skill providers for the Agent Skills format (https://agentskills.io)"
 license = "MIT"
 authors = ["Pratik Panda"]
@@ -19,7 +19,7 @@ classifiers = [
 
 [tool.poetry.dependencies]
 python = ">=3.12,<4.0"
-agentskills-core = ">=0.3.0,<1.0"
+agentskills-core = ">=0.4.0,<1.0"
 httpx = ">=0.27,<1.0"
 pyyaml = ">=6.0,<7.0"