feat(plugin): Support multiple marketplace registrations with auto-load semantics

[jpshackelford]

Summary

This PR introduces support for registering multiple marketplaces with explicit auto-load semantics, replacing the single marketplace_path string.

Closes #2494

Changes

New Models

MarketplaceRegistration - Registration for a plugin marketplace:

class MarketplaceRegistration(BaseModel):
    name: str                              # Identifier for this registration
    source: str                            # github:owner/repo, git URL, or local path
    ref: str | None = None                 # Optional branch/tag/commit
    repo_path: str | None = None           # Subdirectory within repo (for monorepos)
    auto_load: Literal["all"] | None = None

New Classes

MarketplaceRegistry - Manages registered marketplaces with:

• Lazy fetching: Marketplaces are only fetched when first needed
• Caching: Fetched marketplaces are cached for the session
• Plugin resolution: Resolve plugin references like plugin-name@marketplace

Updated AgentContext

AgentContext(
    registered_marketplaces=[
        MarketplaceRegistration(
            name="public", 
            source="github:OpenHands/skills", 
            auto_load="all"
        ),
        MarketplaceRegistration(
            name="team", 
            source="github:acme/monorepo",
            repo_path="marketplaces/internal",
            auto_load="all"
        ),
        MarketplaceRegistration(
            name="experimental", 
            source="github:acme/experimental"
        ),  # registered, not auto-loaded
    ]
)

Deprecations

Deprecated	Replacement
AgentContext.marketplace_path	AgentContext.registered_marketplaces

Backward compatibility is maintained - if marketplace_path is set and registered_marketplaces is empty, a deprecation warning is emitted and the old behavior is preserved.

Plugin Resolution

Reference formats (same as Claude Code plugin syntax):

• plugin-name@marketplace-name — Explicit marketplace qualifier
• plugin-name — Search registered marketplaces (error if ambiguous)

Testing

uv run pytest tests/sdk/plugin/test_marketplace_registry.py -v

All 21 tests pass.

Documentation

• Docs PR: docs: Add multiple marketplace registrations section to plugins guide docs#406

Related

• Builds on feat: add configurable marketplace_path setting for public skills loading #2253 (marketplace_path support, released in v1.13.0)
• Enables feat: add marketplace_path setting to GUI (local and SaaS) OpenHands#13117 (alternative to marketplace_path setting)
• Enables [PRD] [OpenHands Cloud] Default Organizational Resources (Skills, Plugins) OpenHands#12916 (org-level default plugins)
• Enables [M2] Marketplace Management OpenHands-CLI#411 (CLI marketplace management)
• Enables [M1] Plugin Loading and Command Invocation OpenHands-CLI#409 (plugin resolution for slash commands)

---

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

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

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

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-agent-server/openhands/agent_server
conversation_router.py	119	13	89%	265, 323–326, 338–341, 354, 357–359
conversation_service.py	438	102	76%	122–123, 150, 153, 155, 162–168, 196, 203, 224, 323, 329, 334, 340, 348–349, 358–361, 370, 384–386, 393, 426–427, 466, 469, 486–490, 492–493, 496–497, 500–505, 587, 594–598, 601–602, 606–610, 613–614, 618–622, 625–626, 630–634, 637–638, 644–649, 656–657, 661, 663–664, 669–670, 676–677, 684–685, 689–691, 709, 733, 965, 968
event_service.py	325	85	73%	55–56, 74–76, 85–89, 92–95, 115, 219, 236, 290–291, 295, 303, 306, 352–353, 369, 371, 375–377, 381, 390–391, 393, 397, 403, 405, 413–418, 555, 557–558, 562, 576–578, 580, 584–587, 591–594, 602–605, 625, 629–634, 646–647, 649–650, 657–658, 660–661, 668–669, 671–672, 678, 684, 701–702
skills_router.py	68	4	94%	165–166, 168–169
skills_service.py	162	57	64%	125, 159, 162–165, 168–170, 173–174, 177–181, 184–188, 190, 194–195, 197, 208–212, 353–354, 358–360, 377, 405, 411, 414–415, 417–420, 425–426, 428, 431, 438–441, 445–446, 451–452, 454
openhands-sdk/openhands/sdk/context
agent_context.py	172	41	76%	154–155, 162–165, 167, 172–177, 179, 184, 220, 226–227, 229–232, 237–239, 242, 247–250, 254–255, 259–260, 262, 400–402, 431, 454, 460
openhands-sdk/openhands/sdk/context/skills
skill.py	434	33	92%	94–95, 249–250, 436–442, 445, 562–565, 790–791, 850–851, 919–920, 1003, 1031, 1054, 1061–1062, 1125–1126, 1132–1133, 1139–1140
openhands-sdk/openhands/sdk/conversation/impl
local_conversation.py	464	53	88%	291, 296, 325, 352–353, 356, 360–361, 364, 369, 375–376, 419, 437, 453, 518, 696–697, 700, 852, 860, 862, 866–867, 878, 880–882, 907, 979, 1105, 1109, 1179, 1210, 1220, 1258, 1262, 1269–1270, 1290, 1292, 1298, 1303, 1306–1308, 1310, 1312, 1314, 1320–1321, 1327–1328
remote_conversation.py	625	103	83%	77, 79, 150, 177, 190, 192–195, 205, 227–228, 233–236, 319, 329–331, 337, 378, 525–528, 530, 550–554, 559–562, 565, 581, 737–738, 742–743, 757, 781–782, 801, 812–813, 833–836, 838–839, 863–865, 868–872, 874–875, 879, 881–889, 891, 928, 1059, 1131–1132, 1136, 1141–1145, 1151–1157, 1170–1171, 1206, 1262, 1269, 1275–1276, 1338–1339, 1381–1382
openhands-sdk/openhands/sdk/plugin
registry.py	117	2	98%	185–186
types.py	218	4	98%	205, 341, 682, 689
TOTAL	21826	5545	74%

