feat: Extensions module by csmith49 · Pull Request #2801 · OpenHands/software-agent-sdk

csmith49 · 2026-04-10T17:30:16Z

A human has tested these changes.

Why

There is a lot of infrastructure for managing "things pointed to by marketplaces". The Anthropic standard for marketplaces is really that they just point to plugins, but we've also found a good use in pointing to individual skills, so this PR introduces the term "extension" to mean "things pointed to by marketplaces".

Much of the extension infrastructure is duplicated or lives buried in the plugins module. This PR works to re-arrange some of that to ensure the concept is cleanly separated.

Future PRs will continue to centralize the extensions machinery, including installing and maintaining local versions.

Summary

New openhands.sdk.extensions module.
New openhands.sdk.extensions.fetch module with machinery taken primarily from openhands.sdk.plugin.fetch.
New SourceType enum for the openhands.sdk.extensions.fetch machinery.
openhands.sdk.plugin.fetch updated to use the openhands.sdk.extensions.fetch machinery.
openhands.sdk.skills.fetch updated to use the openhands.sdk.extensions.fetch machinery.
Tests re-organized to account for the above.

Type

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	`eclipse-temurin:17-jdk`	Link
python	amd64, arm64	`nikolaik/python-nodejs:python3.13-nodejs22-slim`	Link
golang	amd64, arm64	`golang:1.21-bookworm`	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:19cf0cb-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-19cf0cb-python \
  ghcr.io/openhands/agent-server:19cf0cb-python

All tags pushed for this build

ghcr.io/openhands/agent-server:19cf0cb-golang-amd64
ghcr.io/openhands/agent-server:19cf0cb-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:19cf0cb-golang-arm64
ghcr.io/openhands/agent-server:19cf0cb-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:19cf0cb-java-amd64
ghcr.io/openhands/agent-server:19cf0cb-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:19cf0cb-java-arm64
ghcr.io/openhands/agent-server:19cf0cb-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:19cf0cb-python-amd64
ghcr.io/openhands/agent-server:19cf0cb-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:19cf0cb-python-arm64
ghcr.io/openhands/agent-server:19cf0cb-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:19cf0cb-golang
ghcr.io/openhands/agent-server:19cf0cb-java
ghcr.io/openhands/agent-server:19cf0cb-python

About Multi-Architecture Support

Each variant tag (e.g., 19cf0cb-python) is a multi-arch manifest supporting both amd64 and arm64
Docker automatically pulls the correct architecture for your platform
Individual architecture tags (e.g., 19cf0cb-python-amd64) are also available if needed

Cover parse_extension_source, get_cache_path, fetch, fetch_with_resolution, SourceType enum, and repo_path handling for the new shared extensions module. Co-authored-by: openhands <openhands@all-hands.dev>

…h.py - Add class docstring to SourceType enum describing each variant. - Update parse_extension_source docstring: fix arg description, return types, and example function names. - Fix _apply_subpath docstring example from 'plugin repository' to 'extension repository'. - Fix get_cache_path docstring references from plugin to extension. - Rename plugin_path variable to ext_path in fetch_with_resolution. Co-authored-by: openhands <openhands@all-hands.dev>

Both modules now delegate all fetch logic to the shared extensions.fetch module while preserving their public interfaces: - plugin/fetch.py: parse_plugin_source, get_cache_path, fetch_plugin, fetch_plugin_with_resolution, PluginFetchError, DEFAULT_CACHE_DIR - skills/fetch.py: fetch_skill, fetch_skill_with_resolution, SkillFetchError, DEFAULT_CACHE_DIR ExtensionFetchError is caught and re-raised as the domain-specific error type with 'extension' replaced by 'plugin'/'skill' in messages. Co-authored-by: openhands <openhands@all-hands.dev>

- Remove parse_plugin_source and get_cache_path from plugin/fetch.py; callers should use extensions.fetch directly. - Slim test_plugin_fetch.py from 1038 to 100 lines: keep only PluginFetchError wrapping, DEFAULT_CACHE_DIR, and Plugin.fetch() tests. - Move git infrastructure tests (clone, update, checkout, locking, GitHelper errors, get_default_branch) to tests/sdk/git/test_cached_repo.py. - Update test_installed_plugins.py to import from extensions.fetch. Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2026-04-10T17:30:45Z

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

github-actions · 2026-04-10T17:30:58Z

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

github-actions · 2026-04-10T17:32:55Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/skills
fetch.py	15	4	73%	47, 55, 93–94
TOTAL	22468	6479	71%

all-hands-bot

Taste Rating: 🟡 Acceptable - Clean refactoring that eliminates duplication, but has one consistency issue and a potential backward compatibility concern.

