Skip to content

Commit 07d77f6

Browse files
RhosmarieRhosmarie
authored
Merge pull request #1166 from Rhosmarie/feat/skill_tos
feat(harness): load skills directly from TOS sources
2 parents a7569a0 + 4bf324c commit 07d77f6

13 files changed

Lines changed: 1318 additions & 16 deletions

File tree

‎.github/workflows/harness-sidecar-release-gate.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ jobs:
8686
backend-gate:
8787
name: Backend gate
8888
runs-on: ubuntu-latest
89-
timeout-minutes: 3
89+
timeout-minutes: 10
9090
steps:
9191
- uses: actions/checkout@v4
9292

@@ -236,5 +236,7 @@ jobs:
236236
BACKEND_RESULT: ${{ needs.backend-gate.result }}
237237
FRONTEND_RESULT: ${{ needs.frontend-gate.result }}
238238
run: |
239+
echo "Backend gate result: $BACKEND_RESULT"
240+
echo "Frontend gate result: $FRONTEND_RESULT"
239241
test "$BACKEND_RESULT" = success
240242
test "$FRONTEND_RESULT" = success

‎prd-spec/features/harness-tos-skills/2026-10-12-harness-tos-skills.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Harness TOS Skills
2+
3+
[中文版](2026-10-12-harness-tos-skills.zh.md)
4+
5+
## Metadata
6+
7+
| Field | Value |
8+
| --- | --- |
9+
| Change ID | `harness-tos-skills` |
10+
| Created | 2026-10-12 |
11+
| Status | implemented |
12+
| Related specs | No component spec update; this extends the existing Harness selected-skill request contract without changing ownership boundaries. |
13+
14+
## Background And Evidence
15+
16+
Harness can already load SkillHub skills and Skill Space skills. Skill Space loading eventually downloads TOS-backed Skill archives through the existing materializer, but callers cannot directly provide an object-storage Skill directory.
17+
18+
The requested behavior should align with AWS AgentCore Harness S3 skills: one object-storage URI points to one Skill directory containing `SKILL.md`; multiple Skills are represented as multiple selected-skill entries.
19+
20+
## Goals
21+
22+
- Add `source="tos"` to `HarnessSelectedSkill`.
23+
- Support current-account TOS directories via Runtime cloud identity.
24+
- Support public readable TOS zip URLs without requiring AK/SK.
25+
- Preserve existing SkillHub and Skill Space behavior.
26+
27+
## Non-Goals
28+
29+
- No parent-directory auto-discovery of multiple Skills.
30+
- No plaintext AK/SK in Harness requests.
31+
- No cross-account private TOS credential reference in this MVP.
32+
33+
## Requirements
34+
35+
| ID | Requirement |
36+
| --- | --- |
37+
| FR-1 | A TOS selected Skill with `tos_url="tos://bucket/path/to/skill/"` loads exactly one Skill directory and requires `SKILL.md` or `skill.md` at that URL root. |
38+
| FR-2 | Multiple TOS Skills are loaded by multiple `selected_skills` entries. |
39+
| FR-3 | A public TOS zip URL can load one Skill archive. |
40+
| FR-4 | Empty/bucket-root TOS URLs, parent directories, unsupported public URLs, non-TOS hosts, credential-bearing public URLs, and redirects to non-TOS hosts fail closed. |
41+
| FR-5 | TOS download failures and invalid Skill directories fail the whole SkillToolset build. |
42+
| FR-6 | Public TOS zip downloads, public zip extraction, and private TOS directory downloads enforce bounded file/object count and byte limits before Skill loading. |
43+
44+
## Design
45+
46+
`HarnessSelectedSkill.source` accepts `tos` with either:
47+
48+
```python
49+
HarnessSelectedSkill(source="tos", tos_url="tos://bucket/skills/reporting/", region="cn-beijing")
50+
HarnessSelectedSkill(source="tos", tos_public_url="https://bucket.tos-cn-beijing.volces.com/skills/reporting.zip")
51+
```
52+
53+
Multiple Skills are expressed as multiple entries:
54+
55+
```python
56+
selected_skills=[
57+
HarnessSelectedSkill(source="tos", tos_url="tos://bucket/skills/reporting/", region="cn-beijing"),
58+
HarnessSelectedSkill(source="tos", tos_url="tos://bucket/skills/search/", region="cn-beijing"),
59+
]
60+
```
61+
62+
Harness serializes these as internal refs and dispatches them in `build_skill_toolset`. TOS selected Skills use `tos_url` and `tos_public_url` as the only locator fields. The materializer parses `tos://` URLs, downloads one directory through `VeTOS`, validates path containment, requires root-level `SKILL.md` or `skill.md`, and loads with ADK. A URL pointing at a parent folder containing child Skills is rejected instead of selecting one child. Public URLs must not contain userinfo or TOS signature query credentials. They are streamed as zip archives from validated TOS hosts, every redirect hop must also target a TOS host before it is requested, and the existing safe zip extraction path enforces expanded file count and uncompressed byte limits for public TOS archives.
63+
64+
Rejected TOS refs are redacted when wrapped into Harness skill-load errors, so invalid userinfo or signature query values are not returned to callers or written by the Harness error path.
65+
66+
## Tasks
67+
68+
| ID | Task |
69+
| --- | --- |
70+
| T-1 | Add schema fields and validation for TOS selected Skills. |
71+
| T-2 | Add materializer helpers for TOS directory and public zip sources, including strict root-manifest validation and resource limits. |
72+
| T-3 | Wire Harness SkillToolset building to TOS refs. |
73+
| T-4 | Add focused contract and materializer tests. |
74+
75+
## Verification
76+
77+
| Requirement | Command | Result |
78+
| --- | --- | --- |
79+
| FR-1..FR-6 | `uv run --extra dev pytest tests/skills/test_adk_skill_materializer.py tests/test_ve_tos.py::test_download_can_propagate_tos_error tests/test_ve_tos.py::test_download_rejects_object_over_byte_limit tests/test_ve_tos.py::test_download_directory_rejects_too_many_objects tests/test_ve_tos.py::test_download_directory_rejects_total_bytes_from_listing -q` | pass, 30 passed on 2026-10-12 |
80+
| FR-4..FR-5 | `uv run --extra dev pytest tests/cloud/test_harness_app_contract.py::TestHarnessOverrides::test_tos_selected_skill_rejects_public_url_userinfo tests/cloud/test_harness_app_contract.py::TestHarnessOverrides::test_tos_selected_skill_rejects_public_url_signature_query tests/cloud/test_harness_skill_download.py::test_build_skill_toolset_redacts_tos_ref_on_error -q` | pass, 3 passed on 2026-10-13 |
81+
| FR-1..FR-6 | `uv run --extra dev pytest tests/cloud/test_harness_skill_download.py::test_build_skill_toolset_loads_tos_skill_uri tests/cloud/test_harness_skill_download.py::test_build_skill_toolset_loads_multiple_tos_entries -q` | pass, 2 passed on 2026-10-12 |
82+
| FR-1..FR-6 | `uv run --extra dev ruff check veadk/skills/materializer.py veadk/integrations/ve_tos/ve_tos.py tests/skills/test_adk_skill_materializer.py tests/test_ve_tos.py` | pass on 2026-10-12 |
83+
| FR-1..FR-6 | `uv run --extra dev pre-commit run --all-files` | pass on 2026-10-12 |
84+
| FR-1..FR-6 | `git diff --check` | pass on 2026-10-12 |
85+
| FR-1..FR-6 | `uv run --extra dev pytest tests/skills/test_adk_skill_materializer.py tests/test_ve_tos.py -q` | fail, existing environment limitation: four async tests in `tests/test_ve_tos.py` need an async pytest plugin; TOS-focused tests passed. |
86+
87+
## Risks
88+
89+
- Real TOS IAM behavior requires cloud smoke validation outside the offline unit tests.
90+
- Public directory URLs remain excluded because object storage does not provide a stable generic HTTP directory listing contract.