[all-hands-bot]

🟢 Good taste - Clean implementation with elegant design.

Key strengths:

• Well-structured data models (MarketplaceRegistration, MarketplaceRegistry) with clear separation of concerns
• Security improvement: path validation now uses normalization instead of simple .. checks, catching traversal tricks
• Proper backward compatibility with clear deprecation path
• Comprehensive test coverage (21+ tests) using real marketplace directories, not excessive mocks
• Clean async architecture (router → service → event_service → conversation)

Linus would say: Data structures are right, no special cases, solves real problems. Ship it. 🚀

[enyst]

Thank you for this! Just trying to understand a detail.

@OpenHands Read this PR and the linked issue, and understand them well. I think I saw in the linked issue that 4 things should be deprecated, but in this PR description I see 1 thing to deprecate. Verify what I just said. Are the others replaced with other implementations here, WDYT, should others be deprecated, or what seems to happen about that? Answer directly as a comment on the PR on github.

[openhands-ai]

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

[enyst]

@enyst I checked the linked issue, this PR, and the API-breakage workflow.

You remembered correctly: #2494 lists 4 deprecations:

1. AgentContext.marketplace_path -> AgentContext.registered_marketplaces
2. load_public_skills(marketplace_path=...) -> marketplace registry
3. load_available_skills(marketplace_path=...) -> marketplace registry
4. SkillsRequest.marketplace_path -> SkillsRequest.registered_marketplaces

From the code in this PR, though, I only see #1 actually deprecated today:

• AgentContext.marketplace_path is marked deprecated=True and also emits a DeprecationWarning in the backward-compat path.

The other 3 are not deprecated in the implementation yet:

• load_public_skills(marketplace_path=...) still exists unchanged and is still used by the current skill-loading path.
• load_available_skills(marketplace_path=...) still exists unchanged and is still what AgentContext/server skill loading call into.
• SkillsRequest.marketplace_path is still present on the agent-server /skills API, and I do not see a registered_marketplaces replacement added there in this PR.

So my read is: this PR introduces the new registration/resolution model (MarketplaceRegistration, MarketplaceRegistry, conversation.load_plugin() resolution against registered marketplaces), but it does not complete the full deprecation rollout described in #2494.

So I think the accurate framing is probably:

• This PR: deprecates AgentContext.marketplace_path and adds the new marketplace-registration mechanism for plugin resolution.
• Not yet done here: deprecating the old marketplace_path parameters on skill-loading helpers / /skills request model.

On the griffe / Python API breakage workflow: it failed because the checker compares public SDK API against the PyPI baseline, saw the Field(...) value for AgentContext.marketplace_path change (specifically adding deprecated=True), and counted that as an ATTRIBUTE_CHANGED_VALUE break. The checker has an allowlist for metadata-only Field(...) changes (description, title, examples, json_schema_extra), but not deprecated, so it treats this as breaking and then fails SemVer because the package version did not get a minor bump.

My take: for this specific case, that workflow is being too strict. The field is still there and still works; we are only marking it deprecated. I would not consider that alone a breaking Python API change that should require a minor bump. So I think either:

• the checker should also treat Field(..., deprecated=...) as a non-breaking metadata/deprecation annotation, or
• if the intended policy really is “adding deprecation metadata to a public field counts as a break,” then the current CI result is expected — but that would be a much stricter policy than the behavior this PR is trying to preserve.

So short version: yes, the issue says 4; this PR currently implements 1 of those deprecations, while the other 3 still look live / not migrated yet.

[enyst]

OpenHands-GPT-5.4 here — @enyst @jpshackelford, now that the small Griffe/Field(..., deprecated=...) CI fix is merged, I think there are two viable paths for this PR.

First, the key observation

Right now, the new model is only partially replacing the old one:

• registered_marketplaces is used for explicit plugin resolution via conversation.load_plugin(...)
• but the old path still drives actual skill auto-loading:
  • AgentContext._load_auto_skills() -> load_available_skills(..., marketplace_path=...)
  • load_available_skills() -> load_public_skills(marketplace_path=...)