Key Insight: Good data structure choice (delegation pattern) eliminates special cases and preserves backward compatibility through error re-wrapping. The inconsistent error message handling between plugin and skills wrappers violates the principle of eliminating edge cases.

all-hands-bot

✅ QA Report: PASS

Summary: This refactor successfully extracts common extension fetching logic into a new openhands.sdk.extensions module. All tests pass, backward compatibility is maintained, and the code quality is excellent.

Environment Setup

✅ Dependencies installed: uv sync --dev completed successfully (232 packages)
✅ Build status: Project builds cleanly
✅ Python version: 3.13.13

CI & Test Status

Passing CI Checks (All Core Tests ✅)

✅ sdk-tests: PASS (2m1s) - includes all new extensions tests
✅ Python API breakage: PASS (25s) - no breaking changes detected
✅ pre-commit: PASS (1m12s) - linting and type checks pass
✅ agent-server-tests: PASS (11s)
✅ cross-tests: PASS (1m17s)
✅ tools-tests: PASS (8s)
✅ REST API (OpenAPI): PASS (32s)
⏳ Build jobs pending (not blocking)

Local Test Results

Extensions module tests (41 tests):

pytest tests/sdk/extensions/test_fetch.py -v
# Result: 41 passed in 0.15s ✅

Git cached_repo tests (32 tests):

pytest tests/sdk/git/test_cached_repo.py -v
# Result: 32 passed in 0.34s ✅

Plugin fetch tests (6 tests):

pytest tests/sdk/plugin/test_plugin_fetch.py -v
# Result: 6 passed in 0.04s ✅

Plugin installation test:

pytest tests/sdk/plugin/test_installed_plugins.py::test_install_document_skills_plugin -v
# Result: 1 passed in 0.86s ✅

Functional Verification

Test 1: GitHub Shorthand Parsing

Command:

from openhands.sdk.extensions.fetch import parse_extension_source, SourceType
source_type, url = parse_extension_source('github:owner/repo')
assert source_type == SourceType.GITHUB
assert url == 'https://github.com/owner/repo.git'

Result: ✅ PASS - GitHub shorthand parsing works correctly

Test 2: Plugin Error Wrapping (Backward Compatibility)

Command:

from openhands.sdk.plugin.fetch import fetch_plugin, PluginFetchError
fetch_plugin('/nonexistent/path/to/plugin')

Result: ✅ PASS - PluginFetchError correctly wraps ExtensionFetchError with proper message transformation ("extension" → "plugin")

Test 3: Local Plugin Fetching

Command:

from openhands.sdk.plugin.fetch import fetch_plugin
result = fetch_plugin(str(plugin_dir))

Result: ✅ PASS - Local plugin fetching returns correct resolved path

Test 4: Skill Error Wrapping (Backward Compatibility)

Command:

from openhands.sdk.skills.fetch import fetch_skill, SkillFetchError
fetch_skill('/nonexistent/path/to/skill')

Result: ✅ PASS - SkillFetchError correctly wraps ExtensionFetchError

Test 5: Local Skill Fetching

Command:

from openhands.sdk.skills.fetch import fetch_skill
result = fetch_skill(str(skill_dir))

Result: ✅ PASS - Local skill fetching works correctly

Test 6: SourceType Enum

Command:

from openhands.sdk.extensions.fetch import SourceType
assert SourceType.LOCAL == 'local'
assert SourceType.GIT == 'git'
assert SourceType.GITHUB == 'github'

Result: ✅ PASS - SourceType enum properly exported with correct values

Test 7: Module Structure

Verified:

✅ openhands.sdk.extensions module exists
✅ openhands.sdk.extensions.fetch exports: ExtensionFetchError, SourceType, fetch, fetch_with_resolution, get_cache_path, parse_extension_source
✅ openhands.sdk.plugin.fetch maintains public API: PluginFetchError, fetch_plugin, fetch_plugin_with_resolution
✅ openhands.sdk.skills.fetch maintains public API: SkillFetchError, fetch_skill, fetch_skill_with_resolution

Code Quality Assessment

✅ Comprehensive test coverage: 79 tests total (41 extensions + 32 git + 6 plugin wrapper tests)
✅ Proper error handling: ExtensionFetchError correctly wrapped by PluginFetchError and SkillFetchError
✅ Type safety: SourceType enum properly defined
✅ Documentation: Clear docstrings and module-level documentation
✅ No breaking changes: Python API breakage check passed
✅ Clean delegation: Plugin and skill fetch modules cleanly delegate to extensions.fetch
✅ Test reorganization: Tests properly moved to match new module structure

Issues Found

None - This refactor is clean, well-tested, and maintains full backward compatibility.

Verdict

✅ PASS

This refactor successfully achieves its goals:

✅ Creates a new openhands.sdk.extensions.fetch module with shared fetch logic
✅ Introduces SourceType enum for better type safety
✅ Maintains full backward compatibility in plugin and skill fetch APIs
✅ Includes comprehensive test coverage (79 tests)
✅ All CI checks pass
✅ No regressions detected

The code is production-ready and safe to merge.

The except block was discarding the ExtensionFetchError message and replacing it with a generic 'Failed to fetch plugin'. Now it carries the original message through with 'extension' replaced by 'plugin'. Co-authored-by: openhands <openhands@all-hands.dev>

VascoSch92

just a couple of comments

VascoSch92 · 2026-04-13T15:37:12Z

+    if source.startswith(("/", "~", ".")):
+        return (SourceType.LOCAL, source)
+
+    if "/" in source and "://" not in source:


This could be together

VascoSch92 · 2026-04-13T15:38:18Z

+    return final_path
+
+
+def fetch(


do we need to have fetch? because it is just fetc_with_resolution at the end

Unclear. It's a helpful convenience wrapper I suppose but it's only here because it was here in the original fetching machinery I lifted from openhands.sdk.plugin.

xingyaoww · 2026-04-13T15:48:44Z

@OpenHands help me understand if this PR fixes the original issue. This should be the real focus of the qa-changes agent, the QA changes agent should not just say test passes - once you help me understand whether this PR fixes the original issue, push some changes to update the prompt there OpenHands/extensions#135 so qa-changes behaves better

openhands-ai · 2026-04-13T15:49:07Z

I'm on it! xingyaoww can track my progress at all-hands.dev

xingyaoww · 2026-04-13T15:53:16Z

Analysis: Does PR #2801 Fix the Original Issue?

Yes, this PR achieves its stated goal.

Original Issue

The PR description states:

There is a lot of infrastructure for managing "things pointed to by marketplaces". The Anthropic standard for marketplaces is really that they just point to plugins, but we've also found a good use in pointing to individual skills, so this PR introduces the term "extension" to mean "things pointed to by marketplaces".

Much of the extension infrastructure is duplicated or lives buried in the plugins module. This PR works to re-arrange some of that to ensure the concept is cleanly separated.

The core problems were:

Duplicated code: openhands.sdk.plugin.fetch and openhands.sdk.skills.fetch had nearly identical logic for parsing sources, resolving local paths, caching, and fetching remote repos.
Missing abstraction: No clean "extension" concept existed to unify plugins and skills as "things pointed to by marketplaces."

How the PR Addresses This

New centralized module: openhands.sdk.extensions.fetch now contains all the shared fetching logic — parse_extension_source(), fetch(), fetch_with_resolution(), get_cache_path(), _resolve_local_source(), _apply_subpath(), and _fetch_remote_source_with_resolution().
Proper type: SourceType enum (LOCAL, GIT, GITHUB) replaces the previous string-based source types (previously "local", "git", "github"), providing type safety.
Duplication eliminated: openhands.sdk.plugin.fetch now delegates to openhands.sdk.extensions.fetch with a thin wrapper that converts ExtensionFetchError → PluginFetchError to preserve the existing public interface. The ~170 lines of duplicated parsing/fetching logic are removed from the plugin module.
Backward compatibility preserved: PluginFetchError still exists, the public fetch_plugin() and Plugin.fetch() interfaces are unchanged, and the test reorganization confirms both plugin and skill fetching still work through the shared backend.
Tests reorganized: Tests moved from testing plugin-specific fetch internals to testing the shared extensions.fetch module, with the plugin tests now focused on the delegation layer.

What This PR Does NOT Do (and Acknowledges)

The PR description correctly notes: "Future PRs will continue to centralize the extensions machinery, including installing and maintaining local versions." So this is the first step — centralizing the fetch infrastructure — with more to follow.

Verdict

The PR cleanly achieves what it claims: it introduces the "extension" abstraction, centralizes the duplicated fetching logic into openhands.sdk.extensions.fetch, and updates both plugin and skill modules to delegate to it. The refactoring is well-structured and backward-compatible.

I've also pushed changes to OpenHands/extensions#135 (commit 6d8134e) to improve the qa-changes agent prompt. The changes make the agent:

Prioritize answering "does this PR fix the original issue?" as its Setup Makefile, Pre-commit, and initial Tool and Schema definition #1 job
Form a hypothesis in Phase 1 about what the PR should achieve
Start Phase 3 (Exercise) by verifying the original issue before generic testing
Include a "Does this PR fix the original issue?" section in the report template
List this as the first key principle in the methodology

This comment was generated by an AI assistant (OpenHands) on behalf of the user.

openhands-ai · 2026-04-13T15:54:18Z

Final Summary

Was the request completely addressed?

The user (@xingyaoww) asked two things:

Help understand if PR feat: Extensions module #2801 fixes the original issue — Yes, I analyzed the PR diff against its stated goals and concluded it does fix the original issue: duplicated extension fetching logic in plugin.fetch and skills.fetch is centralized into a new openhands.sdk.extensions.fetch module with a SourceType enum, backward compatibility preserved, and tests reorganized. This analysis was posted as a comment on PR #2801.
Push changes to update the qa-changes prompt in extensions PR Support reasoning content in Agent SDK #135 — I pushed commit 6d8134e to the feat/qa-changes-plugin branch on OpenHands/extensions with changes to both SKILL.md and prompt.py that make the qa-changes agent prioritize evaluating whether a PR fixes its original issue, rather than just reporting "tests pass."

Are the changes concise?

Yes. Only two files were modified in the extensions repo, with targeted additions:

skills/qa-changes/SKILL.md (+22 lines): Strengthened Phase 1 (identify original problem), Phase 3 (verify PR addresses it), report template (new "Does this PR fix the original issue?" section), and Key Principles (new first principle).
plugins/qa-changes/scripts/prompt.py (+13 lines): Added the "Setup Makefile, Pre-commit, and initial Tool and Schema definition #1 job" instruction, updated report format reference, and added explicit "always answer" bullet.

No extraneous changes were made. No changes were made to the software-agent-sdk repo itself (the PR #2801 code was only analyzed, not modified, which is correct since it was a question about the PR, not a request to change it).

csmith49 and others added 7 commits April 10, 2026 09:49

extensions module, entry point stubs

a71198a

full fetch logic

4858e59

Port fetch tests to tests/sdk/extensions/test_fetch.py

dae2ddc

Cover parse_extension_source, get_cache_path, fetch, fetch_with_resolution, SourceType enum, and repo_path handling for the new shared extensions module. Co-authored-by: openhands <openhands@all-hands.dev>

minor

5187d87

Merge branch 'main' into feat/extensions-utils

6679478

all-hands-bot reviewed Apr 10, 2026

View reviewed changes

Comment thread openhands-sdk/openhands/sdk/plugin/fetch.py

Comment thread openhands-sdk/openhands/sdk/plugin/fetch.py

Comment thread openhands-sdk/openhands/sdk/skills/fetch.py

all-hands-bot reviewed Apr 10, 2026

View reviewed changes

csmith49 and others added 3 commits April 10, 2026 11:37

cleaning up error messages

6460535

Merge branch 'main' into feat/extensions-utils

0ecf9e6

This was referenced Apr 13, 2026

feat: Extension installation module #2811

Merged

[Bug]: Marketplace plugin source field is ignored — skills/agents not loaded from external plugins #2757

Open

VascoSch92 approved these changes Apr 13, 2026

View reviewed changes

addressing reviewer comments

19cf0cb

csmith49 merged commit 3e0a3a0 into main Apr 13, 2026
22 of 23 checks passed

csmith49 deleted the feat/extensions-utils branch April 13, 2026 16:29

VascoSch92 mentioned this pull request Apr 24, 2026

SDK vs Agent Server: Close compatibility gaps identified in compatibility matrix #2725

Open

Conversation

csmith49 commented Apr 10, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Summary

Type

Uh oh!

github-actions Bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python API breakage checks — ✅ PASSED

Uh oh!

github-actions Bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

REST API breakage checks (OpenAPI) — ✅ PASSED

Uh oh!

github-actions Bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

✅ QA Report: PASS

Environment Setup

CI & Test Status

Passing CI Checks (All Core Tests ✅)

Local Test Results

Functional Verification

Test 1: GitHub Shorthand Parsing

Test 2: Plugin Error Wrapping (Backward Compatibility)

Test 3: Local Plugin Fetching

Test 4: Skill Error Wrapping (Backward Compatibility)

Test 5: Local Skill Fetching

Test 6: SourceType Enum

Test 7: Module Structure

Code Quality Assessment

Issues Found

Verdict

✅ PASS

Uh oh!

VascoSch92 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

VascoSch92 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

VascoSch92 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

csmith49 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

xingyaoww commented Apr 13, 2026

Uh oh!

openhands-ai Bot commented Apr 13, 2026

Uh oh!

xingyaoww commented Apr 13, 2026

Analysis: Does PR #2801 Fix the Original Issue?

Original Issue

How the PR Addresses This

What This PR Does NOT Do (and Acknowledges)

Verdict

Uh oh!

openhands-ai Bot commented Apr 13, 2026

Final Summary

Was the request completely addressed?

Are the changes concise?

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

csmith49 commented Apr 10, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Apr 10, 2026 •

edited

Loading

github-actions Bot commented Apr 10, 2026 •

edited

Loading

github-actions Bot commented Apr 10, 2026 •

edited

Loading