agentskills-http 0.7.0__tar.gz → 0.9.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.7.0 → agentskills_http-0.9.0}/PKG-INFO +50 -32
- {agentskills_http-0.7.0 → agentskills_http-0.9.0}/README.md +48 -30
- {agentskills_http-0.7.0 → agentskills_http-0.9.0}/pyproject.toml +2 -2
- {agentskills_http-0.7.0 → agentskills_http-0.9.0}/agentskills_http/__init__.py +0 -0
- {agentskills_http-0.7.0 → agentskills_http-0.9.0}/agentskills_http/network.py +0 -0
- {agentskills_http-0.7.0 → agentskills_http-0.9.0}/agentskills_http/py.typed +0 -0
- {agentskills_http-0.7.0 → agentskills_http-0.9.0}/agentskills_http/static.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: agentskills-http
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.9.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,7 @@ 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.9.0,<0.10.0)
|
|
18
18
|
Requires-Dist: httpcore (>=1.0.9,<2.0)
|
|
19
19
|
Requires-Dist: httpx (>=0.27,<1.0)
|
|
20
20
|
Requires-Dist: pyyaml (>=6.0,<7.0)
|
|
@@ -24,7 +24,7 @@ Description-Content-Type: text/markdown
|
|
|
24
24
|
|
|
25
25
|
---
|
|
26
26
|
title: agentskills-http
|
|
27
|
-
description:
|
|
27
|
+
description: Read skills from static HTTP hosts with explicit manifests and network controls.
|
|
28
28
|
---
|
|
29
29
|
|
|
30
30
|
[](https://pypi.org/project/agentskills-http/)
|
|
@@ -33,7 +33,7 @@ description: Static HTTP file provider for Agent Skills.
|
|
|
33
33
|
|
|
34
34
|
> HTTP static-file skill provider for the [Agent Skills SDK](https://github.com/pratikxpanda/agentskills-sdk).
|
|
35
35
|
|
|
36
|
-
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.
|
|
37
37
|
|
|
38
38
|
## Installation
|
|
39
39
|
|
|
@@ -43,7 +43,7 @@ pip install agentskills-http
|
|
|
43
43
|
|
|
44
44
|
Requires Python 3.12 or newer. Installs `agentskills-core`, `httpx`, `httpcore`, and `pyyaml`.
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
Connections default to public-network destinations only. DNS answers are validated
|
|
47
47
|
at connection time and the connection is pinned to an approved IP. Redirects
|
|
48
48
|
are rejected and environment proxies are not inherited. Internal hosts require
|
|
49
49
|
`allow_private_network=True`. Use `require_tls=True` for production sources.
|
|
@@ -64,19 +64,34 @@ https://cdn.example.com/skills/
|
|
|
64
64
|
|
|
65
65
|
## Usage
|
|
66
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
|
+
|
|
67
70
|
```python
|
|
71
|
+
import asyncio
|
|
72
|
+
|
|
68
73
|
from agentskills_core import SkillRegistry
|
|
69
74
|
from agentskills_http import HTTPStaticFileSkillProvider
|
|
70
75
|
|
|
71
|
-
|
|
76
|
+
BASE = "https://cdn.example.com/skills"
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
async def main() -> None:
|
|
80
|
+
async with HTTPStaticFileSkillProvider(BASE, require_tls=True) as provider:
|
|
72
81
|
registry = SkillRegistry()
|
|
73
82
|
await registry.register("incident-response", provider)
|
|
74
|
-
|
|
75
83
|
skill = registry.get_skill("incident-response")
|
|
76
|
-
|
|
77
|
-
|
|
84
|
+
print(await skill.get_metadata())
|
|
85
|
+
print(await skill.get_body())
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
asyncio.run(main())
|
|
78
89
|
```
|
|
79
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
|
+
|
|
80
95
|
### Custom Headers
|
|
81
96
|
|
|
82
97
|
Pass authentication or other headers:
|
|
@@ -84,12 +99,15 @@ Pass authentication or other headers:
|
|
|
84
99
|
```python
|
|
85
100
|
from agentskills_http import HTTPStaticFileSkillProvider
|
|
86
101
|
|
|
87
|
-
|
|
102
|
+
async with HTTPStaticFileSkillProvider(
|
|
88
103
|
"https://cdn.example.com/skills",
|
|
89
104
|
headers={"Authorization": "Bearer <token>"},
|
|
90
|
-
)
|
|
105
|
+
) as provider:
|
|
106
|
+
print(await provider.get_body("incident-response"))
|
|
91
107
|
```
|
|
92
108
|
|
|
109
|
+
Replace `<token>` with a credential supplied by your deployment. Do not commit credentials.
|
|
110
|
+
|
|
93
111
|
### Bring Your Own Client
|
|
94
112
|
|
|
95
113
|
Supply a pre-configured `httpx.AsyncClient` for full control over timeouts, proxies, etc.:
|
|
@@ -98,11 +116,11 @@ Supply a pre-configured `httpx.AsyncClient` for full control over timeouts, prox
|
|
|
98
116
|
import httpx
|
|
99
117
|
from agentskills_http import HTTPStaticFileSkillProvider
|
|
100
118
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
)
|
|
105
|
-
|
|
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"))
|
|
106
124
|
```
|
|
107
125
|
|
|
108
126
|
> **Note:** `client` and `headers` are mutually exclusive. Configure headers on the client directly when providing your own.
|
|
@@ -155,7 +173,7 @@ Supports `async with` for automatic cleanup.
|
|
|
155
173
|
|
|
156
174
|
## Resource Discovery
|
|
157
175
|
|
|
158
|
-
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.
|
|
159
177
|
|
|
160
178
|
If you control the host, publish a small manifest at `{base_url}/{skill_id}/index.json`:
|
|
161
179
|
|
|
@@ -174,7 +192,7 @@ provider = HTTPStaticFileSkillProvider(BASE, resource_manifest=True)
|
|
|
174
192
|
listing = await provider.list_resources("incident-response")
|
|
175
193
|
```
|
|
176
194
|
|
|
177
|
-
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.
|
|
178
196
|
|
|
179
197
|
## Lossless File Access
|
|
180
198
|
|
|
@@ -220,14 +238,14 @@ async with HTTPStaticFileSkillProvider(BASE, skill_manifest=True) as provider:
|
|
|
220
238
|
await registry.register_all(provider)
|
|
221
239
|
```
|
|
222
240
|
|
|
223
|
-
One filename and one shape
|
|
241
|
+
One filename and one shape (an object mapping a category to a list of names) at two depths,
|
|
224
242
|
rather than two manifest formats to keep in step. Unsafe and duplicate IDs are dropped as above.
|
|
225
243
|
Without `skill_manifest=True`, or when the root publishes no manifest, `discover()` raises
|
|
226
244
|
`DiscoveryNotSupportedError`.
|
|
227
245
|
|
|
228
246
|
## Caching
|
|
229
247
|
|
|
230
|
-
`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.
|
|
231
249
|
|
|
232
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:
|
|
233
251
|
|
|
@@ -250,7 +268,7 @@ That sends `If-None-Match` / `If-Modified-Since` on every access and reuses the
|
|
|
250
268
|
| `401` / `403` | `AgentSkillsError` | No |
|
|
251
269
|
| Other `4xx`, oversized responses, invalid `Content-Length` | `AgentSkillsError` | No |
|
|
252
270
|
|
|
253
|
-
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-
|
|
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.
|
|
254
272
|
|
|
255
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.
|
|
256
274
|
|
|
@@ -267,29 +285,29 @@ provider = HTTPStaticFileSkillProvider(
|
|
|
267
285
|
)
|
|
268
286
|
```
|
|
269
287
|
|
|
270
|
-
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.
|
|
271
289
|
|
|
272
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.
|
|
273
291
|
|
|
274
292
|
## Security
|
|
275
293
|
|
|
276
|
-
- **Input validation
|
|
277
|
-
- **TLS warnings
|
|
278
|
-
- **Public-network-only by default
|
|
279
|
-
- **Redirects rejected
|
|
280
|
-
- **Credential-free `base_url
|
|
281
|
-
- **Timeouts
|
|
282
|
-
- **Response size limits
|
|
283
|
-
- **Error-message sanitization
|
|
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.
|
|
284
302
|
|
|
285
303
|
For the full security policy, see [SECURITY.md](https://github.com/pratikxpanda/agentskills-sdk/blob/main/SECURITY.md).
|
|
286
304
|
|
|
287
305
|
## Deployment Considerations
|
|
288
306
|
|
|
289
|
-
- **Rate limiting
|
|
307
|
+
- **Rate limiting**: The SDK does not enforce rate limits on HTTP requests or
|
|
290
308
|
MCP requests. Deploy behind a reverse proxy or API gateway that provides rate
|
|
291
309
|
limiting in production environments.
|
|
292
|
-
- **Credential management
|
|
310
|
+
- **Credential management**: Do not store secrets (API keys, SAS
|
|
293
311
|
tokens, Authorization headers) in config files committed to version
|
|
294
312
|
control. Use environment variables or a secret manager instead.
|
|
295
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
|
|
|
@@ -19,7 +19,7 @@ pip install agentskills-http
|
|
|
19
19
|
|
|
20
20
|
Requires Python 3.12 or newer. Installs `agentskills-core`, `httpx`, `httpcore`, and `pyyaml`.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Connections default to public-network destinations only. DNS answers are validated
|
|
23
23
|
at connection time and the connection is pinned to an approved IP. Redirects
|
|
24
24
|
are rejected and environment proxies are not inherited. Internal hosts require
|
|
25
25
|
`allow_private_network=True`. Use `require_tls=True` for production sources.
|
|
@@ -40,19 +40,34 @@ https://cdn.example.com/skills/
|
|
|
40
40
|
|
|
41
41
|
## Usage
|
|
42
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
|
+
|
|
43
46
|
```python
|
|
47
|
+
import asyncio
|
|
48
|
+
|
|
44
49
|
from agentskills_core import SkillRegistry
|
|
45
50
|
from agentskills_http import HTTPStaticFileSkillProvider
|
|
46
51
|
|
|
47
|
-
|
|
52
|
+
BASE = "https://cdn.example.com/skills"
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
async def main() -> None:
|
|
56
|
+
async with HTTPStaticFileSkillProvider(BASE, require_tls=True) as provider:
|
|
48
57
|
registry = SkillRegistry()
|
|
49
58
|
await registry.register("incident-response", provider)
|
|
50
|
-
|
|
51
59
|
skill = registry.get_skill("incident-response")
|
|
52
|
-
|
|
53
|
-
|
|
60
|
+
print(await skill.get_metadata())
|
|
61
|
+
print(await skill.get_body())
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
asyncio.run(main())
|
|
54
65
|
```
|
|
55
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
|
+
|
|
56
71
|
### Custom Headers
|
|
57
72
|
|
|
58
73
|
Pass authentication or other headers:
|
|
@@ -60,12 +75,15 @@ Pass authentication or other headers:
|
|
|
60
75
|
```python
|
|
61
76
|
from agentskills_http import HTTPStaticFileSkillProvider
|
|
62
77
|
|
|
63
|
-
|
|
78
|
+
async with HTTPStaticFileSkillProvider(
|
|
64
79
|
"https://cdn.example.com/skills",
|
|
65
80
|
headers={"Authorization": "Bearer <token>"},
|
|
66
|
-
)
|
|
81
|
+
) as provider:
|
|
82
|
+
print(await provider.get_body("incident-response"))
|
|
67
83
|
```
|
|
68
84
|
|
|
85
|
+
Replace `<token>` with a credential supplied by your deployment. Do not commit credentials.
|
|
86
|
+
|
|
69
87
|
### Bring Your Own Client
|
|
70
88
|
|
|
71
89
|
Supply a pre-configured `httpx.AsyncClient` for full control over timeouts, proxies, etc.:
|
|
@@ -74,11 +92,11 @@ Supply a pre-configured `httpx.AsyncClient` for full control over timeouts, prox
|
|
|
74
92
|
import httpx
|
|
75
93
|
from agentskills_http import HTTPStaticFileSkillProvider
|
|
76
94
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
)
|
|
81
|
-
|
|
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"))
|
|
82
100
|
```
|
|
83
101
|
|
|
84
102
|
> **Note:** `client` and `headers` are mutually exclusive. Configure headers on the client directly when providing your own.
|
|
@@ -131,7 +149,7 @@ Supports `async with` for automatic cleanup.
|
|
|
131
149
|
|
|
132
150
|
## Resource Discovery
|
|
133
151
|
|
|
134
|
-
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.
|
|
135
153
|
|
|
136
154
|
If you control the host, publish a small manifest at `{base_url}/{skill_id}/index.json`:
|
|
137
155
|
|
|
@@ -150,7 +168,7 @@ provider = HTTPStaticFileSkillProvider(BASE, resource_manifest=True)
|
|
|
150
168
|
listing = await provider.list_resources("incident-response")
|
|
151
169
|
```
|
|
152
170
|
|
|
153
|
-
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.
|
|
154
172
|
|
|
155
173
|
## Lossless File Access
|
|
156
174
|
|
|
@@ -196,14 +214,14 @@ async with HTTPStaticFileSkillProvider(BASE, skill_manifest=True) as provider:
|
|
|
196
214
|
await registry.register_all(provider)
|
|
197
215
|
```
|
|
198
216
|
|
|
199
|
-
One filename and one shape
|
|
217
|
+
One filename and one shape (an object mapping a category to a list of names) at two depths,
|
|
200
218
|
rather than two manifest formats to keep in step. Unsafe and duplicate IDs are dropped as above.
|
|
201
219
|
Without `skill_manifest=True`, or when the root publishes no manifest, `discover()` raises
|
|
202
220
|
`DiscoveryNotSupportedError`.
|
|
203
221
|
|
|
204
222
|
## Caching
|
|
205
223
|
|
|
206
|
-
`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.
|
|
207
225
|
|
|
208
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:
|
|
209
227
|
|
|
@@ -226,7 +244,7 @@ That sends `If-None-Match` / `If-Modified-Since` on every access and reuses the
|
|
|
226
244
|
| `401` / `403` | `AgentSkillsError` | No |
|
|
227
245
|
| Other `4xx`, oversized responses, invalid `Content-Length` | `AgentSkillsError` | No |
|
|
228
246
|
|
|
229
|
-
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-
|
|
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.
|
|
230
248
|
|
|
231
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.
|
|
232
250
|
|
|
@@ -243,29 +261,29 @@ provider = HTTPStaticFileSkillProvider(
|
|
|
243
261
|
)
|
|
244
262
|
```
|
|
245
263
|
|
|
246
|
-
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.
|
|
247
265
|
|
|
248
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.
|
|
249
267
|
|
|
250
268
|
## Security
|
|
251
269
|
|
|
252
|
-
- **Input validation
|
|
253
|
-
- **TLS warnings
|
|
254
|
-
- **Public-network-only by default
|
|
255
|
-
- **Redirects rejected
|
|
256
|
-
- **Credential-free `base_url
|
|
257
|
-
- **Timeouts
|
|
258
|
-
- **Response size limits
|
|
259
|
-
- **Error-message sanitization
|
|
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.
|
|
260
278
|
|
|
261
279
|
For the full security policy, see [SECURITY.md](https://github.com/pratikxpanda/agentskills-sdk/blob/main/SECURITY.md).
|
|
262
280
|
|
|
263
281
|
## Deployment Considerations
|
|
264
282
|
|
|
265
|
-
- **Rate limiting
|
|
283
|
+
- **Rate limiting**: The SDK does not enforce rate limits on HTTP requests or
|
|
266
284
|
MCP requests. Deploy behind a reverse proxy or API gateway that provides rate
|
|
267
285
|
limiting in production environments.
|
|
268
|
-
- **Credential management
|
|
286
|
+
- **Credential management**: Do not store secrets (API keys, SAS
|
|
269
287
|
tokens, Authorization headers) in config files committed to version
|
|
270
288
|
control. Use environment variables or a secret manager instead.
|
|
271
289
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[tool.poetry]
|
|
2
2
|
name = "agentskills-http"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.9.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,7 +19,7 @@ classifiers = [
|
|
|
19
19
|
|
|
20
20
|
[tool.poetry.dependencies]
|
|
21
21
|
python = ">=3.12,<4.0"
|
|
22
|
-
agentskills-core = ">=0.
|
|
22
|
+
agentskills-core = ">=0.9.0,<0.10.0"
|
|
23
23
|
httpx = ">=0.27,<1.0"
|
|
24
24
|
httpcore = ">=1.0.9,<2.0"
|
|
25
25
|
pyyaml = ">=6.0,<7.0"
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|