Move marketplace definitions to openhands.sdk.marketplace module by csmith49 · Pull Request #2786 · OpenHands/software-agent-sdk

csmith49 · 2026-04-09T20:26:22Z

A human has tested these changes.

Why

The marketplace definitions (Marketplace, MarketplaceEntry, MarketplaceOwner, etc.) were embedded in the plugin module but represent a distinct domain. Moving them to their own module improves code organization and makes the SDK structure clearer.

The official Anthropic spec has marketplaces for plugins only. But we use them to point to skills, so if nothing else we should move them out of the openhands.sdk.plugin module.

Summary

Create new openhands.sdk.marketplace module to house marketplace-related types
Update openhands.sdk.plugin with deprecation-tracking re-exports for backward compatibility
Update internal references to use the new canonical location
Add tests for deprecation warning behavior

Issue Number

N/A (refactoring for better code organization)

How to Test

The changes can be verified by running:

# Run the deprecation tests
uv run pytest tests/sdk/marketplace/test_deprecation.py -v

# Run all marketplace and plugin tests
uv run pytest tests/sdk/plugin/ tests/sdk/marketplace/ tests/sdk/skills/ -v

# Test import behavior manually
uv run python -W always -c "
# New import (no warning)
from openhands.sdk.marketplace import Marketplace
print('New import:', Marketplace)

# Old import (deprecation warning)
from openhands.sdk.plugin import Marketplace as OldMarketplace
print('Old import:', OldMarketplace)
print('Same class:', Marketplace is OldMarketplace)
"

Test Results:

tests/sdk/marketplace/test_deprecation.py: 11 passed
tests/sdk/plugin/test_marketplace.py: 39 passed  
tests/sdk/skills/test_installed_skills.py: All tests pass
Total: 284 tests passed

Import Behavior:

New import: <class 'openhands.sdk.marketplace.types.Marketplace'>
DeprecatedWarning: Importing Marketplace from openhands.sdk.plugin is deprecated as of 1.16.0 
and will be removed in 1.19.0. Import from openhands.sdk.marketplace instead.
Old import: <class 'openhands.sdk.marketplace.types.Marketplace'>
Same class: True

Video/Screenshots

N/A (internal refactoring, no UI changes)

Type

Notes

Deprecation Timeline:

deprecated_in: 1.16.0
removed_in: 1.19.0

Migration Guide:

# Before (deprecated)
from openhands.sdk.plugin import Marketplace

# After (recommended)
from openhands.sdk.marketplace import Marketplace

All marketplace classes are affected:

Marketplace
MarketplaceEntry
MarketplaceOwner
MarketplacePluginEntry
MarketplacePluginSource
MarketplaceMetadata
MARKETPLACE_MANIFEST_DIRS
MARKETPLACE_MANIFEST_FILE

@csmith49 can click here to continue refining the PR

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:f4dffd3-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

Each variant tag (e.g., f4dffd3-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., f4dffd3-python-amd64) are also available if needed

Create a new openhands.sdk.marketplace module to house marketplace-related types (Marketplace, MarketplaceEntry, MarketplaceOwner, etc.) that were previously embedded in openhands.sdk.plugin.types. Changes: - Add openhands-sdk/openhands/sdk/marketplace/ module with types.py - Update plugin/types.py with deprecation-tracking __getattr__ re-exports - Update plugin/__init__.py with lazy imports and deprecation warnings - Update internal references in skills modules to use new location - Add tests/sdk/marketplace/test_deprecation.py for deprecation tracking The old import paths (openhands.sdk.plugin.Marketplace, etc.) still work but emit DeprecatedWarning. Users should migrate to importing from openhands.sdk.marketplace instead. Deprecation timeline: - deprecated_in: 1.16.0 - removed_in: 1.19.0 Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2026-04-09T20:26:49Z

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

github-actions · 2026-04-09T20:27:03Z

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

