@openhands/extensions 0.16.0 → 0.18.0

package/automations/catalog.schema.json

@@ -21,8 +21,17 @@
       "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
       "description": "Stable identifier. Must equal the name of the directory holding this manifest."
     },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of this template. Present only on entries whose direct setup sends provenance to the automation service; bump it when the prompt, form, or filter changes meaningfully."
+    },
     "name": { "type": "string", "minLength": 1 },
     "category": { "type": "string", "minLength": 1 },
+    "icon": {
+      "description": "The glyph the card shows, named from the same closed set the interface manifest's navigation uses. Absent means the host derives one from requires.integrations, which is right for an automation whose identity is the service it talks to and wrong for one whose identity is the work itself.",
+      "enum": ["layout-dashboard", "sparkles", "bot", "circle-alert", "activity", "timer"]
+    },
     "description": { "type": "string", "minLength": 1 },
     "requires": { "$ref": "#/$defs/requires" },
     "popularityRank": { "type": "integer", "minimum": 0 },
@@ -63,6 +72,10 @@
           "description": "direct only. What the automation is told to do. The rest of the create request restates the form, so it is not written here: the automation's name comes from this entry, the repository from the repo-picker field, and the trigger from the key and fields under form.triggers.",
           "$ref": "#/$defs/templateValue"
         },
+        "bundle": {
+          "description": "direct only, and the alternative to prompt. The script tarball this entry ships: the automation is deterministic machinery rather than judgement, so it runs as its own code and the host creates it through the raw create endpoint instead of a preset. The rest of the create request still restates the form, so it is not written here either.",
+          "$ref": "#/$defs/bundle"
+        },
         "filter": {
           "description": "direct only, and only for an event trigger. The expression deciding whether a delivered event belongs to this automation. It composes form values into a JMESPath expression, which is the one part of an event trigger that cannot be read off the form.",
           "$ref": "#/$defs/templateValue"
@@ -79,7 +92,10 @@
             "required": ["mode"]
           },
           "then": {
-            "required": ["prompt"]
+            "oneOf": [
+              { "required": ["prompt"], "not": { "required": ["bundle"] } },
+              { "required": ["bundle"], "not": { "required": ["prompt"] } }
+            ]
           }
         },
         {
@@ -91,6 +107,7 @@
             "required": ["message"],
             "allOf": [
               { "not": { "required": ["prompt"] } },
+              { "not": { "required": ["bundle"] } },
               { "not": { "required": ["filter"] } }
             ]
           }
@@ -108,6 +125,88 @@
             "required": ["form"]
           },
           "then": { "not": { "required": ["filter"] } }
+        },
+        {
+          "if": { "required": ["bundle"] },
+          "then": { "not": { "required": ["filter"] } }
+        }
+      ]
+    },
+    "bundle": {
+      "description": "What the host packs into a .tar.gz and uploads before creating the automation. It names files inside this repository and the command that runs them - never a host, a URL, or code to evaluate.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "entrypoint", "files", "config"],
+      "properties": {
+        "version": {
+          "description": "The version of this bundle, recorded as the created automation's template provenance. Bump it when the shipped files or the config shape change: it is what tells an already-enabled deployment that what it installed is no longer current. Not the package version, which moves for reasons that have nothing to do with this entry.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 50,
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+        },
+        "entrypoint": {
+          "description": "The command the automation service runs inside the extracted tarball, such as `python3 main.py`. No shell metacharacters: the service rejects them, and a bundle has no reason to need one.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "pattern": "^[A-Za-z0-9 ._/-]+$"
+        },
+        "setupScript": {
+          "description": "Path inside the tarball to a script run once before the entrypoint, such as `setup.sh`. Absent when the bundle needs no installation step, which is the case for a standard-library script.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$",
+          "not": { "pattern": "(^|/)\\.\\.?(/|$)" }
+        },
+        "timeout": {
+          "description": "Seconds a single run may take, when this entry needs more than the service default. A poll that fetches an archive per queued item needs longer than one that only calls an API.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400
+        },
+        "files": {
+          "description": "The tarball's contents, keyed by the path each file takes inside the archive and valued by where it lives in this repository. Stated rather than derived from the entry directory, so a script shipped by both a skill and the catalog has one copy rather than two.",
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 32,
+          "propertyNames": {
+            "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$",
+            "not": { "pattern": "(^|/)\\.\\.?(/|$)" },
+            "maxLength": 255
+          },
+          "additionalProperties": { "$ref": "#/$defs/bundleSource" }
+        },
+        "config": {
+          "description": "The config.json packed beside the entrypoint, rendered from the form. This is the bundle's analogue of prompt: the one thing that cannot be read off the form, because only the entry knows which key of its own script each field fills.",
+          "$ref": "#/$defs/bundleConfig"
+        }
+      }
+    },
+    "bundleSource": {
+      "description": "A file in this repository, as a repository-relative path under skills/ or automations/. No absolute path, no traversal, and no scheme, so a bundle cannot name anything outside the published package.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "pattern": "^(skills|automations)/[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$",
+      "not": { "pattern": "(^|/)\\.\\.?(/|$)" }
+    },
+    "bundleConfig": {
+      "description": "The JSON document written to config.json. Its string leaves may embed the same placeholders every other value uses. It carries no markup rule, because it is written to a file rather than rendered.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/bundleConfigValue" }
+    },
+    "bundleConfigValue": {
+      "description": "A config leaf: a templated string, a number, a boolean, null, or an array or object of the same.",
+      "anyOf": [
+        { "$ref": "#/$defs/templateValue" },
+        { "type": ["number", "boolean", "null"] },
+        { "type": "array", "items": { "$ref": "#/$defs/bundleConfigValue" } },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/bundleConfigValue" }
         }
       ]
     },