‎prd-spec/features/harness-tos-skills/2026-10-12-harness-tos-skills.zh.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Harness TOS Skills
2+
3+
[English](2026-10-12-harness-tos-skills.md)
4+
5+
## 元数据
6+
7+
| 字段 | 值 |
8+
| --- | --- |
9+
| Change ID | `harness-tos-skills` |
10+
| 创建日期 | 2026-10-12 |
11+
| 状态 | implemented |
12+
| 相关规格 | 不更新组件规格；本变更扩展现有 Harness selected-skill 请求契约，不改变组件职责边界。 |
13+
14+
## 背景和证据
15+
16+
Harness 当前已经支持加载 SkillHub Skill 和 Skill Space Skill。Skill Space 加载最终会通过现有 materializer 下载 TOS 上的 Skill archive，但调用方不能直接提供对象存储 Skill 目录。
17+
18+
目标行为对齐 AWS AgentCore Harness S3 Skills：一个对象存储 URI 指向一个包含 `SKILL.md` 的 Skill 目录；多个 Skill 通过多条 selected-skill entry 表达。
19+
20+
## 目标
21+
22+
- 为 `HarnessSelectedSkill` 增加 `source="tos"`。
23+
- 支持通过 Runtime 云身份读取当前账号 TOS 目录。
24+
- 支持公开读 TOS zip URL，不要求 AK/SK。
25+
- 保持现有 SkillHub 和 Skill Space 行为不变。
26+
27+
## 非目标
28+
29+
- 不做父目录自动发现多个 Skill。
30+
- 不在 Harness 请求中接收明文 AK/SK。
31+
- MVP 不支持跨账号私有 TOS 的 credential reference。
32+
33+
## 需求
34+
35+
| ID | 需求 |
36+
| --- | --- |
37+
| FR-1 | TOS selected Skill 使用 `tos_url="tos://bucket/path/to/skill/"` 时只加载一个 Skill directory，且该 URL 根目录必须直接包含 `SKILL.md` 或 `skill.md`。 |
38+
| FR-2 | 多个 TOS Skill 通过多条 `selected_skills` entry 加载。 |
39+
| FR-3 | 公开读 TOS zip URL 可以加载一个 Skill archive。 |
40+
| FR-4 | 空 URL、bucket 根路径 URL、父目录 URL、不支持的公开 URL、非 TOS host、带凭据的公开 URL，以及跳转到非 TOS host 的公开 URL 必须失败关闭。 |
41+
| FR-5 | TOS 下载失败或 Skill 目录非法时，整个 SkillToolset 构建失败。 |
42+
| FR-6 | 公开 TOS zip 下载、公开 zip 解压和私有 TOS 目录下载必须在 Skill 加载前执行文件/对象数和字节数上限。 |
43+
44+
## 设计
45+
46+
`HarnessSelectedSkill.source` 接受 `tos`，并支持以下两种形式：
47+
48+
```python
49+
HarnessSelectedSkill(source="tos", tos_url="tos://bucket/skills/reporting/", region="cn-beijing")
50+
HarnessSelectedSkill(source="tos", tos_public_url="https://bucket.tos-cn-beijing.volces.com/skills/reporting.zip")
51+
```
52+
53+
多个 Skill 通过多条 entry 表达：
54+
55+
```python
56+
selected_skills=[
57+
HarnessSelectedSkill(source="tos", tos_url="tos://bucket/skills/reporting/", region="cn-beijing"),
58+
HarnessSelectedSkill(source="tos", tos_url="tos://bucket/skills/search/", region="cn-beijing"),
59+
]
60+
```
61+
62+
Harness 将其序列化为内部 ref，并在 `build_skill_toolset` 中分发。TOS selected Skill 只使用 `tos_url` 和 `tos_public_url` 作为 locator 字段。materializer 解析 `tos://` URL，通过 `VeTOS` 下载单个目录，校验路径没有逃逸，要求根目录直接包含 `SKILL.md` 或 `skill.md`，再用 ADK 加载。指向包含多个子 Skill 的父目录 URL 会被拒绝，不会自动选择某个子目录。公开 URL 不允许包含 userinfo 或 TOS 签名 query 凭据。公开 URL 按 zip archive 流式下载，每一跳 redirect 在请求前都必须指向 TOS host，并且现有安全解压路径会对公开 TOS archive 执行展开后的文件数和未压缩字节数上限。
63+
64+
被拒绝的 TOS ref 在包装成 Harness skill-load 错误时会脱敏，避免无效 userinfo 或签名 query 值返回给调用方，或被 Harness 错误路径写入日志。
65+
66+
## 任务
67+
68+
| ID | 任务 |
69+
| --- | --- |
70+
| T-1 | 增加 TOS selected Skill schema 字段和校验。 |
71+
| T-2 | 增加 TOS directory 和 public zip materializer，包括严格根 manifest 校验和资源上限。 |
72+
| T-3 | 将 Harness SkillToolset 构建接入 TOS refs。 |
73+
| T-4 | 增加聚焦的契约测试和 materializer 测试。 |
74+
75+
## 验证
76+
77+
| 需求 | 命令 | 结果 |
78+
| --- | --- | --- |
79+
| FR-1..FR-6 | `uv run --extra dev pytest tests/skills/test_adk_skill_materializer.py tests/test_ve_tos.py::test_download_can_propagate_tos_error tests/test_ve_tos.py::test_download_rejects_object_over_byte_limit tests/test_ve_tos.py::test_download_directory_rejects_too_many_objects tests/test_ve_tos.py::test_download_directory_rejects_total_bytes_from_listing -q` | pass，2026-10-12 执行，30 passed |
80+
| FR-4..FR-5 | `uv run --extra dev pytest tests/cloud/test_harness_app_contract.py::TestHarnessOverrides::test_tos_selected_skill_rejects_public_url_userinfo tests/cloud/test_harness_app_contract.py::TestHarnessOverrides::test_tos_selected_skill_rejects_public_url_signature_query tests/cloud/test_harness_skill_download.py::test_build_skill_toolset_redacts_tos_ref_on_error -q` | pass，2026-10-13 执行，3 passed |
81+
| FR-1..FR-6 | `uv run --extra dev pytest tests/cloud/test_harness_skill_download.py::test_build_skill_toolset_loads_tos_skill_uri tests/cloud/test_harness_skill_download.py::test_build_skill_toolset_loads_multiple_tos_entries -q` | pass，2026-10-12 执行，2 passed |
82+
| FR-1..FR-6 | `uv run --extra dev ruff check veadk/skills/materializer.py veadk/integrations/ve_tos/ve_tos.py tests/skills/test_adk_skill_materializer.py tests/test_ve_tos.py` | pass，2026-10-12 执行 |
83+
| FR-1..FR-6 | `uv run --extra dev pre-commit run --all-files` | pass，2026-10-12 执行 |
84+
| FR-1..FR-6 | `git diff --check` | pass，2026-10-12 执行 |
85+
| FR-1..FR-6 | `uv run --extra dev pytest tests/skills/test_adk_skill_materializer.py tests/test_ve_tos.py -q` | fail，现有环境限制：`tests/test_ve_tos.py` 中 4 个 async 测试需要 pytest async 插件；TOS 聚焦测试已通过。 |
86+
87+
## 风险
88+
89+
- 真实 TOS IAM 行为需要额外的云端 smoke 验证，离线单测无法证明。
90+
- 公开目录 URL 仍不纳入范围，因为对象存储没有稳定通用的 HTTP 目录清单契约。