Restructure tests to match the new module structure: - Move tests/sdk/plugin/test_marketplace.py -> tests/sdk/marketplace/test_marketplace.py - Update imports to use openhands.sdk.marketplace (canonical location) Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2026-04-09T20:29:11Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/marketplace
types.py	112	2	98%	296, 303
openhands-sdk/openhands/sdk/plugin
__init__.py	16	1	93%	88
types.py	115	17	85%	53, 56, 59, 89–97, 100–101, 104, 157, 293
openhands-sdk/openhands/sdk/skills
installed.py	261	41	84%	47, 54, 241–242, 249, 269–270, 276–277, 281, 284, 287, 324–328, 356–358, 362–364, 367, 371, 411, 439, 463, 478–479, 549–552, 554–555, 559–560, 565, 582–583
skill.py	431	33	92%	95–96, 251–252, 438–444, 447, 564–567, 811–812, 871–872, 942–943, 1011, 1039, 1062, 1069–1070, 1114–1115, 1121–1122, 1128–1129
TOTAL	22314	6468	71%

all-hands-bot

🟢 Good taste - Clean refactoring

Verdict: ✅ Merge it

Key insight: The different __getattr__ patterns (eager import in __init__.py, lazy in types.py) are intentional to avoid circular dependencies since marketplace.types imports from plugin.types. Good design.

Proper deprecation timeline (1.16→1.19), backward compatibility maintained, well-tested. No agent behavior changes, no eval impact.

all-hands-bot

QA Report: Marketplace Module Refactor

✅ PASS

Summary: The refactor successfully moves marketplace definitions to a new module with full backward compatibility and proper deprecation warnings.

Environment Setup

✅ Build successful

$ make build
Dependencies installed successfully.
Pre-commit hooks installed successfully.
Build complete! Development environment is ready.

CI & Test Status

✅ All critical CI checks passed:

✅ sdk-tests (2m14s)
✅ cross-tests (1m20s)
✅ Python API breakage checks (23s)
✅ REST API checks (32s)
✅ pre-commit (1m14s)
✅ agent-server-tests, tools-tests

✅ Local test results:

$ uv run pytest tests/sdk/marketplace/ -v
50 passed in 0.13s
  - 11 deprecation tests (new)
  - 39 marketplace functionality tests (moved from plugin/)

Functional Verification

1. Import Behavior ✅

Tested both new and old import paths to verify backward compatibility:

New import path (no warnings):

from openhands.sdk.marketplace import Marketplace, MarketplaceOwner, ...
✓ Imports successful with 0 warnings

Old import paths (deprecation warnings):

from openhands.sdk.plugin import Marketplace
✓ Imports successful with proper DeprecatedWarning:
  "Importing Marketplace from openhands.sdk.plugin is deprecated 
   as of 1.16.0 and will be removed in 1.19.0. Import from 
   openhands.sdk.marketplace instead."

Class identity verification:

Marketplace is OldMarketplace: True
MarketplaceOwner is OldMarketplaceOwner: True
✓ Both import paths return identical classes

2. Marketplace Functionality ✅

Verified all marketplace classes instantiate and function correctly:

# All classes work with new import location
owner = MarketplaceOwner(name="Test Team", email="test@example.com")
entry = MarketplaceEntry(name="test-skill", source="./skills/test")
plugin_entry = MarketplacePluginEntry(name="test-plugin", ...)
source = MarketplacePluginSource(source="github", repo="owner/repo")
metadata = MarketplaceMetadata(version="1.0.0")
✓ All classes instantiate correctly

3. Marketplace.load() Method ✅

Tested loading a real marketplace:

$ uv run python -c "from openhands.sdk.marketplace import Marketplace; ..."
Marketplace loaded successfully!
  Name: mixed-skills-marketplace
  Owner: OpenHands Team
  Skills: 2 skill(s)
  Plugins: 0 plugin(s)