@@ -143,9 +242,8 @@
       "required": ["integrations"],
       "properties": {
         "integrations": {
-          "description": "Keyed by integration id, each of which must resolve to an integrations/catalog entry.",
+          "description": "Keyed by integration id, each of which must resolve to an integrations/catalog entry. Empty when the automation connects to nothing and needs no credential - a requirement worth stating, and the reason the key stays required rather than becoming optional.",
           "type": "object",
-          "minProperties": 1,
           "propertyNames": { "type": "string", "minLength": 1 },
           "additionalProperties": {
             "type": "object",
@@ -224,6 +322,10 @@
         "default": { "type": "string" },
         "required": { "type": "boolean" },
         "provider": { "enum": ["github", "gitlab", "bitbucket"] },
+        "multiple": {
+          "description": "repo-picker only. The field collects several repositories rather than one, and its value is a list. A whole-value placeholder resolves to that list, so a payload can state `\"repos\": \"{{form.repositories}}\"` and get an array.",
+          "const": true
+        },
         "options": {
           "type": "array",
           "minItems": 1,
@@ -259,6 +361,13 @@
           },
           "then": { "required": ["provider"] }
         },
+        {
+          "if": {
+            "properties": { "type": { "not": { "const": "repo-picker" } } },
+            "required": ["type"]
+          },
+          "then": { "not": { "required": ["multiple"] } }
+        },
         {
           "if": {
             "properties": { "type": { "not": { "const": "select" } } },

package/automations/index.d.ts

@@ -1,7 +1,24 @@
 export interface RecommendedAutomation {
   id: string;
+  /**
+   * Semantic version of this template. Present only on entries whose direct
+   * setup sends provenance to the automation service; bumped when the prompt,
+   * form, or filter changes meaningfully.
+   */
+  version?: string;
   name: string;
   category: string;
+  /**
+   * The glyph the card shows, from the closed set the interface manifest's
+   * navigation uses. Absent means the host derives one from the integrations.
+   */
+  icon?:
+    | "layout-dashboard"
+    | "sparkles"
+    | "bot"
+    | "circle-alert"
+    | "activity"
+    | "timer";
   description: string;
   requires: AutomationPrerequisites;
   popularityRank: number;
@@ -63,6 +80,11 @@ export interface AutomationFormField {
   default?: string;
   required: boolean;
   provider?: AutomationGitProvider;
+  /**
+   * repo-picker only. The field collects several repositories rather than one,
+   * and its value is a list. A whole-value placeholder resolves to that list.
+   */
+  multiple?: true;
   options?: AutomationFieldOption[];
   constraints?: AutomationFieldConstraints;
 }
@@ -78,7 +100,7 @@ export interface AutomationIntegrationRequirement {
 }
 
 export interface AutomationPrerequisites {
-  /** Keyed by integration catalog id. */
+  /** Keyed by integration catalog id. Empty when the automation needs nothing connected. */
   integrations: Record<string, AutomationIntegrationRequirement>;
   /** Deployment capabilities this automation cannot run without. */
   features?: string[];
@@ -96,12 +118,40 @@ export interface AutomationForm {
   args: AutomationFormFields;
 }
 
+/** A config.json leaf: templated string, number, boolean, null, or a nesting of those. */
+export type AutomationBundleConfigValue =
+  | string
+  | number
+  | boolean
+  | null
+  | AutomationBundleConfigValue[]
+  | { [key: string]: AutomationBundleConfigValue };
+
+/**
+ * The script tarball a direct entry may ship instead of a prompt, for an
+ * automation that is deterministic machinery rather than judgement.
+ */
+export interface AutomationBundle {
+  /** The command run inside the extracted tarball. */
+  entrypoint: string;
+  /** Script run once before the entrypoint. Absent when nothing to install. */
+  setupScript?: string;
+  /** Seconds a run may take, when the service default is not enough. */
+  timeout?: number;
+  /** Packed path -> the repository path the file is read from at build time. */
+  files: Record<string, string>;
+  /** Rendered from the form and packed as config.json beside the entrypoint. */
+  config: Record<string, AutomationBundleConfigValue>;
+}
+
 export interface AutomationSetup {
   version: "1.0";
   mode: AutomationSetupMode;
   form: AutomationForm;
   /** direct only. What the automation is told to do. */
   prompt?: string;
+  /** direct only, and the alternative to `prompt`. Exactly one is present. */
+  bundle?: AutomationBundle;
   /** direct only, event trigger only. Which delivered events belong to it. */
   filter?: string;
   /**
@@ -337,6 +387,10 @@ export interface AutomationInterfaceEndpoints {
   validate: string;
   createPrompt: string;
   createPlugin: string;
+  /** The raw create endpoint, which a bundle entry is created through. */
+  createBundle: string;
+  /** Where a bundle's tarball is uploaded before that create call. */
+  uploads: string;
 }
 
 export interface AutomationInterfaceManifest {
@@ -365,4 +419,15 @@ export function listAutomationCatalog(): RecommendedAutomation[];
 export function getAutomationCatalogEntry(
   id: string,
 ): RecommendedAutomation | undefined;
+/**
+ * Return the files a bundle entry ships, keyed by the path each takes inside
+ * the tarball, as an independent copy. Undefined for an entry with no bundle.
+ *
+ * The contents are inlined at build time from the repository paths
+ * `setup.bundle.files` names, because a host packing the tarball has the
+ * published package but not the repository.
+ */
+export function getAutomationBundleFiles(
+  id: string,
+): Record<string, string> | undefined;
 export default AUTOMATION_CATALOG;

package/automations/index.js

@@ -5,6 +5,7 @@
  * directory. `catalog-index.js` is generated from that directory so the JS
  * package can statically import each JSON file without an aggregate JSON asset.
  */
+import { AUTOMATION_BUNDLE_FILES } from "./bundle-index.js";
 import { AUTOMATION_CATALOG_ENTRIES } from "./catalog-index.js";
 import interfaceManifest from "./interface.json" with { type: "json" };
 
@@ -21,6 +22,19 @@ export const getAutomationCatalogEntry = (id) => {
 
 export const AUTOMATION_CATALOG = clone(AUTOMATIONS);
 
+/**
+ * The files a bundle entry ships, keyed by entry id and then by the path each
+ * file takes inside the tarball. Generated from the repository paths the
+ * entry's `setup.bundle.files` names, because a host packing the tarball has
+ * the package but not the repository.
+ *
+ * Absent for every entry that does not ship a bundle.
+ */
+export const getAutomationBundleFiles = (id) => {
+  const files = AUTOMATION_BUNDLE_FILES[id];
+  return files ? clone(files) : undefined;
+};
+
 /**
  * The production Automation interface manifest: the domain-level facts of the
  * interface, hand-authored in `automations/interface.json`.

package/automations/interface.json

@@ -144,11 +144,15 @@
     "capabilities": "/v1/capabilities",
     "validate": "/v1/validate",
     "createPrompt": "/v1/preset/prompt",
-    "createPlugin": "/v1/preset/plugin"
+    "createPlugin": "/v1/preset/plugin",
+    "createBundle": "/v1",
+    "uploads": "/v1/uploads"
   },
   "featuredAutomationIds": [
     "github-pr-reviewer",
-    "github-repo-monitor",
+    "github-agents-md-maintainer",
+    "news-digest",
+    "github-issue-to-pr",
     "slack-channel-monitor"
   ],
   "responderIntegrationIds": ["github", "slack"]

package/automations/interface.schema.json

@@ -178,7 +178,9 @@
         "capabilities",
         "validate",
         "createPrompt",
-        "createPlugin"
+        "createPlugin",
+        "createBundle",
+        "uploads"
       ],
       "properties": {
         "list": { "$ref": "#/$defs/plainEndpoint" },
@@ -190,7 +192,9 @@
         "capabilities": { "$ref": "#/$defs/plainEndpoint" },
         "validate": { "$ref": "#/$defs/plainEndpoint" },
         "createPrompt": { "$ref": "#/$defs/plainEndpoint" },
-        "createPlugin": { "$ref": "#/$defs/plainEndpoint" }
+        "createPlugin": { "$ref": "#/$defs/plainEndpoint" },
+        "createBundle": { "$ref": "#/$defs/plainEndpoint" },
+        "uploads": { "$ref": "#/$defs/plainEndpoint" }
       }
     },
     "featuredAutomationIds": {

package/index.d.ts

@@ -42,5 +42,5 @@ export type {
   AutomationInterfacePages,
   AutomationInterfaceRoutes,
 } from "./automations/index.js";
-export { SKILLS_CATALOG } from "./skills/index.js";
+export { SKILLS_CATALOG, DEFAULT_ENABLED_SKILL_NAMES } from "./skills/index.js";
 export type { SkillCatalogEntry } from "./skills/index.js";

package/index.js

@@ -1,3 +1,3 @@
 export { INTEGRATION_CATALOG } from "./integrations/index.js";
 export { AUTOMATION_CATALOG, AUTOMATION_INTERFACE } from "./automations/index.js";
-export { SKILLS_CATALOG } from "./skills/index.js";
+export { SKILLS_CATALOG, DEFAULT_ENABLED_SKILL_NAMES } from "./skills/index.js";

package/integrations/catalog/posthog.json

@@ -8,7 +8,7 @@
   ],
   "appUrl": "https://posthog.com",
   "docsUrl": "https://posthog.com/docs/model-context-protocol",
-  "notes": "Relevant for product analytics and experimentation workflows.",
+  "notes": "Uses PostHog's official hosted MCP server. OAuth is preferred; the bearer-token option remains for clients or deployments that require a personal API key. The OAuth URL defaults to read-only mode; remove readonly=true only when write access has been approved.",
   "popularityRank": 37,
   "iconBg": "#1D4AFF",
   "logoUrl": "https://cdn.simpleicons.org/posthog/FFFFFF",
@@ -18,8 +18,44 @@
     "product",
     "experiments"
   ],
-  "installHint": "Authenticate with a PostHog personal API key (PostHog → User settings → API keys, MCP Server preset) — sent as a Bearer token.",
+  "installHint": "Prefer OAuth. The default OAuth connection uses read-only MCP mode; edit the URL or use the bearer-key fallback only when a workflow needs approved write access. For API keys, create a PostHog personal API key with the MCP Server preset.",
   "connectionOptions": [
+    {
+      "id": "oauth",
+      "provider": "mcp",
+      "auth": {
+        "strategy": "oauth2",
+        "oauth": {
+          "authorizationUrl": "https://oauth.posthog.com/oauth/authorize/",
+          "tokenUrl": "https://oauth.posthog.com/oauth/token/",
+          "registrationUrl": "https://oauth.posthog.com/oauth/register/",
+          "scopes": [
+            "openid",
+            "profile",
+            "email",
+            "organization:read",
+            "project:read",
+            "dashboard:read",
+            "insight:read",
+            "query:read",
+            "event_definition:read"
+          ],
+          "pkce": true,
+          "clientAuthentication": "none",
+          "additionalAuthorizationParams": {
+            "resource": "https://mcp.posthog.com/mcp"
+          },
+          "additionalTokenParams": {
+            "resource": "https://mcp.posthog.com/mcp"
+          }
+        }
+      },
+      "transport": {
+        "kind": "shttp",
+        "url": "https://mcp.posthog.com/mcp?readonly=true",
+        "urlEditable": true
+      }
+    },
     {
       "id": "api-key",
       "provider": "mcp",
@@ -31,7 +67,9 @@
         "strategy": "bearer",
         "credentialLabel": "PostHog personal API key",
         "credentialPlaceholder": "Paste your PostHog personal API key",
-        "credentialHelp": "Create one under PostHog → User settings → API keys (MCP Server preset). Sent as Authorization: Bearer <token>."
+        "credentialHelp": "Create one under PostHog > User settings > API keys using the MCP Server preset. Sent as Authorization: Bearer <token>.",
+        "credentialSecretName": "POSTHOG_PERSONAL_API_KEY",
+        "saveCredentialAsSecretByDefault": true
       }
     }
   ]

package/integrations/catalog/sonarqube.json

@@ -0,0 +1,78 @@
+{
+  "id": "sonarqube",
+  "name": "SonarQube",
+  "description": "Inspect code quality and security findings, quality gates, and analyze code snippets from SonarQube Server or Cloud.",
+  "categories": [
+    "Engineering",
+    "Security"
+  ],
+  "appUrl": "https://www.sonarsource.com/products/sonarqube/mcp-server/",
+  "docsUrl": "https://github.com/SonarSource/sonarqube-mcp-server",
+  "notes": "Uses SonarSource's official SonarQube MCP Server, run locally as a Docker container. Provide a SonarQube user token. Set SONARQUBE_ORG for SonarQube Cloud, or SONARQUBE_URL for a self-managed SonarQube Server (or https://sonarqube.us for SonarQube Cloud US).",
+  "popularityRank": 43,
+  "installHint": "SONARQUBE_TOKEN is always required. For SonarQube Cloud, set your organization key in SONARQUBE_ORG. For a self-managed SonarQube Server, set SONARQUBE_URL to your server URL; for SonarQube Cloud US, set SONARQUBE_URL to https://sonarqube.us. Requires a container runtime such as Docker.",
+  "connectionOptions": [
+    {
+      "id": "api",
+      "provider": "mcp",
+      "transport": {
+        "kind": "stdio",
+        "serverName": "sonarqube",
+        "command": "docker",
+        "args": [
+          "run",
+          "--init",
+          "--pull=always",
+          "-i",
+          "--rm",
+          "-e",
+          "SONARQUBE_TOKEN",
+          "-e",
+          "SONARQUBE_ORG",
+          "-e",
+          "SONARQUBE_URL",
+          "sonarsource/sonarqube-mcp"
+        ],
+        "envFields": [
+          {
+            "key": "SONARQUBE_TOKEN",
+            "label": "SonarQube token",
+            "type": "password",
+            "required": true,
+            "helperText": "User token generated in your SonarQube Server or Cloud account settings.",
+            "helperLink": "https://docs.sonarsource.com/sonarqube-cloud/managing-your-account/managing-tokens/"
+          },
+          {
+            "key": "SONARQUBE_ORG",
+            "label": "Organization key (SonarQube Cloud)",
+            "type": "text",
+            "required": false,
+            "placeholder": "my-org",
+            "helperText": "Required for SonarQube Cloud. Your organization key, found in SonarQube Cloud."
+          },
+          {
+            "key": "SONARQUBE_URL",
+            "label": "Server URL (SonarQube Server)",
+            "type": "text",
+            "required": false,
+            "placeholder": "https://sonarqube.example.com",
+            "helperText": "Required for a self-managed SonarQube Server. For SonarQube Cloud US, use https://sonarqube.us."
+          }
+        ]
+      },
+      "auth": {
+        "strategy": "api_key"
+      }
+    }
+  ],
+  "iconBg": "#126ED3",
+  "logoUrl": "https://cdn.simpleicons.org/sonarqubeserver/FFFFFF",
+  "keywords": [
+    "code quality",
+    "static analysis",
+    "security",
+    "sast",
+    "quality gate",
+    "sonarcloud"
+  ]
+}