• auto_load="all" is modeled, but I do not see production code actually using MarketplaceRegistry.get_auto_load_registrations() to auto-load marketplace plugins at conversation start
• agent-server /skills still exposes SkillsRequest.marketplace_path, and I do not see SkillsRequest.registered_marketplaces added yet

So the question is really: should this PR stay scoped to the part that is already implemented, or should it do a bit more so the new path is actually exercised end-to-end and more deprecations become justified?

Alternative 1: narrow the PR so the claims match the code

What this means

Keep this PR focused on:

• MarketplaceRegistration
• MarketplaceRegistry
• plugin resolution (plugin / plugin@marketplace)
• conversation.load_plugin()
• tests/examples for explicit marketplace-backed plugin loading

What I would do under this option

• remove or soften the deprecation claims in the PR description
• probably do not deprecate additional APIs yet
• possibly even reconsider whether AgentContext.marketplace_path should be deprecated in this PR, since its replacement does not yet cover the same startup/auto-load behavior end-to-end

Pros

• smallest, cleanest PR
• avoids promising more migration than the code currently delivers
• keeps the deprecation story honest

Cons

• leaves the full migration / auto-load rollout for a follow-up PR

Alternative 2: do a bit more in this PR so the new path is used more broadly

What “a bit more” would need to mean

If we want to deprecate more than just the field, I think this PR needs to wire the new model into the real startup path.

Concretely, I think that means:

1. Make conversation/plugin startup honor registered_marketplaces with auto_load="all"

   • at conversation startup, fetch the auto-load registrations
   • resolve/load all plugins declared by those marketplaces
   • merge their skills/hooks/MCP the same way explicit plugins are merged today

2. Keep backward compatibility for legacy users

   • if legacy marketplace_path is used and registered_marketplaces is empty, keep the current behavior working
   • deprecate the legacy field/path with warnings

3. If we want to deprecate the server-side request field too, add the additive replacement now

   • add SkillsRequest.registered_marketplaces
   • prefer it when present
   • keep SkillsRequest.marketplace_path working as the deprecated fallback

What this would justify deprecating

Under this option, I think these become more defensible:

• AgentContext.marketplace_path -> AgentContext.registered_marketplaces
• SkillsRequest.marketplace_path -> SkillsRequest.registered_marketplaces if the new request field is added in this PR

What I still would not deprecate yet

I would still be careful with:

• load_public_skills(marketplace_path=...)
• load_available_skills(marketplace_path=...)

Those are public SDK helpers and they are still the active implementation path today. Even if we extend this PR, I think the safer move is:

• either keep them for now,
• or later deprecate the marketplace_path parameter / old code path, not necessarily the whole helper function.

My recommendation

I recommend Alternative 1 unless you want to explicitly grow the PR into an end-to-end migration PR.

If the goal is to keep this PR tight, then I would:

• keep the new marketplace registration / resolution work
• describe it as the foundation for auto-load semantics
• avoid deprecating the other 3 APIs yet
• maybe even narrow the current deprecation language so it does not imply full replacement already exists

If the goal is to make this PR the real migration point, then I would choose Alternative 2, but in that case I would do the extra wiring above before deprecating more. In particular, I would not deprecate /skills request fields or SDK helper paths without also shipping the additive replacement in the same PR.

Short version

• Alternative 1: keep this PR narrower; deprecate less
• Alternative 2: wire registered_marketplaces into real startup/auto-load behavior, then deprecate more
• My recommendation: Alternative 1, unless you want to intentionally expand the implementation scope now

[neubig]

Could you please fix CI and re-request review? Thanks!

[enyst]

@OpenHands Give us a view on how this PR works and tell WDYT. /codereview Post directly on github as a review with gh api.

[openhands-ai]

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

[enyst]

Thanks — I dug through the issue, the PR, and the updated SDK/agent-server paths. My read is that the overall direction is good: MarketplaceRegistration + MarketplaceRegistry is the right shape, the lazy-fetch/caching model is straightforward, and the plugin resolution flow (plugin vs plugin@marketplace) looks reasonable.

That said, I don't think the new registration model is fully the source of truth yet. I found a few correctness gaps where the legacy marketplace_path flow is still driving behavior, or where load_plugin() doesn't apply the full plugin semantics it advertises. Left the concrete spots inline.

Because this touches plugin loading / agent behavior, I'd want a maintainer to take the final call after those are sorted and the intended end-to-end semantics are tightened up. WDYT?

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @jpshackelford, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @jpshackelford, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

[jpshackelford]

All review feedback has been addressed and the 3 inline review threads are now resolved.

CI Status: All required checks pass. The [Optional] Docs example/check-examples failure is a pre-existing issue about undocumented examples (e.g., 37_llm_profile_store, 45_parallel_tool_execution) that predates this PR and is unrelated to the marketplace registration changes.

[all-hands-bot]

[Automatic Post]: This PR seems to be currently waiting for review. @enyst, could you please take a look when you have a chance?