✓ Marketplace loading works correctly

4. Example Integration ✅

Verified the updated example runs without errors:

$ cd examples/01_standalone_sdk/43_mixed_marketplace_skills
$ uv run python main.py --list
Installed Skills
No skills installed.
EXAMPLE_COST: 0
✓ Example runs successfully with new import path

5. Skills Module Integration ✅

Verified internal SDK code that uses marketplace works:

$ uv run pytest tests/sdk/skills/test_installed_skills.py -k marketplace -v
5 passed
  - test_install_local_skills
  - test_install_skills_force_overwrite
  - test_install_handles_missing_skill_source
  - test_install_skills_from_plugin_directories
  - test_install_both_standalone_and_plugin_skills
✓ Skills integration with marketplace works correctly

Verification Summary

✅ All changed behavior verified:

New module openhands.sdk.marketplace contains all marketplace types
Old import paths continue to work with deprecation warnings
Deprecation warnings properly reference version 1.16.0 (deprecated) and 1.19.0 (removal)
All marketplace functionality preserved
Example code updated and functional
Internal SDK code updated and functional
No breaking changes to public API
All tests pass (50 marketplace tests + 212 plugin tests + 5 skills integration tests)

Migration Path Verification ✅

The PR provides a clear migration path:

Before (deprecated but still works):

from openhands.sdk.plugin import Marketplace

After (recommended):

from openhands.sdk.marketplace import Marketplace

Users have 3 minor versions (1.16.0 → 1.19.0) to migrate.

Verdict

✅ PASS - This is a clean refactor that:

Improves code organization by separating marketplace from plugin concerns
Maintains full backward compatibility with deprecation warnings
Provides a clear migration path with 3-version runway
Preserves all functionality
Updates all internal references
Includes comprehensive test coverage

No issues found. Ready for merge.

enyst

I think it's nice that we use them for skills, I don't know what the plugin format will become, it feels a bit... fluid. But skills are so important and widespread that it's nice to use/reuse a bucket of them IMHO.

Merge branch 'main' into openhands/marketplace-module

11e7b4b

csmith49 marked this pull request as ready for review April 9, 2026 20:40

all-hands-bot approved these changes Apr 9, 2026

View reviewed changes

all-hands-bot reviewed Apr 9, 2026

View reviewed changes

enyst approved these changes Apr 9, 2026

View reviewed changes

Merge branch 'main' into openhands/marketplace-module

f331253

csmith49 merged commit 53b8038 into main Apr 9, 2026
25 checks passed

csmith49 deleted the openhands/marketplace-module branch April 9, 2026 21:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move marketplace definitions to openhands.sdk.marketplace module#2786

Move marketplace definitions to openhands.sdk.marketplace module#2786
csmith49 merged 4 commits intomainfrom
openhands/marketplace-module

csmith49 commented Apr 9, 2026 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

all-hands-bot left a comment

Uh oh!

all-hands-bot left a comment

Uh oh!

enyst left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

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

Uh oh!

Why

Summary

Issue Number

How to Test

Video/Screenshots

Type

Notes

Uh oh!

github-actions bot commented Apr 9, 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 9, 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 9, 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!

all-hands-bot left a comment

Choose a reason for hiding this comment

QA Report: Marketplace Module Refactor

✅ PASS

Environment Setup

CI & Test Status

Functional Verification

1. Import Behavior ✅

2. Marketplace Functionality ✅

3. Marketplace.load() Method ✅

4. Example Integration ✅

5. Skills Module Integration ✅

Verification Summary

Migration Path Verification ✅

Verdict

Uh oh!

enyst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

csmith49 commented Apr 9, 2026 •

edited by github-actions bot

Loading

github-actions bot commented Apr 9, 2026 •

edited

Loading

github-actions bot commented Apr 9, 2026 •

edited

Loading

github-actions bot commented Apr 9, 2026 •

edited

Loading