agentskills-http 0.6.0__tar.gz → 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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agentskills-http
3
- Version: 0.6.0
3
+ Version: 0.8.0
4
4
  Summary: HTTP-based skill providers for the Agent Skills format (https://agentskills.io)
5
5
  License: MIT
6
6
  Author: Pratik Panda
@@ -14,7 +14,8 @@ Classifier: Programming Language :: Python :: 3.13
14
14
  Classifier: Programming Language :: Python :: 3.14
15
15
  Classifier: Programming Language :: Python :: 3.15
16
16
  Classifier: Topic :: Software Development :: Libraries
17
- Requires-Dist: agentskills-core (>=0.6.0,<1.0)
17
+ Requires-Dist: agentskills-core (>=0.8.0,<1.0)
18
+ Requires-Dist: httpcore (>=1.0.9,<2.0)
18
19
  Requires-Dist: httpx (>=0.27,<1.0)
19
20
  Requires-Dist: pyyaml (>=6.0,<7.0)
20
21
  Project-URL: Homepage, https://agentskills.io
@@ -23,7 +24,7 @@ Description-Content-Type: text/markdown
23
24
 
24
25
  ---
25
26
  title: agentskills-http
26
- description: Static HTTP file provider for Agent Skills.
27
+ description: Read skills from static HTTP hosts with explicit manifests and network controls.
27
28
  ---
28
29
 
29
30
  [![PyPI](https://img.shields.io/pypi/v/agentskills-http)](https://pypi.org/project/agentskills-http/)
@@ -32,7 +33,7 @@ description: Static HTTP file provider for Agent Skills.
32
33
 
33
34
  > HTTP static-file skill provider for the [Agent Skills SDK](https://github.com/pratikxpanda/agentskills-sdk).
34
35
 
35
- Serves [Agent Skills](https://agentskills.io) from any static HTTP file host - S3, Azure Blob, CDN, GitHub Pages, Nginx, etc. Expects the same directory-tree layout as the filesystem provider, served over HTTP.
36
+ Serves [Agent Skills](https://agentskills.io) from any static HTTP file host, such as S3, Azure Blob, CDN, GitHub Pages, or Nginx. Expects the same directory-tree layout as the filesystem provider, served over HTTP.
36
37
 
37
38
  ## Installation
38
39
 
@@ -40,7 +41,13 @@ Serves [Agent Skills](https://agentskills.io) from any static HTTP file host - S
40
41
  pip install agentskills-http
41
42
  ```
42
43
 
43
- Requires Python 3.12 or newer. Installs `agentskills-core`, `httpx`, and `pyyaml` as dependencies.
44
+ Requires Python 3.12 or newer. Installs `agentskills-core`, `httpx`, `httpcore`, and `pyyaml`.
45
+
46
+ Connections default to public-network destinations only. DNS answers are validated
47
+ at connection time and the connection is pinned to an approved IP. Redirects
48
+ are rejected and environment proxies are not inherited. Internal hosts require
49
+ `allow_private_network=True`. Use `require_tls=True` for production sources.
50
+ See the [trust and operability guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/trust-and-operability.md).
44
51
 
45
52
  ## Expected URL Layout
46
53
 
@@ -57,19 +64,34 @@ https://cdn.example.com/skills/
57
64
 
58
65
  ## Usage
59
66
 
67
+ Publish a valid `SKILL.md` beneath each skill ID in the layout above. Replace the example
68
+ URL and skill ID with yours. Reading a known skill does not require an `index.json`.
69
+
60
70
  ```python
71
+ import asyncio
72
+
61
73
  from agentskills_core import SkillRegistry
62
74
  from agentskills_http import HTTPStaticFileSkillProvider
63
75
 
64
- async with HTTPStaticFileSkillProvider("https://cdn.example.com/skills") as provider:
76
+ BASE = "https://cdn.example.com/skills"
77
+
78
+
79
+ async def main() -> None:
80
+ async with HTTPStaticFileSkillProvider(BASE, require_tls=True) as provider:
65
81
  registry = SkillRegistry()
66
82
  await registry.register("incident-response", provider)
67
-
68
83
  skill = registry.get_skill("incident-response")
69
- meta = await skill.get_metadata()
70
- body = await skill.get_body()
84
+ print(await skill.get_metadata())
85
+ print(await skill.get_body())
86
+
87
+
88
+ asyncio.run(main())
71
89
  ```
72
90
 
91
+ The remaining async snippets belong inside an async function. `BASE` is your skill-root URL.
92
+ Use the context manager above, or call `await provider.aclose()` in `finally`, for every
93
+ provider you create. Create a registry before snippets that register discovered skills.
94
+
73
95
  ### Custom Headers
74
96
 
75
97
  Pass authentication or other headers:
@@ -77,12 +99,15 @@ Pass authentication or other headers:
77
99
  ```python
78
100
  from agentskills_http import HTTPStaticFileSkillProvider
79
101
 
80
- provider = HTTPStaticFileSkillProvider(
102
+ async with HTTPStaticFileSkillProvider(
81
103
  "https://cdn.example.com/skills",
82
104
  headers={"Authorization": "Bearer <token>"},
83
- )
105
+ ) as provider:
106
+ print(await provider.get_body("incident-response"))
84
107
  ```
85
108
 
109
+ Replace `<token>` with a credential supplied by your deployment. Do not commit credentials.
110
+
86
111
  ### Bring Your Own Client
87
112
 
88
113
  Supply a pre-configured `httpx.AsyncClient` for full control over timeouts, proxies, etc.:
@@ -91,21 +116,28 @@ Supply a pre-configured `httpx.AsyncClient` for full control over timeouts, prox
91
116
  import httpx
92
117
  from agentskills_http import HTTPStaticFileSkillProvider
93
118
 
94
- client = httpx.AsyncClient(timeout=30, headers={"Authorization": "Bearer <token>"})
95
- provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=client)
96
- # caller is responsible for closing the client
119
+ async with httpx.AsyncClient(timeout=30, follow_redirects=False) as client:
120
+ async with HTTPStaticFileSkillProvider(
121
+ "https://cdn.example.com/skills", client=client, allow_private_network=True
122
+ ) as provider:
123
+ print(await provider.get_body("incident-response"))
97
124
  ```
98
125
 
99
126
  > **Note:** `client` and `headers` are mutually exclusive. Configure headers on the client directly when providing your own.
100
127
 
128
+ Custom clients require explicit `allow_private_network=True` because DNS,
129
+ TLS, proxies, and destination restrictions are caller-owned. Apply equivalent
130
+ network restrictions in that client when destinations are untrusted. Redirects
131
+ and response-size limits are still enforced by the provider.
132
+
101
133
  ## API
102
134
 
103
- ### `HTTPStaticFileSkillProvider(base_url, *, client=None, headers=None, params=None, require_tls=False, max_response_bytes=10_485_760, revalidate=False)`
135
+ ### `HTTPStaticFileSkillProvider(base_url, *, client=None, headers=None, params=None, require_tls=False, max_response_bytes=10_485_760, revalidate=False, resource_manifest=False, skill_manifest=False, file_manifest=False, timeout=30.0, max_retries=2, retry_backoff=0.5, max_retry_delay=30.0, allow_private_network=False, observer=None)`
104
136
 
105
137
  | Parameter | Type | Default | Description |
106
138
  | --- | --- | --- | --- |
107
- | `base_url` | `str` | - | Root URL where the skill tree is hosted |
108
- | `client` | `AsyncClient \| None` | `None` | Pre-configured httpx client (caller manages lifecycle) |
139
+ | `base_url` | `str` | - | Root URL where the skill tree is hosted. Must be HTTP(S) without credentials, query string, or fragment |
140
+ | `client` | `AsyncClient \| None` | `None` | Pre-configured httpx client (caller manages lifecycle). Requires `allow_private_network=True` |
109
141
  | `headers` | `dict \| None` | `None` | Extra headers sent with every request |
110
142
  | `params` | `dict \| None` | `None` | Query parameters appended to every request |
111
143
  | `require_tls` | `bool` | `False` | Reject `http://` URLs with `ValueError` |
@@ -118,6 +150,8 @@ provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=
118
150
  | `max_retries` | `int` | `2` | Retries after the initial attempt, for retryable failures only |
119
151
  | `retry_backoff` | `float` | `0.5` | Base delay in seconds for exponential backoff |
120
152
  | `max_retry_delay` | `float` | `30.0` | Ceiling on any single backoff sleep |
153
+ | `allow_private_network` | `bool` | `False` | Opt out of public-only destinations. Required for custom clients |
154
+ | `observer` | callable or `None` | `None` | Content-free fetch/cache events with hashed origin |
121
155
 
122
156
  > **Note:** `client` and `headers`/`params` are mutually exclusive. Configure headers and params on the client directly when providing your own.
123
157
 
@@ -139,7 +173,7 @@ Supports `async with` for automatic cleanup.
139
173
 
140
174
  ## Resource Discovery
141
175
 
142
- A static file host cannot be enumerated: there is no portable directory listing over plain HTTP. By default this provider therefore reports that it *cannot* list resources — `list_resources()` raises `ResourceListingNotSupportedError` — rather than returning an empty mapping that would look like a skill with no resources.
176
+ A static file host cannot be enumerated: there is no portable directory listing over plain HTTP. By default this provider therefore reports that it *cannot* list resources (`list_resources()` raises `ResourceListingNotSupportedError`) rather than returning an empty mapping that would look like a skill with no resources.
143
177
 
144
178
  If you control the host, publish a small manifest at `{base_url}/{skill_id}/index.json`:
145
179
 
@@ -158,12 +192,12 @@ provider = HTTPStaticFileSkillProvider(BASE, resource_manifest=True)
158
192
  listing = await provider.list_resources("incident-response")
159
193
  ```
160
194
 
161
- 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.
195
+ 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.
162
196
 
163
197
  ## Lossless File Access
164
198
 
165
- For v0.6 byte-preserving delivery, publish a complete `files` list in each skill's
166
- `index.json`. This can coexist with the legacy grouped resource keys:
199
+ For byte-preserving delivery, publish a complete `files` list in each skill's
200
+ `index.json`. This can coexist with the grouped resource keys:
167
201
 
168
202
  ```json
169
203
  {
@@ -179,13 +213,13 @@ async with HTTPStaticFileSkillProvider(BASE, file_manifest=True) as provider:
179
213
  ```
180
214
 
181
215
  The host is responsible for listing every file. The provider cannot discover
182
- omitted files on a static host. Unlike legacy resource listing, unsafe paths,
216
+ omitted files on a static host. Unlike resource listing, unsafe paths,
183
217
  duplicates, non-string entries, or a missing `SKILL.md` entry reject the manifest.
184
218
  Enabling `resource_manifest` alone does not enable lossless file access.
185
219
 
186
220
  Reads preserve bytes and bypass the parsed `SKILL.md` cache. Size limits apply,
187
221
  and redirects, partial responses, and unsolicited `304` responses are refused.
188
- An injected client must have `follow_redirects=False`. Publish immutable content
222
+ An injected client must have `follow_redirects=False` and needs `allow_private_network=True`. Publish immutable content
189
223
  when building verified manifests. Listing and reading do not form an atomic snapshot.
190
224
 
191
225
  ## Skill Discovery
@@ -204,14 +238,14 @@ async with HTTPStaticFileSkillProvider(BASE, skill_manifest=True) as provider:
204
238
  await registry.register_all(provider)
205
239
  ```
206
240
 
207
- One filename and one shape — an object mapping a category to a list of names — at two depths,
241
+ One filename and one shape (an object mapping a category to a list of names) at two depths,
208
242
  rather than two manifest formats to keep in step. Unsafe and duplicate IDs are dropped as above.
209
243
  Without `skill_manifest=True`, or when the root publishes no manifest, `discover()` raises
210
244
  `DiscoveryNotSupportedError`.
211
245
 
212
246
  ## Caching
213
247
 
214
- `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.
248
+ `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.
215
249
 
216
250
  By default the cache is served until you call `invalidate()`. If your host serves mutable skills and the process is long-lived, opt into conditional revalidation instead:
217
251
 
@@ -227,12 +261,14 @@ That sends `If-None-Match` / `If-Modified-Since` on every access and reuses the
227
261
  | --- | --- | --- |
228
262
  | `404` / `410` on `SKILL.md` | `SkillNotFoundError` | No |
229
263
  | `404` / `410` on a resource | `ResourceNotFoundError` | No |
230
- | `5xx`, `408`, `425`, `429` | `SkillUnavailableError` | Yes |
231
- | Timeouts, connection and protocol errors | `SkillUnavailableError` | Yes |
264
+ | `5xx`, `408`, `425`, `429` | `ProviderUnavailableError` | Yes |
265
+ | Timeouts, connection and protocol errors | `ProviderUnavailableError` | Yes |
266
+ | Redirects (`3xx`) | `AgentSkillsError` | No |
267
+ | Destination not allowed by network policy | `NetworkPolicyError` (from `agentskills_http`) | No |
232
268
  | `401` / `403` | `AgentSkillsError` | No |
233
- | Other `4xx`, oversized responses | `AgentSkillsError` | No |
269
+ | Other `4xx`, oversized responses, invalid `Content-Length` | `AgentSkillsError` | No |
234
270
 
235
- All exceptions inherit from `AgentSkillsError`.
271
+ All exceptions inherit from `AgentSkillsError`. `ProviderUnavailableError` is a subclass of `SkillUnavailableError`, so existing handlers keep working. It is the only failure that verified stale serving in `agentskills-mcp-extension` may cover.
236
272
 
237
273
  The split between `SkillNotFoundError` and `SkillUnavailableError` is the point of the taxonomy: a `503` means the skill may well exist and the same request could succeed in a moment, whereas a `404` means it is gone. Collapsing both into "not found" turns a retryable blip into a permanent-looking failure, and nothing downstream can tell the difference.
238
274
 
@@ -249,27 +285,29 @@ provider = HTTPStaticFileSkillProvider(
249
285
  )
250
286
  ```
251
287
 
252
- Jitter matters because a registry builds its catalog concurrently — without it, every skill fetch would retry in lockstep and hit the recovering server as one wave.
288
+ Jitter matters because a registry builds its catalog concurrently: without it, every skill fetch would retry in lockstep and hit the recovering server as one wave.
253
289
 
254
290
  `Retry-After` is honoured in both the delay-seconds and HTTP-date forms. If the server asks for longer than `max_retry_delay`, the request is **not** retried: blocking a request path for minutes is worse than failing fast. The advised delay is still available to the caller as `SkillUnavailableError.retry_after`, so a scheduler can act on it.
255
291
 
256
292
  ## Security
257
293
 
258
- - **Input validation** - Skill IDs and resource names are validated against a safe-character pattern (`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`) to prevent path-traversal and injection attacks.
259
- - **TLS warnings** - A `UserWarning` is emitted when `base_url` uses unencrypted HTTP. Set `require_tls=True` to reject HTTP URLs entirely.
260
- - **Redirect protection** - The internally-created HTTP client does not follow redirects by default, preventing open-redirect SSRF.
261
- - **Timeouts** - Default 30-second timeout on all HTTP requests. Configure via `timeout`.
262
- - **Response size limits** - Responses exceeding 10 MB (default) are rejected before processing. Configure via `max_response_bytes`.
263
- - **Error-message sanitization** - Messages carry the status code and the path *relative to `base_url`* — never the host, never a query string. The underlying `httpx` exception is deliberately **not** chained (`from None`), because `httpx.HTTPStatusError` renders the full request URL including its query string, which is exactly where SAS tokens and signed-URL signatures live. Chaining it leaked credentials into every traceback.
294
+ - **Input validation**: Skill IDs and resource names are validated against a safe-character pattern (`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`) to prevent path-traversal and injection attacks.
295
+ - **TLS warnings**: A `UserWarning` is emitted when `base_url` uses unencrypted HTTP. Set `require_tls=True` to reject HTTP URLs entirely.
296
+ - **Public-network-only by default**: DNS is resolved at connection time, every answer must be a public address, and the connection goes to the validated IP, so a rebinding answer cannot reach an internal host. Loopback, private, link-local, multicast, and reserved addresses are refused. `allow_private_network=True` opts out.
297
+ - **Redirects rejected**: Redirects are never followed, in every mode, so credentials cannot be forwarded to another origin. Environment proxies are not inherited.
298
+ - **Credential-free `base_url`**: Userinfo, query strings, and fragments are refused. Pass credentials through `headers` or `params`.
299
+ - **Timeouts**: Default 30-second timeout on all HTTP requests. Configure via `timeout`.
300
+ - **Response size limits**: Responses exceeding 10 MB (default) are rejected before processing. Configure via `max_response_bytes`.
301
+ - **Error-message sanitization**: Messages carry the status code and the path *relative to `base_url`*, never the host, never a query string. The underlying `httpx` exception is deliberately **not** chained (`from None`), because `httpx.HTTPStatusError` renders the full request URL including its query string, which is exactly where SAS tokens and signed-URL signatures live. Chaining it leaked credentials into every traceback.
264
302
 
265
303
  For the full security policy, see [SECURITY.md](https://github.com/pratikxpanda/agentskills-sdk/blob/main/SECURITY.md).
266
304
 
267
305
  ## Deployment Considerations
268
306
 
269
- - **Rate limiting** - The SDK does not enforce rate limits on MCP tool
270
- calls or HTTP requests. Deploy behind a reverse proxy or API gateway
271
- that provides rate limiting in production environments.
272
- - **Credential management** - Do not store secrets (API keys, SAS
307
+ - **Rate limiting**: The SDK does not enforce rate limits on HTTP requests or
308
+ MCP requests. Deploy behind a reverse proxy or API gateway that provides rate
309
+ limiting in production environments.
310
+ - **Credential management**: Do not store secrets (API keys, SAS
273
311
  tokens, Authorization headers) in config files committed to version
274
312
  control. Use environment variables or a secret manager instead.
275
313
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  title: agentskills-http
3
- description: Static HTTP file provider for Agent Skills.
3
+ description: Read skills from static HTTP hosts with explicit manifests and network controls.
4
4
  ---
5
5
 
6
6
  [![PyPI](https://img.shields.io/pypi/v/agentskills-http)](https://pypi.org/project/agentskills-http/)
@@ -9,7 +9,7 @@ description: Static HTTP file provider for Agent Skills.
9
9
 
10
10
  > HTTP static-file skill provider for the [Agent Skills SDK](https://github.com/pratikxpanda/agentskills-sdk).
11
11
 
12
- Serves [Agent Skills](https://agentskills.io) from any static HTTP file host - S3, Azure Blob, CDN, GitHub Pages, Nginx, etc. Expects the same directory-tree layout as the filesystem provider, served over HTTP.
12
+ Serves [Agent Skills](https://agentskills.io) from any static HTTP file host, such as S3, Azure Blob, CDN, GitHub Pages, or Nginx. Expects the same directory-tree layout as the filesystem provider, served over HTTP.
13
13
 
14
14
  ## Installation
15
15
 
@@ -17,7 +17,13 @@ Serves [Agent Skills](https://agentskills.io) from any static HTTP file host - S
17
17
  pip install agentskills-http
18
18
  ```
19
19
 
20
- Requires Python 3.12 or newer. Installs `agentskills-core`, `httpx`, and `pyyaml` as dependencies.
20
+ Requires Python 3.12 or newer. Installs `agentskills-core`, `httpx`, `httpcore`, and `pyyaml`.
21
+
22
+ Connections default to public-network destinations only. DNS answers are validated
23
+ at connection time and the connection is pinned to an approved IP. Redirects
24
+ are rejected and environment proxies are not inherited. Internal hosts require
25
+ `allow_private_network=True`. Use `require_tls=True` for production sources.
26
+ See the [trust and operability guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/trust-and-operability.md).
21
27
 
22
28
  ## Expected URL Layout
23
29
 
@@ -34,19 +40,34 @@ https://cdn.example.com/skills/
34
40
 
35
41
  ## Usage
36
42
 
43
+ Publish a valid `SKILL.md` beneath each skill ID in the layout above. Replace the example
44
+ URL and skill ID with yours. Reading a known skill does not require an `index.json`.
45
+
37
46
  ```python
47
+ import asyncio
48
+
38
49
  from agentskills_core import SkillRegistry
39
50
  from agentskills_http import HTTPStaticFileSkillProvider
40
51
 
41
- async with HTTPStaticFileSkillProvider("https://cdn.example.com/skills") as provider:
52
+ BASE = "https://cdn.example.com/skills"
53
+
54
+
55
+ async def main() -> None:
56
+ async with HTTPStaticFileSkillProvider(BASE, require_tls=True) as provider:
42
57
  registry = SkillRegistry()
43
58
  await registry.register("incident-response", provider)
44
-
45
59
  skill = registry.get_skill("incident-response")
46
- meta = await skill.get_metadata()
47
- body = await skill.get_body()
60
+ print(await skill.get_metadata())
61
+ print(await skill.get_body())
62
+
63
+
64
+ asyncio.run(main())
48
65
  ```
49
66
 
67
+ The remaining async snippets belong inside an async function. `BASE` is your skill-root URL.
68
+ Use the context manager above, or call `await provider.aclose()` in `finally`, for every
69
+ provider you create. Create a registry before snippets that register discovered skills.
70
+
50
71
  ### Custom Headers
51
72
 
52
73
  Pass authentication or other headers:
@@ -54,12 +75,15 @@ Pass authentication or other headers:
54
75
  ```python
55
76
  from agentskills_http import HTTPStaticFileSkillProvider
56
77
 
57
- provider = HTTPStaticFileSkillProvider(
78
+ async with HTTPStaticFileSkillProvider(
58
79
  "https://cdn.example.com/skills",
59
80
  headers={"Authorization": "Bearer <token>"},
60
- )
81
+ ) as provider:
82
+ print(await provider.get_body("incident-response"))
61
83
  ```
62
84
 
85
+ Replace `<token>` with a credential supplied by your deployment. Do not commit credentials.
86
+
63
87
  ### Bring Your Own Client
64
88
 
65
89
  Supply a pre-configured `httpx.AsyncClient` for full control over timeouts, proxies, etc.:
@@ -68,21 +92,28 @@ Supply a pre-configured `httpx.AsyncClient` for full control over timeouts, prox
68
92
  import httpx
69
93
  from agentskills_http import HTTPStaticFileSkillProvider
70
94
 
71
- client = httpx.AsyncClient(timeout=30, headers={"Authorization": "Bearer <token>"})
72
- provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=client)
73
- # caller is responsible for closing the client
95
+ async with httpx.AsyncClient(timeout=30, follow_redirects=False) as client:
96
+ async with HTTPStaticFileSkillProvider(
97
+ "https://cdn.example.com/skills", client=client, allow_private_network=True
98
+ ) as provider:
99
+ print(await provider.get_body("incident-response"))
74
100
  ```
75
101
 
76
102
  > **Note:** `client` and `headers` are mutually exclusive. Configure headers on the client directly when providing your own.
77
103
 
104
+ Custom clients require explicit `allow_private_network=True` because DNS,
105
+ TLS, proxies, and destination restrictions are caller-owned. Apply equivalent
106
+ network restrictions in that client when destinations are untrusted. Redirects
107
+ and response-size limits are still enforced by the provider.
108
+
78
109
  ## API
79
110
 
80
- ### `HTTPStaticFileSkillProvider(base_url, *, client=None, headers=None, params=None, require_tls=False, max_response_bytes=10_485_760, revalidate=False)`
111
+ ### `HTTPStaticFileSkillProvider(base_url, *, client=None, headers=None, params=None, require_tls=False, max_response_bytes=10_485_760, revalidate=False, resource_manifest=False, skill_manifest=False, file_manifest=False, timeout=30.0, max_retries=2, retry_backoff=0.5, max_retry_delay=30.0, allow_private_network=False, observer=None)`
81
112
 
82
113
  | Parameter | Type | Default | Description |
83
114
  | --- | --- | --- | --- |
84
- | `base_url` | `str` | - | Root URL where the skill tree is hosted |
85
- | `client` | `AsyncClient \| None` | `None` | Pre-configured httpx client (caller manages lifecycle) |
115
+ | `base_url` | `str` | - | Root URL where the skill tree is hosted. Must be HTTP(S) without credentials, query string, or fragment |
116
+ | `client` | `AsyncClient \| None` | `None` | Pre-configured httpx client (caller manages lifecycle). Requires `allow_private_network=True` |
86
117
  | `headers` | `dict \| None` | `None` | Extra headers sent with every request |
87
118
  | `params` | `dict \| None` | `None` | Query parameters appended to every request |
88
119
  | `require_tls` | `bool` | `False` | Reject `http://` URLs with `ValueError` |
@@ -95,6 +126,8 @@ provider = HTTPStaticFileSkillProvider("https://cdn.example.com/skills", client=
95
126
  | `max_retries` | `int` | `2` | Retries after the initial attempt, for retryable failures only |
96
127
  | `retry_backoff` | `float` | `0.5` | Base delay in seconds for exponential backoff |
97
128
  | `max_retry_delay` | `float` | `30.0` | Ceiling on any single backoff sleep |
129
+ | `allow_private_network` | `bool` | `False` | Opt out of public-only destinations. Required for custom clients |
130
+ | `observer` | callable or `None` | `None` | Content-free fetch/cache events with hashed origin |
98
131
 
99
132
  > **Note:** `client` and `headers`/`params` are mutually exclusive. Configure headers and params on the client directly when providing your own.
100
133
 
@@ -116,7 +149,7 @@ Supports `async with` for automatic cleanup.
116
149
 
117
150
  ## Resource Discovery
118
151
 
119
- A static file host cannot be enumerated: there is no portable directory listing over plain HTTP. By default this provider therefore reports that it *cannot* list resources — `list_resources()` raises `ResourceListingNotSupportedError` — rather than returning an empty mapping that would look like a skill with no resources.
152
+ A static file host cannot be enumerated: there is no portable directory listing over plain HTTP. By default this provider therefore reports that it *cannot* list resources (`list_resources()` raises `ResourceListingNotSupportedError`) rather than returning an empty mapping that would look like a skill with no resources.
120
153
 
121
154
  If you control the host, publish a small manifest at `{base_url}/{skill_id}/index.json`:
122
155
 
@@ -135,12 +168,12 @@ provider = HTTPStaticFileSkillProvider(BASE, resource_manifest=True)
135
168
  listing = await provider.list_resources("incident-response")
136
169
  ```
137
170
 
138
- 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.
171
+ 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.
139
172
 
140
173
  ## Lossless File Access
141
174
 
142
- For v0.6 byte-preserving delivery, publish a complete `files` list in each skill's
143
- `index.json`. This can coexist with the legacy grouped resource keys:
175
+ For byte-preserving delivery, publish a complete `files` list in each skill's
176
+ `index.json`. This can coexist with the grouped resource keys:
144
177
 
145
178
  ```json
146
179
  {
@@ -156,13 +189,13 @@ async with HTTPStaticFileSkillProvider(BASE, file_manifest=True) as provider:
156
189
  ```
157
190
 
158
191
  The host is responsible for listing every file. The provider cannot discover
159
- omitted files on a static host. Unlike legacy resource listing, unsafe paths,
192
+ omitted files on a static host. Unlike resource listing, unsafe paths,
160
193
  duplicates, non-string entries, or a missing `SKILL.md` entry reject the manifest.
161
194
  Enabling `resource_manifest` alone does not enable lossless file access.
162
195
 
163
196
  Reads preserve bytes and bypass the parsed `SKILL.md` cache. Size limits apply,
164
197
  and redirects, partial responses, and unsolicited `304` responses are refused.
165
- An injected client must have `follow_redirects=False`. Publish immutable content
198
+ An injected client must have `follow_redirects=False` and needs `allow_private_network=True`. Publish immutable content
166
199
  when building verified manifests. Listing and reading do not form an atomic snapshot.
167
200
 
168
201
  ## Skill Discovery
@@ -181,14 +214,14 @@ async with HTTPStaticFileSkillProvider(BASE, skill_manifest=True) as provider:
181
214
  await registry.register_all(provider)
182
215
  ```
183
216
 
184
- One filename and one shape — an object mapping a category to a list of names — at two depths,
217
+ One filename and one shape (an object mapping a category to a list of names) at two depths,
185
218
  rather than two manifest formats to keep in step. Unsafe and duplicate IDs are dropped as above.
186
219
  Without `skill_manifest=True`, or when the root publishes no manifest, `discover()` raises
187
220
  `DiscoveryNotSupportedError`.
188
221
 
189
222
  ## Caching
190
223
 
191
- `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.
224
+ `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.
192
225
 
193
226
  By default the cache is served until you call `invalidate()`. If your host serves mutable skills and the process is long-lived, opt into conditional revalidation instead:
194
227
 
@@ -204,12 +237,14 @@ That sends `If-None-Match` / `If-Modified-Since` on every access and reuses the
204
237
  | --- | --- | --- |
205
238
  | `404` / `410` on `SKILL.md` | `SkillNotFoundError` | No |
206
239
  | `404` / `410` on a resource | `ResourceNotFoundError` | No |
207
- | `5xx`, `408`, `425`, `429` | `SkillUnavailableError` | Yes |
208
- | Timeouts, connection and protocol errors | `SkillUnavailableError` | Yes |
240
+ | `5xx`, `408`, `425`, `429` | `ProviderUnavailableError` | Yes |
241
+ | Timeouts, connection and protocol errors | `ProviderUnavailableError` | Yes |
242
+ | Redirects (`3xx`) | `AgentSkillsError` | No |
243
+ | Destination not allowed by network policy | `NetworkPolicyError` (from `agentskills_http`) | No |
209
244
  | `401` / `403` | `AgentSkillsError` | No |
210
- | Other `4xx`, oversized responses | `AgentSkillsError` | No |
245
+ | Other `4xx`, oversized responses, invalid `Content-Length` | `AgentSkillsError` | No |
211
246
 
212
- All exceptions inherit from `AgentSkillsError`.
247
+ All exceptions inherit from `AgentSkillsError`. `ProviderUnavailableError` is a subclass of `SkillUnavailableError`, so existing handlers keep working. It is the only failure that verified stale serving in `agentskills-mcp-extension` may cover.
213
248
 
214
249
  The split between `SkillNotFoundError` and `SkillUnavailableError` is the point of the taxonomy: a `503` means the skill may well exist and the same request could succeed in a moment, whereas a `404` means it is gone. Collapsing both into "not found" turns a retryable blip into a permanent-looking failure, and nothing downstream can tell the difference.
215
250
 
@@ -226,27 +261,29 @@ provider = HTTPStaticFileSkillProvider(
226
261
  )
227
262
  ```
228
263
 
229
- Jitter matters because a registry builds its catalog concurrently — without it, every skill fetch would retry in lockstep and hit the recovering server as one wave.
264
+ Jitter matters because a registry builds its catalog concurrently: without it, every skill fetch would retry in lockstep and hit the recovering server as one wave.
230
265
 
231
266
  `Retry-After` is honoured in both the delay-seconds and HTTP-date forms. If the server asks for longer than `max_retry_delay`, the request is **not** retried: blocking a request path for minutes is worse than failing fast. The advised delay is still available to the caller as `SkillUnavailableError.retry_after`, so a scheduler can act on it.
232
267
 
233
268
  ## Security
234
269
 
235
- - **Input validation** - Skill IDs and resource names are validated against a safe-character pattern (`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`) to prevent path-traversal and injection attacks.
236
- - **TLS warnings** - A `UserWarning` is emitted when `base_url` uses unencrypted HTTP. Set `require_tls=True` to reject HTTP URLs entirely.
237
- - **Redirect protection** - The internally-created HTTP client does not follow redirects by default, preventing open-redirect SSRF.
238
- - **Timeouts** - Default 30-second timeout on all HTTP requests. Configure via `timeout`.
239
- - **Response size limits** - Responses exceeding 10 MB (default) are rejected before processing. Configure via `max_response_bytes`.
240
- - **Error-message sanitization** - Messages carry the status code and the path *relative to `base_url`* — never the host, never a query string. The underlying `httpx` exception is deliberately **not** chained (`from None`), because `httpx.HTTPStatusError` renders the full request URL including its query string, which is exactly where SAS tokens and signed-URL signatures live. Chaining it leaked credentials into every traceback.
270
+ - **Input validation**: Skill IDs and resource names are validated against a safe-character pattern (`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`) to prevent path-traversal and injection attacks.
271
+ - **TLS warnings**: A `UserWarning` is emitted when `base_url` uses unencrypted HTTP. Set `require_tls=True` to reject HTTP URLs entirely.
272
+ - **Public-network-only by default**: DNS is resolved at connection time, every answer must be a public address, and the connection goes to the validated IP, so a rebinding answer cannot reach an internal host. Loopback, private, link-local, multicast, and reserved addresses are refused. `allow_private_network=True` opts out.
273
+ - **Redirects rejected**: Redirects are never followed, in every mode, so credentials cannot be forwarded to another origin. Environment proxies are not inherited.
274
+ - **Credential-free `base_url`**: Userinfo, query strings, and fragments are refused. Pass credentials through `headers` or `params`.
275
+ - **Timeouts**: Default 30-second timeout on all HTTP requests. Configure via `timeout`.
276
+ - **Response size limits**: Responses exceeding 10 MB (default) are rejected before processing. Configure via `max_response_bytes`.
277
+ - **Error-message sanitization**: Messages carry the status code and the path *relative to `base_url`*, never the host, never a query string. The underlying `httpx` exception is deliberately **not** chained (`from None`), because `httpx.HTTPStatusError` renders the full request URL including its query string, which is exactly where SAS tokens and signed-URL signatures live. Chaining it leaked credentials into every traceback.
241
278
 
242
279
  For the full security policy, see [SECURITY.md](https://github.com/pratikxpanda/agentskills-sdk/blob/main/SECURITY.md).
243
280
 
244
281
  ## Deployment Considerations
245
282
 
246
- - **Rate limiting** - The SDK does not enforce rate limits on MCP tool
247
- calls or HTTP requests. Deploy behind a reverse proxy or API gateway
248
- that provides rate limiting in production environments.
249
- - **Credential management** - Do not store secrets (API keys, SAS
283
+ - **Rate limiting**: The SDK does not enforce rate limits on HTTP requests or
284
+ MCP requests. Deploy behind a reverse proxy or API gateway that provides rate
285
+ limiting in production environments.
286
+ - **Credential management**: Do not store secrets (API keys, SAS
250
287
  tokens, Authorization headers) in config files committed to version
251
288
  control. Use environment variables or a secret manager instead.
252
289
 
@@ -11,6 +11,7 @@ Install::
11
11
  pip install agentskills-http
12
12
  """
13
13
 
14
+ from agentskills_http.network import NetworkPolicyError
14
15
  from agentskills_http.static import HTTPStaticFileSkillProvider
15
16
 
16
- __all__ = ["HTTPStaticFileSkillProvider"]
17
+ __all__ = ["HTTPStaticFileSkillProvider", "NetworkPolicyError"]
@@ -0,0 +1,135 @@
1
+ """DNS-pinned outbound HTTP transport with explicit private-network policy."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import ipaddress
7
+ import socket
8
+ import ssl
9
+ from collections.abc import AsyncIterator, Iterator
10
+ from contextlib import contextmanager
11
+ from typing import Any
12
+
13
+ import httpcore
14
+ import httpx
15
+
16
+ from agentskills_core.exceptions import AgentSkillsError
17
+
18
+
19
+ class NetworkPolicyError(AgentSkillsError):
20
+ """A destination or redirect violates configured outbound policy."""
21
+
22
+
23
+ class GuardedBackend(httpcore.AsyncNetworkBackend):
24
+ """Resolve once per connection, validate every answer, and connect to an IP.
25
+
26
+ HTTPcore retains the original hostname for TLS SNI and certificate checks.
27
+ No proxy or environment-selected transport can bypass this backend.
28
+ """
29
+
30
+ def __init__(self, *, allow_private_network: bool = False) -> None:
31
+ self._allow_private = allow_private_network
32
+ self._backend = httpcore.AnyIOBackend()
33
+
34
+ async def connect_tcp(
35
+ self,
36
+ host: str,
37
+ port: int,
38
+ timeout: float | None = None,
39
+ local_address: str | None = None,
40
+ socket_options: Any = None,
41
+ ) -> httpcore.AsyncNetworkStream:
42
+ """Connect only to an address from this request's validated DNS answer."""
43
+ try:
44
+ async with asyncio.timeout(timeout):
45
+ answers = await asyncio.get_running_loop().getaddrinfo(
46
+ host, port, type=socket.SOCK_STREAM
47
+ )
48
+ addresses = [answer[4][0] for answer in answers]
49
+ if not addresses:
50
+ raise httpcore.ConnectError("Destination did not resolve")
51
+ for address in addresses:
52
+ parsed = ipaddress.ip_address(address.split("%", 1)[0])
53
+ mapped = getattr(parsed, "ipv4_mapped", None)
54
+ if not self._allow_private and (
55
+ not parsed.is_global
56
+ or parsed.is_multicast
57
+ or parsed.is_reserved
58
+ or (mapped is not None and not mapped.is_global)
59
+ or "%" in address
60
+ ):
61
+ raise NetworkPolicyError("Destination is not a public network address")
62
+ return await self._backend.connect_tcp(
63
+ addresses[0], port, timeout, local_address, socket_options
64
+ )
65
+ except TimeoutError:
66
+ raise httpcore.ConnectTimeout("Destination connection timed out") from None
67
+ except OSError:
68
+ raise httpcore.ConnectError("Destination resolution or connection failed") from None
69
+
70
+
71
+ @contextmanager
72
+ def _translate_errors() -> Iterator[None]:
73
+ try:
74
+ yield
75
+ except httpcore.TimeoutException:
76
+ raise httpx.TimeoutException("HTTP transport timed out") from None
77
+ except httpcore.NetworkError:
78
+ raise httpx.NetworkError("HTTP network failure") from None
79
+ except httpcore.ProtocolError:
80
+ raise httpx.ProtocolError("HTTP protocol failure") from None
81
+
82
+
83
+ class _ResponseStream(httpx.AsyncByteStream):
84
+ def __init__(self, response: httpcore.Response) -> None:
85
+ self._response = response
86
+
87
+ async def __aiter__(self) -> AsyncIterator[bytes]:
88
+ with _translate_errors():
89
+ async for chunk in self._response.aiter_stream():
90
+ yield chunk
91
+
92
+ async def aclose(self) -> None:
93
+ with _translate_errors():
94
+ await self._response.aclose()
95
+
96
+
97
+ class GuardedTransport(httpx.AsyncBaseTransport):
98
+ """HTTPX adapter using public HTTPcore interfaces and a guarded network backend."""
99
+
100
+ def __init__(self, *, allow_private_network: bool = False) -> None:
101
+ self._pool = httpcore.AsyncConnectionPool(
102
+ ssl_context=ssl.create_default_context(),
103
+ network_backend=GuardedBackend(allow_private_network=allow_private_network),
104
+ max_connections=10,
105
+ max_keepalive_connections=5,
106
+ keepalive_expiry=5,
107
+ )
108
+
109
+ async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
110
+ """Send the original hostname and headers through the DNS-pinned pool."""
111
+ with _translate_errors():
112
+ response = await self._pool.handle_async_request(
113
+ httpcore.Request(
114
+ method=request.method,
115
+ url=httpcore.URL(
116
+ scheme=request.url.raw_scheme,
117
+ host=request.url.raw_host,
118
+ port=request.url.port,
119
+ target=request.url.raw_path,
120
+ ),
121
+ headers=request.headers.raw,
122
+ content=request.stream,
123
+ extensions=request.extensions,
124
+ )
125
+ )
126
+ return httpx.Response(
127
+ response.status,
128
+ headers=response.headers,
129
+ stream=_ResponseStream(response),
130
+ extensions=response.extensions,
131
+ )
132
+
133
+ async def aclose(self) -> None:
134
+ """Close only the connections owned by this transport."""
135
+ await self._pool.aclose()
@@ -37,9 +37,11 @@ import json
37
37
  import random
38
38
  import re
39
39
  import warnings
40
+ from collections.abc import Callable
40
41
  from dataclasses import dataclass
41
42
  from datetime import UTC, datetime
42
43
  from email.utils import parsedate_to_datetime
44
+ from time import monotonic
43
45
  from typing import Any
44
46
  from urllib.parse import quote, urlparse
45
47
 
@@ -59,6 +61,9 @@ from agentskills_core import (
59
61
  redact_url,
60
62
  split_frontmatter,
61
63
  )
64
+ from agentskills_core.exceptions import ProviderUnavailableError
65
+ from agentskills_core.telemetry import DisclosureEvent, emit_event
66
+ from agentskills_http.network import GuardedTransport
62
67
 
63
68
  _logger = get_logger(__name__)
64
69
 
@@ -144,9 +149,8 @@ class HTTPStaticFileSkillProvider(SkillProvider):
144
149
  slash is stripped automatically.
145
150
  client: Optional pre-configured :class:`httpx.AsyncClient`.
146
151
  When provided, the caller is responsible for closing it.
147
- The provider will still enforce *max_response_bytes* but
148
- will **not** override the client's timeout or redirect
149
- settings.
152
+ Requires explicit ``allow_private_network=True`` because the
153
+ caller owns DNS, TLS, timeout, and network policy. Redirects remain disabled.
150
154
  headers: Optional extra headers sent with every request (e.g.
151
155
  ``Authorization``).
152
156
  params: Optional query parameters appended to every request
@@ -195,6 +199,9 @@ class HTTPStaticFileSkillProvider(SkillProvider):
195
199
  immediately with ``retry_after`` attached, because blocking
196
200
  a request path for minutes is worse than failing fast and
197
201
  letting the caller decide.
202
+ allow_private_network: Explicitly allow internal destinations. Default
203
+ owned transports pin validated public DNS addresses at connection time.
204
+ observer: Optional content-free operation observer. Never receives credentials.
198
205
 
199
206
  ``SKILL.md`` responses are cached per provider instance, because a
200
207
  single skill is otherwise re-fetched up to five times in one agent
@@ -229,6 +236,8 @@ class HTTPStaticFileSkillProvider(SkillProvider):
229
236
  max_retries: int = DEFAULT_MAX_RETRIES,
230
237
  retry_backoff: float = DEFAULT_RETRY_BACKOFF_SECONDS,
231
238
  max_retry_delay: float = DEFAULT_MAX_RETRY_DELAY_SECONDS,
239
+ allow_private_network: bool = False,
240
+ observer: Callable[[DisclosureEvent], None] | None = None,
232
241
  ) -> None:
233
242
  if client is not None and (headers is not None or params is not None):
234
243
  raise ValueError(
@@ -245,9 +254,24 @@ class HTTPStaticFileSkillProvider(SkillProvider):
245
254
  raise ValueError("retry_backoff must be positive")
246
255
  if max_retry_delay <= 0:
247
256
  raise ValueError("max_retry_delay must be positive")
257
+ if type(allow_private_network) is not bool:
258
+ raise ValueError("allow_private_network must be an explicit boolean")
259
+ if client is not None and not allow_private_network:
260
+ raise ValueError("A custom client requires explicit allow_private_network=True")
248
261
 
249
262
  # TLS enforcement
250
263
  parsed = urlparse(base_url)
264
+ if (
265
+ parsed.scheme not in {"http", "https"}
266
+ or not parsed.hostname
267
+ or parsed.username is not None
268
+ or parsed.password is not None
269
+ or parsed.query
270
+ or parsed.fragment
271
+ ):
272
+ raise ValueError(
273
+ "base_url must be an HTTP(S) URL without credentials, query, or fragment"
274
+ )
251
275
  if parsed.scheme == "http":
252
276
  if require_tls:
253
277
  raise ValueError(
@@ -263,6 +287,7 @@ class HTTPStaticFileSkillProvider(SkillProvider):
263
287
  )
264
288
 
265
289
  self._base_url = base_url.rstrip("/")
290
+ self._observer = observer
266
291
  self._max_response_bytes = max_response_bytes
267
292
  self._revalidate = revalidate
268
293
  self._skill_md_cache: dict[str, _CachedSkillMd] = {}
@@ -278,6 +303,8 @@ class HTTPStaticFileSkillProvider(SkillProvider):
278
303
  params=params,
279
304
  timeout=httpx.Timeout(timeout),
280
305
  follow_redirects=False,
306
+ trust_env=False,
307
+ transport=GuardedTransport(allow_private_network=allow_private_network),
281
308
  )
282
309
 
283
310
  async def aclose(self) -> None:
@@ -537,7 +564,7 @@ class HTTPStaticFileSkillProvider(SkillProvider):
537
564
  """Return the complete, sorted file list without fetching file contents.
538
565
 
539
566
  The host must publish ``{"files": ["SKILL.md", "data/nested.bin"]}``
540
- in the skill's ``index.json``. This is separate from legacy grouped
567
+ in the skill's ``index.json``. This is separate from grouped
541
568
  resource listing and must include every supporting file.
542
569
  """
543
570
  if not self.supports_file_access:
@@ -638,6 +665,37 @@ class HTTPStaticFileSkillProvider(SkillProvider):
638
665
  not_found_error: type[Exception],
639
666
  *,
640
667
  extra_headers: dict[str, str] | None = None,
668
+ ) -> tuple[bytes | None, httpx.Headers]:
669
+ started = monotonic()
670
+ try:
671
+ data, headers = await self._stream_with_retries(
672
+ url, not_found_error, extra_headers=extra_headers
673
+ )
674
+ except Exception:
675
+ emit_event(
676
+ self._observer,
677
+ "fetch",
678
+ origin=self._base_url,
679
+ status="error",
680
+ duration_seconds=monotonic() - started,
681
+ )
682
+ raise
683
+ emit_event(
684
+ self._observer,
685
+ "fetch",
686
+ origin=self._base_url,
687
+ byte_count=0 if data is None else len(data),
688
+ cache_hit=data is None,
689
+ duration_seconds=monotonic() - started,
690
+ )
691
+ return data, headers
692
+
693
+ async def _stream_with_retries(
694
+ self,
695
+ url: str,
696
+ not_found_error: type[Exception],
697
+ *,
698
+ extra_headers: dict[str, str] | None = None,
641
699
  ) -> tuple[bytes | None, httpx.Headers]:
642
700
  """Fetch *url*, retrying retryable failures with jittered backoff.
643
701
 
@@ -707,17 +765,19 @@ class HTTPStaticFileSkillProvider(SkillProvider):
707
765
  "GET",
708
766
  url,
709
767
  headers=extra_headers,
710
- follow_redirects=False if self.supports_file_access else httpx.USE_CLIENT_DEFAULT,
768
+ follow_redirects=False,
711
769
  ) as resp:
712
770
  status = resp.status_code
713
771
  if status in _NOT_FOUND_STATUS_CODES:
714
772
  raise not_found_error(f"Skill content not found at {safe_url}")
715
773
  if status == 304:
716
774
  return None, resp.headers
775
+ if 300 <= status < 400:
776
+ raise AgentSkillsError(f"HTTP {status} redirect is disabled by network policy")
717
777
  if self.supports_file_access and status != 200 and status < 400:
718
778
  raise AgentSkillsError(f"HTTP {status} is not a complete file response")
719
779
  if status in _RETRYABLE_STATUS_CODES or status >= 500:
720
- raise SkillUnavailableError(
780
+ raise ProviderUnavailableError(
721
781
  f"HTTP {status} from {safe_url}",
722
782
  retry_after=_parse_retry_after(resp.headers.get("retry-after")),
723
783
  )
@@ -734,7 +794,13 @@ class HTTPStaticFileSkillProvider(SkillProvider):
734
794
  # Check Content-Length header for an early reject when
735
795
  # the server advertises the size up-front.
736
796
  cl = resp.headers.get("content-length")
737
- if cl is not None and int(cl) > self._max_response_bytes:
797
+ try:
798
+ content_length = None if cl is None else int(cl)
799
+ except ValueError:
800
+ raise AgentSkillsError("Invalid Content-Length header") from None
801
+ if content_length is not None and content_length < 0:
802
+ raise AgentSkillsError("Invalid Content-Length header")
803
+ if content_length is not None and content_length > self._max_response_bytes:
738
804
  raise AgentSkillsError(
739
805
  f"Response exceeds maximum size ({self._max_response_bytes} bytes)"
740
806
  )
@@ -755,7 +821,9 @@ class HTTPStaticFileSkillProvider(SkillProvider):
755
821
  except (SkillNotFoundError, ResourceNotFoundError, AgentSkillsError):
756
822
  raise
757
823
  except (httpx.TimeoutException, httpx.NetworkError, httpx.ProtocolError) as exc:
758
- raise SkillUnavailableError(f"{type(exc).__name__} while fetching {safe_url}") from None
824
+ raise ProviderUnavailableError(
825
+ f"{type(exc).__name__} while fetching {safe_url}"
826
+ ) from None
759
827
  except httpx.HTTPError as exc:
760
828
  raise AgentSkillsError(f"{type(exc).__name__} while fetching {safe_url}") from None
761
829
 
@@ -781,6 +849,7 @@ class HTTPStaticFileSkillProvider(SkillProvider):
781
849
  cached = self._skill_md_cache.get(skill_id)
782
850
  if cached is not None and not self._revalidate:
783
851
  _logger.debug("Cache hit for SKILL.md of %r", skill_id)
852
+ emit_event(self._observer, "cache", origin=self._base_url, cache_hit=True)
784
853
  return cached.text
785
854
 
786
855
  conditional: dict[str, str] = {}
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "agentskills-http"
3
- version = "0.6.0"
3
+ version = "0.8.0"
4
4
  description = "HTTP-based skill providers for the Agent Skills format (https://agentskills.io)"
5
5
  license = "MIT"
6
6
  authors = ["Pratik Panda"]
@@ -19,8 +19,9 @@ classifiers = [
19
19
 
20
20
  [tool.poetry.dependencies]
21
21
  python = ">=3.12,<4.0"
22
- agentskills-core = ">=0.6.0,<1.0"
22
+ agentskills-core = ">=0.8.0,<1.0"
23
23
  httpx = ">=0.27,<1.0"
24
+ httpcore = ">=1.0.9,<2.0"
24
25
  pyyaml = ">=6.0,<7.0"
25
26
 
26
27
  [build-system]