@openhands/extensions 0.9.0 → 0.11.0

package/integrations/catalog.schema.json

@@ -5,7 +5,7 @@
   "description": "Strict schema for integrations/catalog/*.json. Mirrors integrations/index.d.ts and encodes the cross-field connectability rules the catalog contract depends on.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["id", "name", "description", "connectionOptions"],
+  "required": ["id", "name", "description", "docsUrl", "connectionOptions"],
   "properties": {
     "id": { "type": "string", "minLength": 1 },
     "name": { "type": "string", "minLength": 1 },
@@ -39,7 +39,7 @@
     "marketplaceField": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["key", "label"],
+      "required": ["key", "label", "type", "required"],
       "properties": {
         "key": { "type": "string", "minLength": 1 },
         "label": { "type": "string", "minLength": 1 },
@@ -91,6 +91,72 @@
         }
       }
     },
+    "identityPath": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*$",
+      "minLength": 1
+    },
+    "identityMapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "externalPrincipalIdPath"],
+      "properties": {
+        "source": {
+          "enum": ["oauth_token_response", "access_token_claims", "identity_api"]
+        },
+        "endpoint": { "type": "string", "pattern": "^https://", "minLength": 8 },
+        "externalPrincipalIdPath": { "$ref": "#/$defs/identityPath" },
+        "externalTenantIdPath": { "$ref": "#/$defs/identityPath" },
+        "externalResourceIdPath": { "$ref": "#/$defs/identityPath" },
+        "resourceNamePath": { "$ref": "#/$defs/identityPath" },
+        "resourceUrlPath": { "$ref": "#/$defs/identityPath" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "source": { "const": "identity_api" } } },
+          "then": { "required": ["endpoint"] },
+          "else": { "not": { "required": ["endpoint"] } }
+        }
+      ]
+    },
+    "resourceDiscovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["endpoint", "externalResourceIdPath"],
+      "properties": {
+        "endpoint": { "type": "string", "pattern": "^https://", "minLength": 8 },
+        "itemsPath": { "$ref": "#/$defs/identityPath" },
+        "externalResourceIdPath": { "$ref": "#/$defs/identityPath" },
+        "resourceNamePath": { "$ref": "#/$defs/identityPath" },
+        "resourceUrlPath": { "$ref": "#/$defs/identityPath" }
+      }
+    },
+    "connectionModel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "principalType",
+        "credentialScope",
+        "resourceType",
+        "resourceCardinality",
+        "selectionMode"
+      ],
+      "properties": {
+        "principalType": { "enum": ["user", "bot", "service_account", "application"] },
+        "credentialScope": { "enum": ["account", "tenant", "organization", "resource"] },
+        "resourceType": { "type": "string", "minLength": 1 },
+        "resourceCardinality": { "enum": ["one", "many"] },
+        "selectionMode": { "enum": ["automatic", "post_auth", "runtime"] },
+        "identityMapping": { "$ref": "#/$defs/identityMapping" },
+        "resourceDiscovery": { "$ref": "#/$defs/resourceDiscovery" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "selectionMode": { "const": "post_auth" } } },
+          "then": { "required": ["resourceDiscovery"] }
+        }
+      ]
+    },
     "authConfig": {
       "type": "object",
       "additionalProperties": false,
@@ -186,7 +252,8 @@
         "provider": { "enum": ["mcp", "http"] },
         "transport": { "$ref": "#/$defs/transport" },
         "http": { "$ref": "#/$defs/httpConfig" },
-        "auth": { "$ref": "#/$defs/authConfig" }
+        "auth": { "$ref": "#/$defs/authConfig" },
+        "connectionModel": { "$ref": "#/$defs/connectionModel" }
       },
       "allOf": [
         {

package/integrations/index.d.ts

@@ -3,11 +3,11 @@ export type MarketplaceFieldType = "text" | "password";
 export interface MarketplaceField {
   key: string;
   label: string;
-  type?: MarketplaceFieldType;
+  type: MarketplaceFieldType;
   placeholder?: string;
   helperText?: string;
   helperLink?: string;
-  required?: boolean;
+  required: boolean;
 }
 
 export type IntegrationTransport =
@@ -95,12 +95,58 @@ export interface IntegrationHttpConfig {
   openApiUrl?: string;
 }
 
+export type IntegrationPrincipalType =
+  | "user"
+  | "bot"
+  | "service_account"
+  | "application";
+
+export type IntegrationCredentialScope =
+  | "account"
+  | "tenant"
+  | "organization"
+  | "resource";
+
+export type IntegrationIdentitySource =
+  | "oauth_token_response"
+  | "access_token_claims"
+  | "identity_api";
+
+export interface IntegrationIdentityMapping {
+  source: IntegrationIdentitySource;
+  endpoint?: string;
+  externalPrincipalIdPath: string;
+  externalTenantIdPath?: string;
+  externalResourceIdPath?: string;
+  resourceNamePath?: string;
+  resourceUrlPath?: string;
+}
+
+export interface IntegrationResourceDiscovery {
+  endpoint: string;
+  itemsPath?: string;
+  externalResourceIdPath: string;
+  resourceNamePath?: string;
+  resourceUrlPath?: string;
+}
+
+export interface IntegrationConnectionModel {
+  principalType: IntegrationPrincipalType;
+  credentialScope: IntegrationCredentialScope;
+  resourceType: string;
+  resourceCardinality: "one" | "many";
+  selectionMode: "automatic" | "post_auth" | "runtime";
+  identityMapping?: IntegrationIdentityMapping;
+  resourceDiscovery?: IntegrationResourceDiscovery;
+}
+
 export interface IntegrationConnectionOption {
   id: "oauth" | "api" | "none" | string;
   provider: IntegrationProvider;
   transport?: IntegrationTransport;
   http?: IntegrationHttpConfig;
   auth: IntegrationAuthConfig;
+  connectionModel?: IntegrationConnectionModel;
 }
 
 
@@ -110,7 +156,7 @@ export interface IntegrationCatalogEntry {
   description: string;
   categories?: string[];
   appUrl?: string;
-  docsUrl?: string;
+  docsUrl: string;
   notes?: string;
   iconBg?: string;
   iconColor?: string;

package/marketplaces/openhands-extensions.json

@@ -729,6 +729,15 @@
         "automation"
       ]
     },
+    {
+      "name": "technical-writing",
+      "source": "./skills/technical-writing",
+      "description": "Write and revise technical explanations in flowing, direct, conversational prose that stays concise without becoming fragmented or vague.",
+      "category": "productivity",
+      "keywords": [
+        "technical-writing"
+      ]
+    },
     {
       "name": "plain-english-content",
       "source": "./skills/plain-english-content",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -1,8 +1,13 @@
 [project]
 name = "openhands-extensions"
-version = "0.9.0"
+version = "0.11.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
+dependencies = [
+    "deprecation>=2.1,<3",
+    "packaging>=24,<26",
+    "pydantic>=2.10,<3",
+]
 
 [build-system]
 requires = ["hatchling>=1.21"]

package/python/openhands_extensions/__init__.py

@@ -13,12 +13,50 @@ from ._version import __version__
 from .integrations import (
     INTEGRATION_CATALOG_SNAPSHOT,
     get_integration_catalog_entry,
+    get_integration_catalog_entry_model,
     list_integration_catalog,
+    list_integration_catalog_models,
+)
+from .integration_models import (
+    HttpConnectionOption,
+    IntegrationAuthConfig,
+    IntegrationCatalogEntry,
+    IntegrationCatalogSnapshot,
+    IntegrationConnectionOption,
+    IntegrationConnectionModel,
+    IntegrationHttpConfig,
+    IntegrationIdentityMapping,
+    IntegrationOAuthConfig,
+    IntegrationResourceDiscovery,
+    IntegrationTransport,
+    McpConnectionOption,
+    MarketplaceField,
+    SseTransport,
+    StdioTransport,
+    StreamableHttpTransport,
 )
 
 __all__ = [
     "INTEGRATION_CATALOG_SNAPSHOT",
+    "HttpConnectionOption",
+    "IntegrationAuthConfig",
+    "IntegrationCatalogEntry",
+    "IntegrationCatalogSnapshot",
+    "IntegrationConnectionOption",
+    "IntegrationConnectionModel",
+    "IntegrationHttpConfig",
+    "IntegrationIdentityMapping",
+    "IntegrationOAuthConfig",
+    "IntegrationResourceDiscovery",
+    "IntegrationTransport",
+    "MarketplaceField",
+    "McpConnectionOption",
+    "SseTransport",
+    "StdioTransport",
+    "StreamableHttpTransport",
     "__version__",
     "get_integration_catalog_entry",
+    "get_integration_catalog_entry_model",
     "list_integration_catalog",
+    "list_integration_catalog_models",
 ]

package/python/openhands_extensions/_version.py

@@ -16,8 +16,8 @@ from importlib.metadata import PackageNotFoundError, version
 
 #: Fallback used only when the package is not installed (no dist metadata).
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
-# x-release-please-update-version
-_FALLBACK_VERSION = "0.9.0"
+# x-release-please-version
+_FALLBACK_VERSION = "0.11.0"
 
 try:
     __version__: str = version("openhands-extensions")

package/python/openhands_extensions/deprecation.py

@@ -0,0 +1,159 @@
+"""Versioned deprecation helpers for OpenHands extensions.
+
+This module intentionally mirrors ``openhands.sdk.utils.deprecation`` so public
+extension APIs use the same decorator, runtime warning, and model-input
+compatibility behavior as the SDK.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from datetime import date
+from functools import cache
+from importlib.metadata import PackageNotFoundError, version as get_version
+from typing import Any, TypeVar, cast
+
+from deprecation import (
+    DeprecatedWarning,
+    UnsupportedWarning,
+    deprecated as _deprecated,
+)
+from packaging import version as pkg_version
+
+
+_FuncT = TypeVar("_FuncT", bound=Callable[..., Any])
+
+
+@cache
+def _current_version() -> str:
+    try:
+        return get_version("openhands-extensions")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+def deprecated(
+    *,
+    deprecated_in: str,
+    removed_in: str | date | None,
+    current_version: str | None = None,
+    details: str = "",
+) -> Callable[[_FuncT], _FuncT]:
+    """Return a decorator that deprecates a callable with explicit metadata."""
+    base_decorator = _deprecated(
+        deprecated_in=deprecated_in,
+        removed_in=removed_in,
+        current_version=current_version or _current_version(),
+        details=details,
+    )
+
+    def decorator(func: _FuncT) -> _FuncT:
+        return cast(_FuncT, base_decorator(func))
+
+    return decorator
+
+
+def _should_warn(
+    *,
+    deprecated_in: str | None,
+    removed_in: str | date | None,
+    current_version: str | None,
+) -> tuple[bool, bool]:
+    is_deprecated = False
+    is_unsupported = False
+
+    if isinstance(removed_in, date):
+        if date.today() >= removed_in:
+            is_unsupported = True
+        else:
+            is_deprecated = True
+    elif current_version:
+        current = pkg_version.parse(current_version)
+        if removed_in and current >= pkg_version.parse(str(removed_in)):
+            is_unsupported = True
+        elif deprecated_in and current >= pkg_version.parse(deprecated_in):
+            is_deprecated = True
+    else:
+        is_deprecated = True
+
+    return is_deprecated, is_unsupported
+
+
+def warn_deprecated(
+    feature: str,
+    *,
+    deprecated_in: str,
+    removed_in: str | date | None,
+    current_version: str | None = None,
+    details: str = "",
+    stacklevel: int = 2,
+) -> None:
+    """Emit a deprecation warning for dynamic access to a legacy feature."""
+    current_version = current_version or _current_version()
+    is_deprecated, is_unsupported = _should_warn(
+        deprecated_in=deprecated_in,
+        removed_in=removed_in,
+        current_version=current_version,
+    )
+
+    if not (is_deprecated or is_unsupported):
+        return
+
+    warning_cls = UnsupportedWarning if is_unsupported else DeprecatedWarning
+    warning = warning_cls(feature, deprecated_in, removed_in, details)
+    warnings.warn(warning, stacklevel=stacklevel)
+
+
+def warn_cleanup(
+    workaround: str,
+    *,
+    cleanup_by: str | date,
+    current_version: str | None = None,
+    details: str = "",
+    stacklevel: int = 2,
+) -> None:
+    """Emit a warning when a temporary workaround has reached its deadline."""
+    current_version = current_version or _current_version()
+
+    should_cleanup = False
+    if isinstance(cleanup_by, date):
+        should_cleanup = date.today() >= cleanup_by
+    else:
+        try:
+            current = pkg_version.parse(current_version)
+            target = pkg_version.parse(str(cleanup_by))
+            should_cleanup = current >= target
+        except pkg_version.InvalidVersion:
+            pass
+
+    if should_cleanup:
+        message = (
+            f"Cleanup required: {workaround}. "
+            f"This workaround was scheduled for removal by {cleanup_by}."
+        )
+        if details:
+            message += f" {details}"
+        warnings.warn(message, UserWarning, stacklevel=stacklevel)
+
+
+def handle_deprecated_model_fields(
+    data: Any,
+    deprecated_fields: tuple[str, ...],
+) -> Any:
+    """Remove permanently supported legacy fields from Pydantic model input."""
+    if not isinstance(data, dict):
+        return data
+
+    for field in deprecated_fields:
+        data.pop(field, None)
+
+    return data
+
+
+__all__ = [
+    "deprecated",
+    "warn_deprecated",
+    "warn_cleanup",
+    "handle_deprecated_model_fields",
+]

package/python/openhands_extensions/integration_models.py

@@ -0,0 +1,233 @@
+"""Typed models for the OpenHands integration catalog.
+
+The hand-authored JSON files under ``integrations/catalog`` remain the source
+of truth. These models provide a Python representation of the public catalog
+contract defined by ``integrations/catalog.schema.json`` and
+``integrations/index.d.ts``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+NonEmptyString = Annotated[str, Field(min_length=1)]
+HttpsUrl = Annotated[str, Field(pattern=r"^https://", min_length=8)]
+IdentityPath = Annotated[
+    str,
+    Field(pattern=r"^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$", min_length=1),
+]
+IntegrationAuthStrategy = Literal["none", "api_key", "bearer", "basic", "oauth2"]
+IntegrationProvider = Literal["mcp", "http"]
+
+
+class CatalogModel(BaseModel):
+    """Base model for strict, portable catalog data."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="before")
+    @classmethod
+    def reject_explicit_nulls(cls, values: Any) -> Any:
+        """Match the JSON Schema: optional fields may be omitted, never null."""
+        if not isinstance(values, dict):
+            return values
+
+        null_fields = [field for field, value in values.items() if value is None]
+        if null_fields:
+            raise ValueError(
+                "Catalog fields must be omitted instead of set to null: "
+                f"{', '.join(null_fields)}"
+            )
+        return values
+
+
+class MarketplaceField(CatalogModel):
+    key: NonEmptyString
+    label: NonEmptyString
+    type: Literal["text", "password"]
+    placeholder: str | None = None
+    helperText: str | None = None
+    helperLink: HttpsUrl | None = None
+    required: bool
+
+    @model_validator(mode="after")
+    def password_fields_have_help(self) -> MarketplaceField:
+        if self.type == "password" and not self.helperText:
+            raise ValueError("Password marketplace fields require helperText.")
+        return self
+
+
+class StreamableHttpTransport(CatalogModel):
+    kind: Literal["shttp"]
+    url: HttpsUrl
+    apiKeyOptional: bool | None = None
+    headerFields: list[MarketplaceField] | None = None
+    urlEditable: bool | None = None
+
+
+class SseTransport(CatalogModel):
+    kind: Literal["sse"]
+    url: HttpsUrl
+    apiKeyOptional: bool | None = None
+    headerFields: list[MarketplaceField] | None = None
+    urlEditable: bool | None = None
+
+
+class StdioTransport(CatalogModel):
+    kind: Literal["stdio"]
+    serverName: NonEmptyString
+    command: NonEmptyString
+    args: list[str]
+    envFields: list[MarketplaceField] | None = None
+    argFields: list[MarketplaceField] | None = None
+
+
+IntegrationTransport = Annotated[
+    StreamableHttpTransport | SseTransport | StdioTransport,
+    Field(discriminator="kind"),
+]
+
+
+class IntegrationOAuthConfig(CatalogModel):
+    authorizationUrl: HttpsUrl | None = None
+    tokenUrl: HttpsUrl | None = None
+    scopes: list[NonEmptyString] | None = None
+    optionalScopes: list[NonEmptyString] | None = None
+    toolScopes: list[NonEmptyString] | None = None
+    scopeSeparator: Literal["space", "comma"] | None = None
+    pkce: bool | None = None
+    clientAuthentication: Literal["basic", "body", "none"] | None = None
+    registrationUrl: HttpsUrl | None = None
+    additionalAuthorizationParams: dict[str, str] | None = None
+    additionalTokenParams: dict[str, str] | None = None
+
+
+class IntegrationAuthConfig(CatalogModel):
+    strategy: IntegrationAuthStrategy
+    authModes: list[IntegrationAuthStrategy] | None = Field(default=None, min_length=1)
+    credentialLabel: NonEmptyString | None = None
+    credentialPlaceholder: NonEmptyString | None = None
+    credentialHelp: NonEmptyString | None = None
+    credentialSecretName: NonEmptyString | None = None
+    saveCredentialAsSecretByDefault: bool | None = None
+    apiKeyHeaderName: NonEmptyString | None = None
+    apiKeyOptional: bool | None = None
+    oauth: IntegrationOAuthConfig | None = None
+
+
+class IntegrationHttpConfig(CatalogModel):
+    apiBaseUrl: HttpsUrl
+    openApiUrl: HttpsUrl
+
+
+class IntegrationIdentityMapping(CatalogModel):
+    source: Literal["oauth_token_response", "access_token_claims", "identity_api"]
+    endpoint: HttpsUrl | None = None
+    externalPrincipalIdPath: IdentityPath
+    externalTenantIdPath: IdentityPath | None = None
+    externalResourceIdPath: IdentityPath | None = None
+    resourceNamePath: IdentityPath | None = None
+    resourceUrlPath: IdentityPath | None = None
+
+    @model_validator(mode="after")
+    def identity_api_requires_endpoint(self) -> IntegrationIdentityMapping:
+        if self.source == "identity_api" and not self.endpoint:
+            raise ValueError("identity_api mappings require an endpoint.")
+        if self.source != "identity_api" and self.endpoint:
+            raise ValueError("Only identity_api mappings may define an endpoint.")
+        return self
+
+
+class IntegrationResourceDiscovery(CatalogModel):
+    endpoint: HttpsUrl
+    itemsPath: IdentityPath | None = None
+    externalResourceIdPath: IdentityPath
+    resourceNamePath: IdentityPath | None = None
+    resourceUrlPath: IdentityPath | None = None
+
+
+class IntegrationConnectionModel(CatalogModel):
+    principalType: Literal["user", "bot", "service_account", "application"]
+    credentialScope: Literal["account", "tenant", "organization", "resource"]
+    resourceType: NonEmptyString
+    resourceCardinality: Literal["one", "many"]
+    selectionMode: Literal["automatic", "post_auth", "runtime"]
+    identityMapping: IntegrationIdentityMapping | None = None
+    resourceDiscovery: IntegrationResourceDiscovery | None = None
+
+    @model_validator(mode="after")
+    def post_auth_requires_resource_discovery(self) -> IntegrationConnectionModel:
+        if self.selectionMode == "post_auth" and not self.resourceDiscovery:
+            raise ValueError("post_auth connections require resourceDiscovery.")
+        return self
+
+
+class McpConnectionOption(CatalogModel):
+    id: NonEmptyString
+    provider: Literal["mcp"]
+    transport: IntegrationTransport
+    auth: IntegrationAuthConfig
+    connectionModel: IntegrationConnectionModel | None = None
+
+
+class HttpConnectionOption(CatalogModel):
+    id: NonEmptyString
+    provider: Literal["http"]
+    http: IntegrationHttpConfig
+    auth: IntegrationAuthConfig
+    connectionModel: IntegrationConnectionModel | None = None
+
+
+IntegrationConnectionOption = Annotated[
+    McpConnectionOption | HttpConnectionOption,
+    Field(discriminator="provider"),
+]
+
+
+class IntegrationCatalogEntry(CatalogModel):
+    id: NonEmptyString
+    name: NonEmptyString
+    description: NonEmptyString
+    categories: list[NonEmptyString] | None = Field(default=None, min_length=1)
+    appUrl: HttpsUrl | None = None
+    docsUrl: HttpsUrl
+    notes: NonEmptyString | None = None
+    iconBg: NonEmptyString | None = None
+    iconColor: NonEmptyString | None = None
+    logoUrl: HttpsUrl | None = None
+    keywords: list[NonEmptyString] | None = None
+    popularityRank: int | None = Field(default=None, ge=0)
+    installHint: NonEmptyString | None = None
+    connectionOptions: list[IntegrationConnectionOption] = Field(min_length=1)
+
+    @field_validator("categories", "keywords")
+    @classmethod
+    def list_values_are_unique(
+        cls, values: list[NonEmptyString] | None
+    ) -> list[NonEmptyString] | None:
+        if values is not None and len(values) != len(set(values)):
+            raise ValueError("Catalog list values must be unique.")
+        return values
+
+    @model_validator(mode="after")
+    def validate_auth_requirements(self) -> IntegrationCatalogEntry:
+        for option in self.connectionOptions:
+            if option.provider == "http" and option.auth.strategy == "api_key":
+                if not option.auth.apiKeyHeaderName:
+                    raise ValueError(
+                        "HTTP API-key connections require apiKeyHeaderName."
+                    )
+            if option.provider == "http" and option.auth.strategy == "oauth2":
+                oauth = option.auth.oauth
+                if not oauth or not oauth.authorizationUrl or not oauth.tokenUrl:
+                    raise ValueError(
+                        "HTTP OAuth connections require authorizationUrl and tokenUrl."
+                    )
+        return self
+
+
+class IntegrationCatalogSnapshot(CatalogModel):
+    integrations: list[IntegrationCatalogEntry]