‎tests/cloud/test_harness_app_contract.py‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,11 @@ def test_structured_tools_skills_and_mcp_are_accepted(self):
191191
"space_id": "ss-1",
192192
"skill_id": "skill-1",
193193
},
194+
{
195+
"source": "tos",
196+
"tos_url": "tos://customer-bucket/skills/reporting/",
197+
"region": "cn-beijing",
198+
},
194199
],
195200
"mcp": [{"name": "db", "url": "http://db.test/mcp"}],
196201
}
@@ -206,8 +211,97 @@ def test_structured_tools_skills_and_mcp_are_accepted(self):
206211
skill_space_id="ss-1",
207212
skill_id="skill-1",
208213
)
214+
assert h.selected_skills[2] == HarnessSelectedSkill(
215+
source="tos",
216+
tos_url="tos://customer-bucket/skills/reporting/",
217+
region="cn-beijing",
218+
)
209219
assert h.mcp == [HarnessMcpServer(name="db", server_url="http://db.test/mcp")]
210220

221+
def test_tos_selected_skill_rejects_legacy_locator_names(self):
222+
with pytest.raises(ValidationError, match="requires tos_url or tos_public_url"):
223+
HarnessOverrides.model_validate(
224+
{
225+
"selected_skills": [
226+
{
227+
"source": "tos",
228+
"uri": "tos://customer-bucket/skills/reporting/",
229+
}
230+
]
231+
}
232+
)
233+
234+
with pytest.raises(ValidationError, match="requires tos_url or tos_public_url"):
235+
HarnessOverrides.model_validate(
236+
{
237+
"selected_skills": [
238+
{
239+
"source": "tos",
240+
"public_url": (
241+
"https://bucket.tos-cn-beijing.volces.com/"
242+
"skills/reporting.zip"
243+
),
244+
}
245+
]
246+
}
247+
)
248+
249+
def test_tos_selected_skill_requires_tos_url_or_tos_public_url(self):
250+
with pytest.raises(ValidationError, match="requires tos_url or tos_public_url"):
251+
HarnessOverrides.model_validate({"selected_skills": [{"source": "tos"}]})
252+
253+
def test_tos_selected_skill_rejects_bucket_root_uri(self):
254+
with pytest.raises(ValidationError, match="must point to a Skill directory"):
255+
HarnessOverrides.model_validate(
256+
{"selected_skills": [{"source": "tos", "tos_url": "tos://bucket"}]}
257+
)
258+
259+
def test_tos_selected_skill_rejects_unsafe_uri(self):
260+
with pytest.raises(ValidationError, match="safe Skill directory"):
261+
HarnessOverrides.model_validate(
262+
{
263+
"selected_skills": [
264+
{
265+
"source": "tos",
266+
"tos_url": "tos://bucket/skills/../secret/",
267+
}
268+
]
269+
}
270+
)
271+
272+
def test_tos_selected_skill_rejects_public_url_userinfo(self):
273+
credential = "user" + ":" + "secret"
274+
with pytest.raises(ValidationError, match="must not include credentials"):
275+
HarnessOverrides.model_validate(
276+
{
277+
"selected_skills": [
278+
{
279+
"source": "tos",
280+
"tos_public_url": (
281+
f"https://{credential}@bucket.tos-cn-beijing."
282+
"volces.com/skills/reporting.zip"
283+
),
284+
}
285+
]
286+
}
287+
)
288+
289+
def test_tos_selected_skill_rejects_public_url_signature_query(self):
290+
with pytest.raises(ValidationError, match="must not include credentials"):
291+
HarnessOverrides.model_validate(
292+
{
293+
"selected_skills": [
294+
{
295+
"source": "tos",
296+
"tos_public_url": (
297+
"https://bucket.tos-cn-beijing.volces.com/"
298+
"skills/reporting.zip?X-Tos-Signature=TOPSECRET"
299+
),
300+
}
301+
]
302+
}
303+
)
304+
211305
def test_selected_skill_accepts_skill_space_policy(self):
212306
h = HarnessOverrides.model_validate(
213307
{

0 commit comments

Comments
 (0)