feat(integrations): declare HubSpot managed-connector migration + error hints

integrations/index.d.ts

@@ -114,6 +114,37 @@ export interface OAuthProviderRegistrationDefaults {
   toolDescription?: string;
   requestMethod?: string;
   requestPath?: string;
+  /**
+   * Provider-specific, HTTP-status-keyed error hints surfaced to the user when
+   * a managed connector call fails (e.g. HubSpot 401/403 reconnection advice).
+   * Keeps provider knowledge out of the hub's own source.
+   */
+  errorHints?: Record<number, string>;
+  /**
+   * Declarative managed-connector migration descriptor. Lets the integrations
+   * hub detect and normalize legacy stored connectors from catalog data instead
+   * of branching on a provider slug in its own source.
+   */
+  managedConnectorMigration?: ManagedConnectorMigration;
+}
+
+/**
+ * Describes how to migrate a legacy stored managed connector to the canonical
+ * shape declared on the provider's catalog entry.
+ */
+export interface ManagedConnectorMigration {
+  /** Canonical MCP/HTTP server URL the connector should resolve to. */
+  canonicalServerUrl: string;
+  /**
+   * Historical OAuth scope bundles. A stored connector whose scopes match one
+   * of these bundles is treated as legacy and forced to re-discover tools.
+   */
+  legacyScopeBundles: {
+    required: string[];
+    optional: string[];
+    union: string[];
+    unionWithoutOauth: string[];
+  };
 }
 
 export interface OAuthProviderCatalogOption {
@@ -165,5 +196,8 @@ export const hubspotMcpAuthorizationUrl: string;
 export const hubspotMcpTokenUrl: string;
 export const hubspotRequiredScopes: readonly string[];
 export const hubspotOptionalScopes: readonly string[];
+export const hubspotLegacyScopeBundle: readonly string[];
+export const hubspotLegacyScopeBundleWithoutOauth: readonly string[];
+export const hubspotManagedConnectorMigration: ManagedConnectorMigration;
 
 export default INTEGRATION_CATALOG;

integrations/index.js

@@ -42,6 +42,9 @@ import { listOAuthProviderCatalog } from "./oauth-provider-catalog.js";
 export { listOAuthProviderCatalog } from "./oauth-provider-catalog.js";
 export {
   getOAuthProviderRegistrationDefaults,
+  hubspotLegacyScopeBundle,
+  hubspotLegacyScopeBundleWithoutOauth,
+  hubspotManagedConnectorMigration,
   hubspotMcpAuthorizationUrl,
   hubspotMcpServerUrl,
   hubspotMcpTokenUrl,

integrations/oauth-provider-registration-defaults.js

@@ -87,6 +87,36 @@ export const hubspotOptionalScopes = [
   "crm.schemas.deals.read",
 ];
 
+/**
+ * Historical HubSpot OAuth scope bundles. Before the managed connector pointed
+ * at mcp.hubspot.com, already-stored HubSpot connectors carried these scopes.
+ * The integrations hub compares a stored connector's scopes against these
+ * bundles to detect legacy connectors that need re-discovery, so the values
+ * here must match the bundles the hub previously hardcoded exactly.
+ */
+export const hubspotLegacyScopeBundle = [
+  ...hubspotRequiredScopes,
+  ...hubspotOptionalScopes,
+];
+
+export const hubspotLegacyScopeBundleWithoutOauth =
+  hubspotLegacyScopeBundle.filter((scope) => scope !== "oauth");
+
+/**
+ * Declarative HubSpot managed-connector migration descriptor. Lets the
+ * integrations hub migrate/normalize legacy HubSpot connectors from catalog
+ * data instead of branching on the "hubspot" slug in its own source.
+ */
+export const hubspotManagedConnectorMigration = {
+  canonicalServerUrl: hubspotMcpServerUrl,
+  legacyScopeBundles: {
+    required: hubspotRequiredScopes,
+    optional: hubspotOptionalScopes,
+    union: hubspotLegacyScopeBundle,
+    unionWithoutOauth: hubspotLegacyScopeBundleWithoutOauth,
+  },
+};
+
 const registrationDefaults = {
   github: {
     apiBaseUrl: "https://api.github.com",
@@ -330,6 +360,13 @@ const registrationDefaults = {
     scopes: [],
     credentialHelp:
       "Use the client ID and secret from a HubSpot MCP auth app (Development → MCP Auth Apps). Standard HubSpot OAuth apps and private apps will not authenticate with mcp.hubspot.com.",
+    managedConnectorMigration: hubspotManagedConnectorMigration,
+    errorHints: {
+      401:
+        "HubSpot MCP requires a user-level OAuth token from a HubSpot MCP auth app. Reconnect HubSpot with an MCP auth app instead of a standard HubSpot OAuth app or private app.",
+      403:
+        "HubSpot MCP may need reauthorization to grant the current server tool scopes. Disconnect and reconnect HubSpot, then try discovery again.",
+    },
   },
   zendesk: {
     apiBaseUrl: "https://{subdomain}.zendesk.com/api/v2",

skills/openhands-sdk/SKILL.md

@@ -180,7 +180,6 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`40_acp_agent_example.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/40_acp_agent_example.py)
 - [`41_task_tool_set.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/41_task_tool_set.py)
 - [`42_file_based_subagents.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/42_file_based_subagents.py)
-- [`43_mixed_marketplace_skills`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/43_mixed_marketplace_skills)
 - [`44_model_switching_in_convo.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/44_model_switching_in_convo.py)
 - [`45_parallel_tool_execution.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/45_parallel_tool_execution.py)
 - [`46_agent_settings.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/46_agent_settings.py)
@@ -232,4 +231,5 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`01_loading_agentskills`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/01_loading_agentskills)
 - [`02_loading_plugins`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/02_loading_plugins)
 - [`03_managing_installed_skills`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/03_managing_installed_skills)
+- [`04_mixed_marketplace_skills`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills)
 

tests/test_catalogs.py

@@ -107,3 +107,61 @@ def test_node_package_exports_catalogs():
       if (!AUTOMATION_CATALOG.some((entry) => entry.id === 'github-pr-reviewer')) process.exit(1);
     """
     subprocess.run(["node", "--input-type=module", "-e", script], cwd=ROOT, check=True)
+
+
+def test_hubspot_managed_connector_migration_is_declared():
+    """The HubSpot catalog entry must declare the managed-connector migration
+    descriptor (canonicalServerUrl + the four legacy scope bundles) so the
+    integrations hub can migrate legacy HubSpot connectors from catalog data
+    instead of branching on the "hubspot" slug. The bundles must match the
+    historical hub constants exactly."""
+    script = r"""
+      import {
+        getOAuthProviderRegistrationDefaults,
+        hubspotMcpServerUrl,
+        hubspotRequiredScopes,
+        hubspotOptionalScopes,
+      } from './integrations/index.js';
+
+      const defaults = getOAuthProviderRegistrationDefaults('hubspot');
+      const migration = defaults?.managedConnectorMigration;
+      if (!migration) process.exit(1);
+
+      const expectedUnion = [...hubspotRequiredScopes, ...hubspotOptionalScopes];
+      const expectedUnionWithoutOauth = expectedUnion.filter((s) => s !== 'oauth');
+
+      const assertEqual = (actual, expected, label) => {
+        const a = JSON.stringify(actual);
+        const e = JSON.stringify(expected);
+        if (a !== e) {
+          console.error(`${label} mismatch:\n  actual:   ${a}\n  expected: ${e}`);
+          process.exit(1);
+        }
+      };
+
+      if (migration.canonicalServerUrl !== hubspotMcpServerUrl) process.exit(1);
+      if (migration.canonicalServerUrl !== 'https://mcp.hubspot.com') process.exit(1);
+
+      assertEqual(migration.legacyScopeBundles.required, hubspotRequiredScopes, 'required');
+      assertEqual(migration.legacyScopeBundles.optional, hubspotOptionalScopes, 'optional');
+      assertEqual(migration.legacyScopeBundles.union, expectedUnion, 'union');
+      assertEqual(
+        migration.legacyScopeBundles.unionWithoutOauth,
+        expectedUnionWithoutOauth,
+        'unionWithoutOauth',
+      );
+
+      // errorHints must remain declared alongside the migration metadata.
+      if (!defaults.errorHints?.[401] || !defaults.errorHints?.[403]) process.exit(1);
+      // Canonical OAuth config the hub reads from the same entry.
+      if (
+        defaults.provider !== 'mcp' ||
+        defaults.serverUrl !== hubspotMcpServerUrl ||
+        defaults.clientAuthentication !== 'body' ||
+        defaults.pkce !== true ||
+        defaults.scopes.length !== 0
+      ) {
+        process.exit(1);
+      }
+    """
+    subprocess.run(["node", "--input-type=module", "-e", script], cwd=ROOT, check=True)