openhands-sdk 1.55.0__tar.gz → 1.56.0__tar.gz

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.55.0
+Version: 1.56.0
 Summary: OpenHands SDK - Core functionality for building AI agents
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk
@@ -15,7 +15,7 @@ Requires-Dist: filelock>=3.20.1
 Requires-Dist: httpx[socks]>=0.28.1
 Requires-Dist: jsonschema>=4.23.0
 Requires-Dist: joserfc>=1.7.5
-Requires-Dist: litellm>=1.93.0
+Requires-Dist: litellm<1.106,>=1.93.0
 Requires-Dist: pillow>=12.3.0
 Requires-Dist: pydantic>=2.13.5
 Requires-Dist: python-frontmatter>=1.3.0

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/agent/base.py

@@ -33,7 +33,6 @@ from openhands.sdk.mcp.client import MCPClient
 from openhands.sdk.mcp.config import MCPServer
 from openhands.sdk.mcp.tool import MCPToolDefinition, MCPToolExecutor
 from openhands.sdk.tool import (
-    BROWSER_TOOL_NAME,
     BUILT_IN_TOOL_CLASSES,
     BUILT_IN_TOOLS,
     Tool,
@@ -45,7 +44,6 @@ from openhands.sdk.tool.builtins.vision_inspect import (
     VisionInspectTool,
     has_vision_profile_available,
 )
-from openhands.sdk.utils.deprecation import warn_deprecated
 from openhands.sdk.utils.models import DiscriminatedUnionMixin
 from openhands.sdk.utils.path import get_user_persistence_dir
 
@@ -268,21 +266,11 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
 
     @field_validator("system_prompt_kwargs")
     @classmethod
-    def _warn_deprecated_enable_browser(
+    def _drop_retired_enable_browser(
         cls, value: dict[str, object]
     ) -> dict[str, object]:
-        if "enable_browser" in value:
-            warn_deprecated(
-                "system_prompt_kwargs['enable_browser']",
-                deprecated_in="1.51.0",
-                removed_in="1.56.0",
-                details=(
-                    "Browser guidance now comes from the loaded browser tools; "
-                    "only custom Jinja templates still read this kwarg."
-                ),
-                stacklevel=5,
-            )
-        return value
+        """Old saved conversations may still carry this retired prompt flag."""
+        return {key: item for key, item in value.items() if key != "enable_browser"}
 
     condenser: CondenserBase | None = Field(
         default=None,
@@ -378,15 +366,10 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         # own Jinja template; everything else (incl. custom policies) uses the registry.
         preset = self._prompt_preset
         if preset is None:
-            # Deprecated kwarg, kept until 1.56.0 for templates that branch on it.
-            template_kwargs = {
-                "enable_browser": any(t.name == BROWSER_TOOL_NAME for t in self.tools),
-                **self._resolved_template_kwargs(),
-            }
             return render_template(
                 prompt_dir=self.prompt_dir,
                 template_name=self.system_prompt_filename,
-                **template_kwargs,
+                **self._resolved_template_kwargs(),
             )
 
         return create_registry(preset).build(self._build_prompt_context()).static

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/conversation/impl/local_conversation.py

@@ -177,6 +177,16 @@ def _copy_event_for_fork(event: Event) -> Event:
     return Event.model_validate_json(event.model_dump_json(exclude_none=True))
 
 
+def _same_llm_config(a: LLM, b: LLM) -> bool:
+    """Return whether two LLMs serialize to the same config, secrets included."""
+    if a is b:
+        return True
+    context = {"expose_secrets": True}
+    return a.model_dump(mode="json", context=context) == b.model_dump(
+        mode="json", context=context
+    )
+
+
 class LocalConversation(BaseConversation):
     agent: AgentBase
     workspace: LocalWorkspace
@@ -1664,18 +1674,31 @@ class LocalConversation(BaseConversation):
         """Swap the agent's LLM to the given object.
 
         The caller owns ``llm.usage_id``; it is the registry key. If an
-        entry with that key already exists, the cached LLM is reused and
-        the passed ``llm`` is dropped — matching the rest of the
-        registry's "first-write-wins" contract.
+        entry with that key already exists and has the same config, the
+        cached LLM is reused. If its config differs (e.g. ``default``, which
+        agent initialization registers, posted with another model), the
+        passed ``llm`` replaces the entry and takes over the metrics already
+        recorded under that ``usage_id``.
 
         Args:
             llm: LLM to install on the agent.
         """
+        usage_id = llm.usage_id
         try:
-            new_llm = self.llm_registry.get(llm.usage_id)
+            registered = self.llm_registry.get(usage_id)
         except KeyError:
+            registered = None
+        if registered is not None and _same_llm_config(registered, llm):
+            new_llm = registered
+        else:
             new_llm = create_subscription_llm_from_config(llm)
+            if registered is not None:
+                self.llm_registry.remove(usage_id)
             self.llm_registry.add(new_llm)
+            if registered is not None:
+                # Keep one metrics object per usage_id: ConversationStats
+                # tracks the registered LLM's, so accrued usage is retained.
+                new_llm.restore_metrics(registered.metrics)
         # A switch_llm tool runs on a worker thread while run()/arun() holds the
         # state lock across the agent step on another thread, blocked awaiting
         # this very tool. Re-acquiring _state here would deadlock, so skip it:
@@ -1760,7 +1783,8 @@ class LocalConversation(BaseConversation):
 
         Raises:
             ValueError: If the conversation's agent is not an :class:`ACPAgent`,
-                or (for a live switch) the provider does not support runtime
+                if ``model`` is empty or whitespace-only (live or not), or
+                (for a live switch) the provider does not support runtime
                 model switching, or the ACP server rejects the switch.
             TimeoutError: If a live switch's ``session/set_model`` round-trip
                 exceeds ``acp_prompt_timeout`` seconds.
@@ -1769,6 +1793,10 @@ class LocalConversation(BaseConversation):
             raise ValueError(
                 "switch_acp_model is only supported for ACP conversations."
             )
+        # Check here, not only in set_acp_model: the pre-run path below skips
+        # that call and would persist a blank model unchecked.
+        if not model or not model.strip():
+            raise ValueError("model must be a non-empty string")
         with self._state:
             # With a live session, perform the protocol switch first; if it
             # fails we leave the persisted state untouched. Without one (pre

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/conversation/impl/remote_conversation.py

@@ -13,6 +13,7 @@ from urllib.parse import urlparse
 
 import httpx
 import websockets
+from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices
 from websockets.exceptions import ConnectionClosed
 
 from openhands.sdk.agent.base import AgentBase
@@ -34,6 +35,7 @@ from openhands.sdk.conversation.title_utils import generate_conversation_title
 from openhands.sdk.conversation.types import (
     ConversationCallbackType,
     ConversationID,
+    ConversationTokenCallbackType,
     StuckDetectionThresholds,
     TraceMetadataValue,
 )
@@ -49,6 +51,7 @@ from openhands.sdk.event.conversation_state import (
     ConversationStateUpdateEvent,
 )
 from openhands.sdk.event.llm_completion_log import LLMCompletionLogEvent
+from openhands.sdk.event.streaming_delta import StreamingDeltaEvent
 from openhands.sdk.event.types import EventID
 from openhands.sdk.hooks import HookConfig
 from openhands.sdk.llm import LLM, Message, TextContent
@@ -92,6 +95,26 @@ def _validate_remote_agent(agent_data: dict) -> AgentBase:
     return AgentBase.model_validate(agent_data)
 
 
+def _token_delta_callback(
+    token_callbacks: list[ConversationTokenCallbackType],
+) -> ConversationCallbackType:
+    """Hand each streamed delta from the events socket to the token callbacks."""
+    on_token = BaseConversation.compose_callbacks(token_callbacks)
+
+    def callback(event: Event) -> None:
+        if isinstance(event, StreamingDeltaEvent):
+            delta = Delta(
+                content=event.content, reasoning_content=event.reasoning_content
+            )
+            on_token(
+                ModelResponseStream(
+                    id=event.id, choices=[StreamingChoices(index=0, delta=delta)]
+                )
+            )
+
+    return callback
+
+
 def _restore_tool_registrations(tool_module_qualnames: Mapping[str, str]) -> None:
     """Import the tool modules persisted with a remote conversation."""
     for tool_name, module_qualname in tool_module_qualnames.items():
@@ -493,9 +516,16 @@ class RemoteEventsList(EventsListBase):
         return len(self._cached_events) - 1
 
     def create_default_callback(self) -> ConversationCallbackType:
-        """Create a default callback that adds events to this list."""
+        """Create a default callback that adds events to this list.
+
+        Streamed ``StreamingDeltaEvent`` frames are transient: the server never
+        stores them, so they reach the other callbacks but stay out of this
+        list, which keeps matching the server's event log.
+        """
 
         def callback(event: Event) -> None:
+            if isinstance(event, StreamingDeltaEvent):
+                return
             self.add_event(event)
 
         return callback
@@ -746,6 +776,7 @@ class RemoteConversation(BaseConversation):
         observability_tags: list[str] | None = None,
         observability_span_name: str = "conversation",
         observability_parent_span_context: str | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
         **_: object,
     ) -> None:
         """Remote conversation proxy that talks to an agent server.
@@ -783,6 +814,8 @@ class RemoteConversation(BaseConversation):
             observability_tags: Optional root span tags for observability backends.
             observability_span_name: Optional child span name for observability
                       backends. The root span remains named "conversation".
+            token_callbacks: Optional callbacks invoked with each streamed token
+                      delta the server sends (agent LLM with ``stream=True``).
         """
         observability_metadata = merge_observability_metadata(observability_metadata)
         observability_parent_span_context = (
@@ -920,6 +953,7 @@ class RemoteConversation(BaseConversation):
             workspace=workspace,
             conversation_id=conversation_id,
             callbacks=callbacks,
+            token_callbacks=token_callbacks,
             max_iteration_per_run=max_iteration_per_run,
             client_tools=[*(client_tools or []), *attached_client_tools],
             visualizer=visualizer,
@@ -1060,10 +1094,13 @@ class RemoteConversation(BaseConversation):
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ),
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
     ) -> None:
         super().__init__()  # Initialize base class with span tracking
         self.agent = agent
         self._callbacks = callbacks or []
+        if token_callbacks:
+            self._callbacks.append(_token_delta_callback(token_callbacks))
         self.max_iteration_per_run = max_iteration_per_run
         self.workspace = workspace
         self._client = workspace.client
@@ -1166,13 +1203,40 @@ class RemoteConversation(BaseConversation):
         all_callbacks = self._callbacks + [run_complete_callback]
         composed_callback = BaseConversation.compose_callbacks(all_callbacks)
 
+        # Track which events the callbacks have seen, so that events the
+        # server recorded while the socket was reconnecting (and that only
+        # reached the cache through REST reconciliation) can be replayed to
+        # them once, without the live socket delivering them a second time.
+        delivered_ids: set[str] = set()
+        replayed_ids: set[str] = set()
+
+        def socket_callback(event: Event) -> None:
+            if event.id in replayed_ids:
+                replayed_ids.discard(event.id)
+                return
+            delivered_ids.add(event.id)
+            composed_callback(event)
+
+        def replay_missed_events() -> None:
+            self._state.events.reconcile()
+            replayed_ids.clear()
+            for event in self._state.events[:]:
+                if event.id in delivered_ids:
+                    continue
+                delivered_ids.add(event.id)
+                replayed_ids.add(event.id)
+                try:
+                    composed_callback(event)
+                except Exception:
+                    logger.exception("ws_replay_callback_error", stack_info=True)
+
         # Initialize WebSocket client for callbacks
         self._ws_client = WebSocketCallbackClient(
             host=self.workspace.host,
             conversation_id=str(self._id),
-            callback=composed_callback,
+            callback=socket_callback,
             api_key=self.workspace.api_key,
-            on_reconnect=self._state.events.reconcile,
+            on_reconnect=replay_missed_events,
         )
         self._ws_client.start()
 
@@ -1210,6 +1274,9 @@ class RemoteConversation(BaseConversation):
         # were emitted between the initial REST sync and WebSocket subscription.
         # This is the "reconciliation" part of the subscription handshake.
         self._state.events.reconcile()
+        # Callbacks are not replayed history: only events recorded after this
+        # point and missed by the socket are replayed on reconnect.
+        delivered_ids.update(event.id for event in self._state.events[:])
 
     def _create_llm_completion_log_callback(self) -> ConversationCallbackType:
         """Create a callback that writes LLM completion logs to client filesystem."""

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/conversation/request.py

@@ -8,7 +8,7 @@ agent-server.
 
 from __future__ import annotations
 
-from typing import Annotated, Any, cast
+from typing import Annotated, Any, Literal, cast
 from uuid import UUID
 
 from pydantic import (
@@ -65,6 +65,53 @@ ACPEnabledAgent = Annotated[
 # ---------------------------------------------------------------------------
 
 
+class StartChildConversationRequest(BaseModel):
+    """Payload to start a child conversation on the same backend as its parent.
+
+    Sent by the ``start_child_conversation`` tool to a child-launch endpoint:
+    the agent-server's ``POST /api/conversations/{id}/children`` by default, or
+    an equivalent launcher supplied by the backend hosting the parent.
+    """
+
+    task: str = Field(
+        min_length=1,
+        description=(
+            "Self-contained brief delivered to the child as its first user message."
+        ),
+    )
+    title: str | None = Field(
+        default=None, description="Optional title for the child conversation."
+    )
+    isolation: Literal["worktree", "shared"] = Field(
+        default="worktree",
+        description=(
+            "Workspace isolation for the child. 'worktree' runs it in a git "
+            "worktree carved from the parent's workspace when that workspace is a "
+            "git repository; 'shared' runs it in the parent's directory. Backends "
+            "that manage workspaces themselves may ignore this."
+        ),
+    )
+
+
+class StartChildConversationResponse(BaseModel):
+    """Result of a child conversation launch, returned to the parent agent."""
+
+    conversation_id: UUID
+    parent_conversation_id: UUID
+    status: str = Field(description="Initial launch status reported by the backend.")
+    title: str | None = None
+    url: str | None = Field(
+        default=None,
+        description="Link to the child conversation, when the backend knows it.",
+    )
+    workspace: str | None = Field(
+        default=None, description="Working directory of the child, when known."
+    )
+    isolation: Literal["worktree", "shared"] | None = Field(
+        default=None, description="Workspace isolation actually applied, when known."
+    )
+
+
 class AgentLaunchAdditions(BaseModel):
     """Add deployment context after agent resolution."""
 

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/git/git_changes.py

@@ -9,7 +9,11 @@ import logging
 import os
 from pathlib import Path
 
-from openhands.sdk.git.exceptions import GitCommandError, GitError
+from openhands.sdk.git.exceptions import (
+    GitCommandError,
+    GitError,
+    GitRepositoryError,
+)
 from openhands.sdk.git.models import GitChange, GitChangeStatus
 from openhands.sdk.git.utils import (
     get_valid_ref,
@@ -154,7 +158,9 @@ def get_changes_in_repo(
     vs the latest commit) instead.
 
     Args:
-        repo_dir: Path to the git repository
+        repo_dir: Path to the git repository, or to a directory inside one.
+            Only changes under this directory are listed, with paths relative
+            to it.
         ref: Optional explicit ref to compare against (e.g. ``"HEAD"`` or a
             commit hash). When ``None``, behaves as before and compares
             against the upstream/default branch.
@@ -178,10 +184,14 @@ def get_changes_in_repo(
         logger.warning(f"No valid git reference found for {validated_repo}")
         return []
 
-    # Get changed files using secure git command
+    # Get changed files using secure git command. ``--relative`` limits the
+    # diff to ``repo_dir`` and prints paths relative to it, the same base as
+    # ``git ls-files --others`` below, so a subdirectory of a repository does
+    # not mix repository-relative and subdirectory-relative paths.
     try:
         changed_files_output = run_git_command(
-            ["git", "--no-pager", "diff", "--name-status", ref], validated_repo
+            ["git", "--no-pager", "diff", "--name-status", "--relative", ref],
+            validated_repo,
         )
         changed_files = (
             changed_files_output.splitlines() if changed_files_output else []
@@ -221,8 +231,17 @@ def get_git_changes(cwd: str | Path, ref: str | None = None) -> list[GitChange]:
         for f in glob.glob("./*/.git", root_dir=cwd, recursive=True)
     }
 
-    # First try the workspace directory
-    changes = get_changes_in_repo(cwd, ref=ref)
+    # First try the workspace directory. A directory that is not a repository
+    # itself but holds repositories below it (the ``{base}/{repo}`` layout of a
+    # repository-backed conversation) contributes no changes of its own.
+    base_error: GitRepositoryError | None = None
+    try:
+        changes = get_changes_in_repo(cwd, ref=ref)
+    except GitRepositoryError as e:
+        if not git_dirs:
+            raise
+        base_error = e
+        changes = []
 
     # Filter out any changes which are inside one of the nested repositories.
     # This compares path ancestry rather than string prefixes: a nested
@@ -236,6 +255,7 @@ def get_git_changes(cwd: str | Path, ref: str | None = None) -> list[GitChange]:
     ]
 
     # Add changes from git directories
+    found_nested_repo = False
     for git_dir in git_dirs:
         try:
             git_dir_changes = get_changes_in_repo(str(Path(cwd, git_dir)), ref=ref)
@@ -244,6 +264,7 @@ def get_git_changes(cwd: str | Path, ref: str | None = None) -> list[GitChange]:
                 f"Skipping nested git directory {git_dir}: not a valid repository"
             )
             continue
+        found_nested_repo = True
         for change in git_dir_changes:
             # Create a new GitChange with the updated path
             updated_change = GitChange(
@@ -252,6 +273,10 @@ def get_git_changes(cwd: str | Path, ref: str | None = None) -> list[GitChange]:
             )
             changes.append(updated_change)
 
+    # Neither the directory nor anything below it is a repository.
+    if base_error is not None and not found_nested_repo:
+        raise base_error
+
     changes.sort(key=lambda change: str(change.path))
 
     return changes

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/llm/llm_profile_store.py

@@ -34,6 +34,12 @@ _LOCK_TIMEOUT_SECONDS: Final[float] = 30.0
 PROFILE_NAME_PATTERN: Final[str] = r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
 PROFILE_NAME_REGEX: Final[re.Pattern[str]] = re.compile(PROFILE_NAME_PATTERN)
 
+
+def canonical_profile_name(name: str) -> str:
+    """Return the store key ``name`` addresses: ``foo.json`` is profile ``foo``."""
+    return name.removesuffix(".json")
+
+
 logger = get_logger(__name__)
 
 
@@ -163,7 +169,7 @@ class LLMProfileStore:
         Raises:
             ValueError: If name does not match the allowed pattern.
         """
-        clean_name = name.removesuffix(".json")
+        clean_name = canonical_profile_name(name)
         if not PROFILE_NAME_REGEX.match(clean_name):
             raise ValueError(
                 f"Invalid profile name: {name!r}. "

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/llm/meta_profile_store.py

@@ -10,7 +10,6 @@ string — credentials/provider settings resolve through that store.
 from __future__ import annotations
 
 import json
-import os
 import re
 import tempfile
 from collections.abc import Iterator
@@ -23,6 +22,7 @@ from pydantic import BaseModel, Field, model_validator
 
 from openhands.sdk.llm.llm_profile_store import PROFILE_NAME_REGEX
 from openhands.sdk.logger import get_logger
+from openhands.sdk.utils.path import get_user_persistence_dir
 
 
 _LOCK_TIMEOUT_SECONDS: Final[float] = 30.0
@@ -37,11 +37,10 @@ def default_meta_profile_dir() -> Path:
     persisted state. Honor that for bare ``MetaProfileStore()`` instances so
     runtime tools read the same meta-profiles exposed by the HTTP API. Without
     that env var, keep the standalone SDK default under ``~/.openhands``.
+    Resolved at call time through ``get_user_persistence_dir`` so ``~`` and
+    relative values land where the other stores put their files.
     """
-    env_dir = os.environ.get("OH_PERSISTENCE_DIR")
-    if env_dir:
-        return Path(env_dir) / "meta-profiles"
-    return Path.home() / ".openhands" / "meta-profiles"
+    return get_user_persistence_dir() / "meta-profiles"
 
 
 class MetaProfileLimitExceeded(Exception):

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/llm/utils/unverified_models.py

@@ -51,6 +51,19 @@ def _list_bedrock_foundation_models(
         return []
 
 
+def _is_litellm_bedrock_model(model: str) -> bool:
+    """Whether LiteLLM serves ``model`` only through AWS Bedrock.
+
+    Many Bedrock ids carry no ``bedrock`` prefix (``deepseek.r1-v1:0``,
+    ``us.anthropic.claude-...``), so ask LiteLLM's model-cost map which provider
+    it files the id under (``bedrock``, ``bedrock_converse``, ``bedrock_mantle``).
+    """
+    if model.startswith("bedrock"):
+        return True
+    provider = litellm.model_cost.get(model, {}).get("litellm_provider")
+    return isinstance(provider, str) and provider.startswith("bedrock")
+
+
 def get_supported_llm_models(
     aws_region_name: str | None = None,
     aws_access_key_id: SecretStr | None = None,
@@ -68,9 +81,9 @@ def get_supported_llm_models(
         + list(litellm.model_cost.keys())
         + [f"openrouter/{model}" for model in VERIFIED_MODELS["openrouter"]]
     )
-    litellm_model_list_without_bedrock = list(
-        filter(lambda m: not m.startswith("bedrock"), litellm_model_list)
-    )
+    litellm_model_list_without_bedrock = [
+        m for m in litellm_model_list if not _is_litellm_bedrock_model(m)
+    ]
     bedrock_model_list = []
     if aws_region_name and aws_access_key_id and aws_secret_access_key:
         bedrock_model_list = _list_bedrock_foundation_models(

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/marketplace/registry.py

@@ -76,6 +76,25 @@ class MarketplaceNotFoundError(PluginResolutionError):
         super().__init__(f"Marketplace '{marketplace_name}' is not registered")
 
 
+def _load_marketplace(path: Path, name: str) -> Marketplace:
+    """Load the manifest, or read a source without one as a plain skills folder."""
+    try:
+        return Marketplace.load(path)
+    except FileNotFoundError as missing_manifest:
+        marketplace = Marketplace.from_skills_dir(path, name)
+        if not marketplace.skills:
+            raise FileNotFoundError(
+                f"{missing_manifest}, and no skill folders (<name>/SKILL.md) "
+                "were found there"
+            ) from missing_manifest
+        logger.info(
+            "Marketplace '%s' has no manifest; using %d skills from its folder",
+            name,
+            len(marketplace.skills),
+        )
+        return marketplace
+
+
 class MarketplaceRegistry:
     """Resolve plugin references against registered marketplaces."""
 
@@ -165,7 +184,7 @@ class MarketplaceRegistry:
             repo_path=registration.repo_path,
         )
         fetched = FetchedMarketplace(
-            marketplace=Marketplace.load(path),
+            marketplace=_load_marketplace(path, registration.name),
             path=path,
             resolved_ref=resolved_ref,
         )

{openhands_sdk-1.55.0 → openhands_sdk-1.56.0}/openhands/sdk/marketplace/types.py

@@ -8,6 +8,7 @@ from typing import Any
 
 from pydantic import BaseModel, Field, field_validator, model_validator
 
+from openhands.sdk.logger import get_logger
 from openhands.sdk.plugin.types import (
     HooksConfigDict,
     LspServersDict,
@@ -17,6 +18,8 @@ from openhands.sdk.plugin.types import (
 )
 
 
+logger = get_logger(__name__)
+
 # Directories to check for marketplace manifest
 MARKETPLACE_MANIFEST_DIRS = [".plugin", ".claude-plugin"]
 MARKETPLACE_MANIFEST_FILE = "marketplace.json"
@@ -260,6 +263,58 @@ class Marketplace(BaseModel):
 
         return cls.model_validate({**data, "path": str(marketplace_dir)})
 
+    @classmethod
+    def from_skills_dir(cls, marketplace_path: str | Path, name: str) -> Marketplace:
+        """Build a marketplace from a plain folder of skills, without a manifest.
+
+        Each ``<name>/SKILL.md`` folder becomes a standalone skill: those in
+        ``skills/`` and ``.skills/``, or, when neither exists, those directly in
+        ``marketplace_path``, so a ``repo_path`` can point at the skills folder
+        itself. Loose markdown files are not read, so a repository's README and
+        docs never become skills. The result has no skills when none are found.
+
+        Args:
+            marketplace_path: Path to the repository or skills folder.
+            name: Marketplace name, since there is no manifest to supply one.
+
+        Returns:
+            Marketplace listing the discovered skills, with no plugins.
+        """
+        from openhands.sdk.skills import Skill
+        from openhands.sdk.skills.utils import find_skill_md_directories
+
+        marketplace_dir = Path(marketplace_path).resolve()
+        skills_dirs = [
+            path
+            for path in (marketplace_dir / "skills", marketplace_dir / ".skills")
+            if path.is_dir()
+        ] or [marketplace_dir]
+
+        entries: dict[str, MarketplaceEntry] = {}
+        for skills_dir in skills_dirs:
+            for skill_md in find_skill_md_directories(skills_dir, marketplace_dir):
+                try:
+                    skill = Skill.load(skill_md, strict=False)
+                except Exception as e:
+                    logger.warning(f"Failed to load skill from {skill_md}: {e}")
+                    continue
+                source = skill_md.parent.relative_to(marketplace_dir).as_posix()
+                entries.setdefault(
+                    skill.name,
+                    MarketplaceEntry(
+                        name=skill.name,
+                        source=f"./{source}",
+                        description=skill.description,
+                    ),
+                )
+
+        return cls(
+            name=name,
+            owner=MarketplaceOwner(name=name),
+            skills=list(entries.values()),
+            path=str(marketplace_dir),
+        )
+
     def get_plugin(self, name: str) -> MarketplacePluginEntry | None:
         """Get a plugin entry by name.