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.
- {agentskills_http-0.6.0 → agentskills_http-0.8.0}/PKG-INFO +78 -40
- {agentskills_http-0.6.0 → agentskills_http-0.8.0}/README.md +75 -38
- {agentskills_http-0.6.0 → agentskills_http-0.8.0}/agentskills_http/__init__.py +2 -1
- agentskills_http-0.8.0/agentskills_http/network.py +135 -0
- {agentskills_http-0.6.0 → agentskills_http-0.8.0}/agentskills_http/static.py +77 -8
- {agentskills_http-0.6.0 → agentskills_http-0.8.0}/pyproject.toml +3 -2
- {agentskills_http-0.6.0 → agentskills_http-0.8.0}/agentskills_http/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: agentskills-http
|
|
3
|
-
Version: 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.
|
|
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:
|
|
27
|
+
description: Read skills from static HTTP hosts with explicit manifests and network controls.
|
|
27
28
|
---
|
|
28
29
|
|
|
29
30
|
[](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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
70
|
-
|
|
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
|
-
|
|
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
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
|
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
|
|
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
|
|
166
|
-
`index.json`. This can coexist with the
|
|
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
|
|
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
|
|
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
|
|
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` | `
|
|
231
|
-
| Timeouts, connection and protocol errors | `
|
|
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
|
|
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
|
|
259
|
-
- **TLS warnings
|
|
260
|
-
- **
|
|
261
|
-
- **
|
|
262
|
-
- **
|
|
263
|
-
- **
|
|
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
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
- **Credential management
|
|
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:
|
|
3
|
+
description: Read skills from static HTTP hosts with explicit manifests and network controls.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
[](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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
47
|
-
|
|
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
|
-
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
|
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
|
|
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
|
|
143
|
-
`index.json`. This can coexist with the
|
|
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
|
|
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
|
|
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
|
|
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` | `
|
|
208
|
-
| Timeouts, connection and protocol errors | `
|
|
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
|
|
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
|
|
236
|
-
- **TLS warnings
|
|
237
|
-
- **
|
|
238
|
-
- **
|
|
239
|
-
- **
|
|
240
|
-
- **
|
|
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
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
- **Credential management
|
|
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
|
-
|
|
148
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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]
|
|
File without changes
|