openhands-extensions 0.11.0__tar.gz → 0.12.0__tar.gz

openhands_extensions-0.12.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.12.0"
+}

{openhands_extensions-0.11.0 → openhands_extensions-0.12.0}/AGENTS.md

@@ -90,7 +90,8 @@ When editing or adding skills in this repo, follow these rules (and add new skil
 - Keep formatting consistent across skills.
 - If you change a skill’s behavior or scope, update its `README.md` (if present) accordingly.
 - If you change top-level documentation, ensure links still resolve.
-- `integrations/catalog/*.json` is the single hand-authored source of truth consumed by `@openhands/extensions`; adding or editing an integration should require changing exactly one JSON file in that directory. Do not reintroduce `integrations/integration-catalog.json`, separate provider files, per-language catalog duplicates, or provider-specific runtime code. Run `npm run build:integrations` after catalog edits to regenerate `integrations/catalog-index.js`, which statically imports each individual JSON file for the JS package. The Python package includes the same individual JSON files via wheel data and reads them directly. Agent-canvas and integrations-hub import this package directly, so integration marketplace fixes belong here rather than in app-local constants. When upstream MCP projects move repos, verify both `docsUrl` and the connection option (`transport`, `command`/`args`, or URL), not just links. JS exposes `listIntegrationCatalog({ mcp, oauth })` / `getIntegrationCatalogEntry`; Python mirrors with `list_integration_catalog(mcp=, oauth=)` / `get_integration_catalog_entry`. The legacy provider-catalog compatibility layer and `managedConnectorMigration` / `legacyScopeBundles` / `canonicalServerUrl` / `errorHints` mechanisms were removed intentionally; providers declare only standard OAuth config as integration data.
+- `integrations/catalog/*.json` is the single hand-authored source of truth consumed by `@openhands/extensions`; adding or editing an integration should require changing exactly one JSON file in that directory. Do not reintroduce `integrations/integration-catalog.json`, separate provider files, per-language catalog duplicates, or provider-specific runtime code. Run `npm run build:integrations` after catalog edits to regenerate `integrations/catalog-index.js`, which statically imports each individual JSON file for the JS package. The Python package includes the same individual JSON files via wheel data and reads them directly. Agent-canvas and integrations-hub import this package directly, so integration marketplace fixes belong here rather than in app-local constants. When upstream MCP projects move repos, verify both `docsUrl` and the connection option (`transport`, `command`/`args`, or URL), not just links. JS exposes `listIntegrationCatalog({ mcp, oauth })` / `getIntegrationCatalogEntry`; Python mirrors with `list_integration_catalog_models(mcp=, oauth=)` / `get_integration_catalog_entry_model`, which return validated Pydantic models (the raw-dict accessors were deprecated in 0.10.0 and removed in 0.12.0). The legacy provider-catalog compatibility layer and `managedConnectorMigration` / `legacyScopeBundles` / `canonicalServerUrl` / `errorHints` mechanisms were removed intentionally; providers declare only standard OAuth config as integration data.
+- `automations/catalog/<id>/` follows the same rule, as a directory per automation so an automation can ship the scripts it uploads to the automations service alongside its metadata. `manifest.json` is the single hand-authored file, carrying both the card metadata and an optional nested `setup` block (the extension-owned configuration experience). Every entry is validated against `automations/catalog.schema.json`. Run `npm run build:automations` after catalog edits to regenerate `automations/catalog-index.js`. JS exposes `listAutomationCatalog()` / `getAutomationCatalogEntry(id)` alongside `AUTOMATION_CATALOG`. The governing rule is that a manifest states only what varies between automations, and states it once; anything derivable is absent and the host generates it. Derived, so never written in a manifest: the command that launches the card (read from the `triggers:` frontmatter of the skill named by `skill`, which defaults to `id` and is stated only where the two differ - editing an automation must never require editing a skill), the setup route (`/automations/new/<id>`), the trigger kinds a deployment must support (the keys of `setup.form.triggers`), schedule limits and timezone lists (the `cron` and `timezone` field types), the preflight call, the create request's `name`/`repos`/`trigger` (rebuilt from the entry name, the repo-picker field and the keys and fields under `setup.form.triggers`, where a field is named after the property it fills), the mapping from a rejected payload path back to the input at fault, the review screen, the create endpoint, the post-success navigation, and the analytics stages. `requires.integrations` is keyed by integration id and lives on the entry, not in `setup`, because a card lists its integrations whether or not it ships a setup flow; there is no key anywhere for a credential, because the credential comes with the connection. `setup.form` splits inputs into `triggers` (keyed by trigger kind - what decides when the automation runs) and `args` (everything else), both keyed by field name. `setup` declares a `prompt` (plus a `filter` for an event trigger) when `mode` is `direct`, and a `message` when it is `assisted`. Contract fixtures are test vectors, not catalog data: they live in `tests/fixtures/automations/`, are optional per automation, and are reachable only through the `@openhands/extensions/testing/automations/*.json` subpath - never from the runtime entry point.
 - For Python test runs, prefer `uv sync --group test` followed by `uv run pytest -q`; the full suite depends on `openhands-sdk`, which is not available in the base environment.
 - Agent-driven plugins (for example `plugins/pr-review` and `plugins/release-notes`) use `uv run --with openhands-sdk --with openhands-tools ...` and require an `LLM_API_KEY` in addition to `GITHUB_TOKEN`.
 - For OpenHands Cloud API guidance, automations, and CLI integration, use `plugins/openhands`. It is the canonical unified OpenHands plugin covering the V1 Cloud API, Automations API, and CLI. The individual skills (`skills/openhands-api`, `skills/openhands-automation`) are also available standalone.

{openhands_extensions-0.11.0 → openhands_extensions-0.12.0}/MIGRATION.md

@@ -1,5 +1,36 @@
 # Migration Guide
 
+## Python raw-dict catalog accessors removed in 0.12.0
+
+`openhands_extensions.list_integration_catalog` and
+`openhands_extensions.get_integration_catalog_entry` were deprecated in 0.10.0
+with `removed_in="0.12.0"` and are removed in 0.12.0, per the two-minor-release
+runway enforced by `scripts/check_deprecations.py`. Replace them with the typed
+accessors, which validate every entry against `IntegrationCatalogEntry`:
+
+```diff
+-from openhands_extensions import get_integration_catalog_entry, list_integration_catalog
++from openhands_extensions import (
++    get_integration_catalog_entry_model,
++    list_integration_catalog_models,
++)
+
+-entries = list_integration_catalog(oauth=True)
+-entry = get_integration_catalog_entry("github")
+-entry_id = entry["id"]
++entries = list_integration_catalog_models(oauth=True)
++entry = get_integration_catalog_entry_model("github")
++entry_id = entry.id
+```
+
+The filter arguments (`mcp=`, `oauth=`) and the `None` returned for an unknown
+id are unchanged; only the element type differs. Callers that genuinely need
+JSON-compatible dictionaries can call `model.model_dump(exclude_none=True)`,
+which reproduces the hand-authored entry exactly, or read the unchanged
+`INTEGRATION_CATALOG_SNAPSHOT`. The JavaScript API is unaffected:
+`listIntegrationCatalog` / `getIntegrationCatalogEntry` keep returning plain
+objects.
+
 ## MCP catalog to integration catalog
 
 This package version is still `0.0.0`, and the MCP catalog was an experimental

{openhands_extensions-0.11.0 → openhands_extensions-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-extensions
-Version: 0.11.0
+Version: 0.12.0
 Summary: OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)
 License-File: LICENSE
 Requires-Python: >=3.12

{openhands_extensions-0.11.0 → openhands_extensions-0.12.0}/README.md

@@ -61,21 +61,23 @@ See [`integrations/README.md`](integrations/README.md), [`automations/README.md`
 
 The integration catalog is also published as a Python package (`openhands-extensions`) so Python services read the same catalog data as JS consumers. The single source of truth is the hand-authored JSON directory `integrations/catalog/<id>.json`; there is no separate provider file and no aggregate catalog JSON to maintain. Both the JS package (`@openhands/extensions/integrations`) and the Python package read those same per-integration JSON files and expose parallel read functions.
 
-Each catalog entry can carry oauth and/or mcp/http `connectionOptions`. `supportsOauth` / `supportsMcp` flags are derived at runtime. Use `listIntegrationCatalog({ mcp, oauth })` (JS) or `list_integration_catalog(mcp=, oauth=)` (Python) to filter by connector type - for example only integrations that support an oauth connector.
+Each catalog entry can carry oauth and/or mcp/http `connectionOptions`. `supportsOauth` / `supportsMcp` flags are derived at runtime. Use `listIntegrationCatalog({ mcp, oauth })` (JS) or `list_integration_catalog_models(mcp=, oauth=)` (Python) to filter by connector type - for example only integrations that support an oauth connector.
 
 ```python
 from openhands_extensions import (
-    list_integration_catalog,                        # listIntegrationCatalog({ mcp, oauth })
-    get_integration_catalog_entry,                   # getIntegrationCatalogEntry(id)
+    list_integration_catalog_models,                 # listIntegrationCatalog({ mcp, oauth })
+    get_integration_catalog_entry_model,             # getIntegrationCatalogEntry(id)
     INTEGRATION_CATALOG_SNAPSHOT,                    # { integrations }
 )
 
-all_integrations = list_integration_catalog()
-oauth_integrations = list_integration_catalog(oauth=True)      # only entries with an oauth connector
-mcp_integrations = list_integration_catalog(mcp=True)          # only entries with an mcp connector
-sample = get_integration_catalog_entry(all_integrations[0]["id"])
+all_integrations = list_integration_catalog_models()
+oauth_integrations = list_integration_catalog_models(oauth=True)  # only entries with an oauth connector
+mcp_integrations = list_integration_catalog_models(mcp=True)      # only entries with an mcp connector
+sample = get_integration_catalog_entry_model(all_integrations[0].id)
 ```
 
+The Python functions return validated `IntegrationCatalogEntry` models. The raw-dictionary accessors `list_integration_catalog` / `get_integration_catalog_entry` were deprecated in 0.10.0 and removed in 0.12.0; see [`MIGRATION.md`](MIGRATION.md).
+
 Install from git (the hub backend consumes it this way):
 
 ```bash

openhands_extensions-0.12.0/automations/README.md

@@ -0,0 +1,258 @@
+# Automations
+
+`catalog/<id>/` is one automation. Its `manifest.json` is the single hand-authored source of truth: the
+card metadata Agent Canvas renders today and, optionally, a nested `setup` block, the extension-owned
+configuration experience for that automation. Anything else an automation ships, such as a script that is
+uploaded to the automations service as a `.tar.gz`, belongs in the same directory.
+
+```
+catalog/<id>/manifest.json   one automation per directory - card metadata plus an optional `setup` block
+catalog.schema.json          the contract, JSON Schema draft 2020-12
+catalog-index.js             generated from catalog/ - do not edit by hand
+index.js                     the stable API for Node.js and bundlers
+index.d.ts                   the public TypeScript shape
+```
+
+Adding or changing an automation should require changing exactly one JSON file. Run
+`npm run build:automations` afterwards to regenerate `catalog-index.js`, which statically imports each
+individual manifest for the JS package.
+
+```js
+import {
+  AUTOMATION_CATALOG,
+  listAutomationCatalog,
+  getAutomationCatalogEntry,
+} from "@openhands/extensions/automations";
+```
+
+All three return independent copies.
+
+## The governing rule
+
+**A manifest states only what varies between automations, and states each of those things once.**
+Anything that can be worked out from another field is absent, and the host generates it. That is what keeps
+two records of the same fact from drifting apart, and it is why the file is as short as it is.
+
+| Not declared | Where it comes from |
+| --- | --- |
+| The command the card launches | The `triggers:` frontmatter of the skill named by `skill`, which the skills catalog already exposes |
+| The setup route | `/automations/new/<id>` |
+| The integrations the card lists | `requires.integrations`, which every entry carries |
+| The capabilities endpoint | The host queries it for every automation |
+| The trigger kinds a deployment must support | The keys of `setup.form.triggers` |
+| Schedule limits and the timezone list | The `cron` and `timezone` field types |
+| Local validation rules | The `required` flag and `constraints` on each field |
+| The preflight call | `POST /v1/validate` with the entry id, the create endpoint, and the rendered payload |
+| The created automation's name | The entry's `name`, plus the repository that was picked |
+| `repos` in the create request | The repo-picker field, its declared `provider`, and a field named `ref` if there is one |
+| `trigger` in the create request | The key under `form.triggers`, and the fields under it named after trigger properties |
+| Which input a rejected payload path belongs to | Rebuilding that body with each field standing in for its own value |
+| The review screen | The fields and their labels |
+| The create endpoint | `POST /v1/preset/prompt` |
+| Where a success navigates | The created automation, or the started conversation |
+| The analytics stages | The same stages for every automation |
+
+`tests/test_automation_setup.py` derives the preflight body and the payload-path mapping from the entry and
+checks them against the recorded fixtures, so these deletions stay honest rather than becoming assumptions.
+
+## What an entry carries
+
+```jsonc
+{
+  "id": "github-pr-reviewer",
+  "name": "GitHub Code Review Agent",
+  "category": "Code review",
+  "description": "...",
+  "requires": {
+    "integrations": { "github": { "message": "Used to read pull requests and post review comments." } },
+    "features": ["repoClone", "presetPrompt"]
+  },
+  "popularityRank": 100,
+  "estimatedSetupMinutes": 4,
+  "exampleImplementation": "...",
+  "setup": {
+    "version": "1.0",
+    "mode": "direct",
+    "form": {
+      "triggers": { "cron": { "schedule": {...}, "timezone": {...} } },
+      "args": { "repository": {...}, "triggerLabel": {...}, "reviewTone": {...} }
+    },
+    "prompt": "Review pull requests labeled '{{form.triggerLabel}}' in {{form.repository}}. ..."
+  }
+}
+```
+
+`requires` sits on the entry, not inside `setup`, because a card lists the integrations it needs whether or
+not it ships a setup flow. Integrations are keyed by id, and each id must match an entry in
+`integrations/catalog/*.json`. Every one carries a `message` saying what it is for, so an integration is
+never listed with nothing attached. `required` defaults to true; state `false` only for an integration
+setup can proceed without.
+
+`skill` names the `skills/` directory that builds this automation today, and defaults to `id`, so only the
+three entries whose names differ from their skill state it. The command that launches that skill is **not**
+repeated here: it lives once, in the skill's own `triggers:` frontmatter, and the skills catalog exposes it.
+That way a skill can rename its trigger without leaving a stale copy behind in this catalog.
+
+`setup` is optional. Three of eight entries carry one today. It never repeats `id`, `name`, `category`, or
+`description`. `setup.version` selects how the block is interpreted; a future format ships a new constant.
+
+### Triggers and args
+
+`form` separates the two things a user is configuring, and both are keyed by field name:
+
+- **`form.triggers`** decides *when* the automation runs, keyed by trigger kind (`cron` or `event`).
+  `github-pr-reviewer` asks for a schedule and a timezone; `github-repo-monitor` asks which GitHub event to
+  answer and which phrase to match.
+- **`form.args`** is everything else: the arguments to the automation itself, such as the repository to
+  clone and the tone of the review.
+
+An assisted entry declares no triggers, because the trigger is settled during the conversation.
+
+### What the form produces
+
+- **`mode: "direct"`** declares a `prompt`: what the automation is told to do. The rest of the create
+  request restates the form, so it is not written out. An event trigger also declares a `filter`, because
+  composing form values into a JMESPath expression is the one part of an event trigger that cannot be read
+  off the form.
+- **`mode: "assisted"`** declares a `message`: setup context handed to an agent conversation that finishes
+  the job. The command that opens that conversation comes from the skill, so it is not repeated here.
+
+A form field is named after the property it fills. `schedule` and `timezone` under `triggers.cron` become
+`trigger.schedule` and `trigger.timezone`; `on` under `triggers.event` becomes `trigger.on`; a field named
+`ref` becomes `repos[].ref`. Any other field under a trigger kind, such as a phrase to match, is an input
+to `filter` rather than a trigger property.
+
+### Format constraints
+
+A setup block is data that instructs another repo to render copy and build a request, so the schema is the
+trust boundary. It enforces:
+
+- **No code.** There is no key that accepts JavaScript, and no free-form value that is executed.
+- **No markup.** Every user-visible copy field rejects HTML. Payload strings do not, because they are never
+  rendered - that is what lets an event filter carry expression syntax.
+- **No arbitrary requests.** An entry supplies a request *body*. It does not name a host, a path, or a
+  method, so it cannot express a request to anywhere the host did not choose.
+- **No credentials.** There is no key for a credential at all. An automation names the integrations it
+  needs; the credential comes from the connection the user already made.
+- **No supplied regex.** `constraints.format` names a host-implemented check from a closed set, so an entry
+  cannot hand the host a pathological pattern.
+
+Placeholders are namespaced and the schema rejects any other namespace: `{{form.*}}` for what the user
+entered and `{{automation.*}}` for the entry itself. There is deliberately no secrets namespace.
+
+### The three archetypes
+
+| Entry | Archetype | Trigger | Produces |
+| --- | --- | --- | --- |
+| `github-pr-reviewer` | Direct scheduled | `cron` | a create payload |
+| `github-repo-monitor` | Direct GitHub-event | `event` on `github` with a JMESPath filter | a create payload |
+| `incident-retrospective-drafter` | Assisted conversation | decided during the conversation | a seed message |
+
+The assisted archetype has no payload and no preflight, because at the end of its flow no automation exists
+yet. The agent creates it during the conversation, and the service validates it there. That is the defining
+property of the archetype, not an omission.
+
+### Two generations in one entry
+
+`skill` and `exampleImplementation` describe the **current** path: Agent Canvas launches that skill, and the
+agent builds the automation. `setup` describes the **declarative** path that replaces it.
+
+They can differ in more than wording. `github-repo-monitor`'s skill polls GitHub on a cron and states that
+a webhook variant is out of scope, while its `setup` block creates the webhook form the service already
+supports. Both statements are accurate about their own generation. Retiring the skill path for entries that
+ship a `setup` block belongs to whoever promotes this to production.
+
+## Contract fixtures
+
+The fixtures are independent test vectors, not part of the runtime catalog. They live in
+`tests/fixtures/automations/*.json` and are not required for every automation. Downstream contract tests
+reach them through an explicit testing subpath:
+
+```js
+import scenarios from "@openhands/extensions/testing/automations/github-pr-reviewer.json";
+```
+
+`tests/fixtures/automations/<automation-id>.json` pairs the values a user types with the exact request that
+must result. That pairing is the contract: form shape and API shape genuinely differ, the create endpoint
+is declared `extra="forbid"`, and a mapping mistake is a 422 discovered only at creation time.
+
+Each scenario carries whichever blocks apply: `formValues`, `integrationState`, `localValidation`,
+`preflight`, `create`, `conversation`, `expectedFieldErrors`, `expectedPrerequisiteOutcome`.
+`capabilities.json` holds three deployment shapes so the unsupported paths have coverage too.
+
+Beyond the derivation checks, every request body here has been verified against the live Pydantic models in
+`OpenHands/automation`:
+
+- each `201` body validates against `CreatePromptAutomationRequest`
+- each `422` body reproduces the error detail the service actually returns, including the `loc` path
+- each response `trigger` matches what `model_dump()` stores, so defaults such as `timezone` are present
+- each event filter compiles, because `EventTrigger` validates it on construction
+
+Two findings came out of that check and are baked into the entries:
+
+- **`repos[].provider` is required** for short `owner/repo` URLs. Without it the create request is a hard
+  422, not a silently dropped field. Recorded as the `short-repo-url-without-provider-is-rejected` scenario.
+- **A trigger phrase containing an apostrophe breaks the event filter**, because it is interpolated into a
+  JMESPath string literal. Hence `constraints.format: "safeExpressionLiteral"` on that field, and the
+  `quote-in-trigger-phrase-blocked-locally` scenario.
+
+## Endpoints the host calls
+
+| Endpoint | Status |
+| --- | --- |
+| `POST /v1/preset/prompt` | Exists |
+| `GET /v1/capabilities` | Does not exist. Defining it is OpenHands/automation#262 |
+| `POST /v1/validate` | Does not exist. Defining it is OpenHands/automation#262 |
+
+None of these appear in a manifest. They are the host's, which is why settling on different paths changes
+no catalog entry at all.
+
+## Deviations from the project reference document
+
+The shape sketched in the project reference document is marked as a proposal, and hands several open
+questions to this work. What changed and why:
+
+| Proposed | Decision |
+| --- | --- |
+| A separate manifest file per automation | Merged into the catalog entry as `setup`, so there is one hand-authored record per automation and nothing to keep in sync. |
+| `prompt` | Removed. It duplicated the slash command already declared in the skill's `triggers:` frontmatter. The entry names the `skill` instead, defaulting to `id`, and the command is looked up from the skills catalog. |
+| `requiredIntegrationIds` | Removed. It duplicated the integration ids in `requires`, which now sits on the entry so every automation carries them once. |
+| `routes` | Removed. The only route is `/automations/new/<id>`. |
+| `capabilities` | Removed. The discovery call is the same for every automation, and the block's only entry-specific content was a feature list, now `requires.features`. |
+| `capabilities.bindings` | Removed. The `cron` and `timezone` field types tell the host to resolve the deployment's limits on their own. |
+| `requires.secrets` | Removed. An automation that needs GitHub declares the GitHub integration; the credential comes with the connection rather than being asked for twice. |
+| `requires.onUnmet` / `onWarn` | Removed. What to do about an unmet requirement follows from `required`, and the copy follows from the integration's `message`. |
+| `enforcement: "block" \| "warn"` | Replaced by `required`, which defaults to true and is stated only when false. |
+| `reason` / `help` / `message` | Unified on `message`. Three words for one thing. |
+| `form.fields` | Split into `form.triggers` and `form.args`, and both keyed by field name so the name is the key rather than a repeated property. |
+| `validation` | Removed. The preflight call has the same shape for every automation, and the payload-path mapping is recovered by walking `payload`. |
+| `review` | Removed. The confirmation screen is the declared fields and their labels. |
+| `submit` | Reduced to the parts that vary: `prompt` and, for an event trigger, `filter` for direct; `message` for assisted. The action, endpoint, success navigation, and error handling are identical everywhere. |
+| `submit.payload` | Removed. `name`, `repos` and `trigger` all restated the form, so they are rebuilt from it. What is left is the prompt and the event filter. |
+| `analytics` | Removed. The same stages fire for every automation, so they belong in shared host code. |
+| `workflow.steps` | Removed. It restated which keys were present, creating a second source of truth that could contradict the file. |
+| `form.intent: "seed"` | Removed. Derivable from `setup.mode: "assisted"`. |
+| `triggerKindsAnyOf` | Removed. The keys of `form.triggers` are the trigger kinds. |
+| `{{form.filledCount}}` | Removed. It overloaded the `form` namespace with a computed value that names no field. |
+| `submit.message` | Kept as `setup.message`, capped at 2000 characters, so seed messages cannot grow back into the giant runtime prompts that recommended automation cards were already fixed to stop sending. |
+
+## Open questions
+
+Recorded rather than resolved, because they need an owner outside this contract:
+
+- **Localization.** Entries carry literal copy, because the ownership split assigns copy to this repo.
+  Agent Canvas ships 15 languages. Shipping i18n keys instead would move the copy back into Canvas, so the
+  gap is real and unsolved.
+- **Distribution.** Agent Canvas pins `@openhands/extensions`, so changing an entry still needs a version
+  bump and a dependency update. Delivering "change automation UI without a Canvas release" needs runtime
+  loading.
+- **Integration credentials at runtime.** Dropping `requires.secrets` assumes a created automation can use
+  the credential behind a connected integration. Whether the automations service receives it, and how, is
+  not settled here.
+- **Grouped review rows.** The review screen is now one row per field. The hand-written summaries grouped
+  related fields onto one line, which reads better; if that matters, it is a host concern, not an entry's.
+- **Assisted-setup completion.** The assisted flow ends at a conversation, so the host cannot emit a
+  completion event. Until something reports back, the ratio of direct to assisted setup is not measurable.
+- **Edit and delete routes.** Only the `new` route is modelled here.
+- **Types from the schema.** `index.d.ts` is hand-written and mirrors `catalog.schema.json`. Generating it
+  would remove that second source of truth.

openhands_extensions-0.12.0/automations/catalog/github-pr-reviewer/manifest.json

@@ -0,0 +1,82 @@
+{
+  "id": "github-pr-reviewer",
+  "name": "GitHub Code Review Agent",
+  "category": "Code review",
+  "description": "Watch for a configurable label on GitHub pull requests, inspect full PR and repository context, and post an AI review comment once per label event.",
+  "requires": {
+    "integrations": {
+      "github": {
+        "message": "Used to read pull requests and post review comments."
+      }
+    },
+    "features": [
+      "repoClone",
+      "presetPrompt"
+    ]
+  },
+  "popularityRank": 100,
+  "estimatedSetupMinutes": 4,
+  "exampleImplementation": "Trigger: cron polling for open GitHub PRs with a configured label such as openhands-review\nRequired secret: GITHUB_PERSONAL_ACCESS_TOKEN\n\n1. Read repository, trigger label, review tone, and polling schedule from setup.\n2. List open PRs and find the latest matching GitHub labeled issue event for each labeled PR.\n3. Deduplicate on the label event ID so every label application queues exactly one review.\n4. Start an OpenHands conversation that clones the repo, checks out the exact PR head SHA, and inspects PR discussion, review comments, changed files, diff, and surrounding code.\n5. Post an acknowledgement with the conversation link, then post the final AI review comment only if the PR is still open and the head SHA has not changed.",
+  "setup": {
+    "version": "1.0",
+    "mode": "direct",
+    "form": {
+      "triggers": {
+        "cron": {
+          "schedule": {
+            "type": "cron",
+            "label": "Check frequency",
+            "help": "How often to look for newly labelled pull requests.",
+            "default": "*/15 * * * *",
+            "required": true
+          },
+          "timezone": {
+            "type": "timezone",
+            "label": "Timezone",
+            "help": "Timezone the schedule is interpreted in.",
+            "default": "UTC",
+            "required": true
+          }
+        }
+      },
+      "args": {
+        "repository": {
+          "type": "repo-picker",
+          "label": "Repository",
+          "help": "The repository whose pull requests will be reviewed.",
+          "provider": "github",
+          "required": true
+        },
+        "triggerLabel": {
+          "type": "text",
+          "label": "Trigger label",
+          "help": "Only pull requests carrying this label are reviewed.",
+          "default": "openhands-review",
+          "required": true,
+          "constraints": {
+            "minLength": 1,
+            "maxLength": 50
+          }
+        },
+        "reviewTone": {
+          "type": "select",
+          "label": "Review tone",
+          "help": "How detailed the review comments should be.",
+          "default": "concise",
+          "required": true,
+          "options": [
+            {
+              "value": "concise",
+              "label": "Concise"
+            },
+            {
+              "value": "thorough",
+              "label": "Thorough"
+            }
+          ]
+        }
+      }
+    },
+    "prompt": "Review pull requests labeled '{{form.triggerLabel}}' in {{form.repository}}. Review tone: {{form.reviewTone}}."
+  }
+}

openhands_extensions-0.12.0/automations/catalog/github-repo-monitor/manifest.json

@@ -0,0 +1,82 @@
+{
+  "id": "github-repo-monitor",
+  "name": "GitHub repository monitor",
+  "category": "Developer tools",
+  "description": "Watch a repository for @OpenHands mentions in issues and PR comments, start a conversation, and post the agent's reply back to GitHub.",
+  "requires": {
+    "integrations": {
+      "github": {
+        "message": "Used to read issue and pull request comments and post replies."
+      }
+    },
+    "features": [
+      "repoClone",
+      "presetPrompt",
+      "webhookDelivery"
+    ]
+  },
+  "popularityRank": 98,
+  "estimatedSetupMinutes": 5,
+  "exampleImplementation": "Trigger: cron, every minute (configurable)\nRequired secret: GITHUB_PERSONAL_ACCESS_TOKEN\n\n1. Poll GitHub for new issue and PR comments since the last run.\n2. Match comments containing the trigger phrase (case-insensitive, default: @OpenHands).\n3. Post an acknowledgment comment with a link to the new OpenHands conversation.\n4. Forward follow-up replies in the same thread to the running conversation.\n5. Post the agent's final response back to GitHub when the conversation completes.",
+  "setup": {
+    "version": "1.0",
+    "mode": "direct",
+    "form": {
+      "triggers": {
+        "event": {
+          "on": {
+            "type": "select",
+            "label": "Respond to",
+            "help": "Which GitHub comment event starts a conversation.",
+            "default": "issue_comment.created",
+            "required": true,
+            "options": [
+              {
+                "value": "issue_comment.created",
+                "label": "Comments on issues and pull requests"
+              },
+              {
+                "value": "pull_request_review_comment.created",
+                "label": "Pull request review comments only"
+              }
+            ]
+          },
+          "triggerPhrase": {
+            "type": "text",
+            "label": "Trigger phrase",
+            "help": "Only comments containing this phrase start a conversation. Matched case-insensitively. Quotes and backslashes are not allowed, because the phrase becomes part of the event filter expression.",
+            "default": "@openhands",
+            "required": true,
+            "constraints": {
+              "minLength": 2,
+              "maxLength": 50,
+              "format": "safeExpressionLiteral"
+            }
+          }
+        }
+      },
+      "args": {
+        "repository": {
+          "type": "repo-picker",
+          "label": "Repository",
+          "help": "The repository or repositories to watch for mentions.",
+          "provider": "github",
+          "required": true
+        },
+        "ref": {
+          "type": "text",
+          "label": "Base branch",
+          "help": "Branch checked out when the agent responds.",
+          "default": "main",
+          "required": true,
+          "constraints": {
+            "minLength": 1,
+            "maxLength": 255
+          }
+        }
+      }
+    },
+    "prompt": "A comment in {{form.repository}} mentions '{{form.triggerPhrase}}'. Read the surrounding issue or pull request context from the event payload, then post a helpful reply as a comment on the same thread.",
+    "filter": "icontains(comment.body, '{{form.triggerPhrase}}') && glob(repository.full_name, '{{form.repository}}')"
+  }
+}

openhands_extensions-0.12.0/automations/catalog/incident-retrospective-drafter/manifest.json

@@ -0,0 +1,100 @@
+{
+  "id": "incident-retrospective-drafter",
+  "name": "Incident retrospective drafter",
+  "category": "Reliability",
+  "description": "Collect incident chatter and issue updates, then draft a timeline and follow-up checklist.",
+  "requires": {
+    "integrations": {
+      "slack": {
+        "message": "Reads incident discussion and timestamps."
+      },
+      "linear": {
+        "message": "Reads follow-up tickets, owners, and status."
+      },
+      "notion": {
+        "message": "Publishes the drafted retrospective. Can be connected later during setup.",
+        "required": false
+      }
+    },
+    "features": [
+      "mcpTools",
+      "conversationDispatch"
+    ]
+  },
+  "popularityRank": 78,
+  "estimatedSetupMinutes": 8,
+  "skill": "incident-retrospective",
+  "exampleImplementation": "Trigger: manual, cron, or incident label added\nRequired MCPs: Slack, Linear, Notion\n\n1. Gather incident messages, timestamps, and linked issue references.\n2. Pull Linear follow-up tickets, owners, and status.\n3. TODO: define the incident identifier format and approved Notion template.\n4. Build a timeline, impact summary, root-cause hypotheses, and action items.\n5. Publish a draft retrospective and notify the incident owner.",
+  "setup": {
+    "version": "1.0",
+    "mode": "assisted",
+    "form": {
+      "note": "These answers start the conversation. Anything left blank is something the agent will ask about.",
+      "args": {
+        "incidentChannel": {
+          "type": "text",
+          "label": "Incident channel",
+          "help": "The Slack channel where incidents are discussed.",
+          "placeholder": "#incidents",
+          "required": false,
+          "constraints": {
+            "maxLength": 100
+          }
+        },
+        "linearTeam": {
+          "type": "text",
+          "label": "Linear team",
+          "help": "The team whose follow-up tickets belong in the retrospective.",
+          "required": false,
+          "constraints": {
+            "maxLength": 100
+          }
+        },
+        "notionDestination": {
+          "type": "text",
+          "label": "Notion destination",
+          "help": "Page or database where drafts should be published. Leave blank to decide during setup.",
+          "required": false,
+          "constraints": {
+            "maxLength": 200
+          }
+        },
+        "triggerPreference": {
+          "type": "select",
+          "label": "How should it run?",
+          "help": "A starting preference only. The agent confirms the exact trigger before creating anything.",
+          "default": "undecided",
+          "required": false,
+          "options": [
+            {
+              "value": "undecided",
+              "label": "Let the agent recommend one"
+            },
+            {
+              "value": "scheduled",
+              "label": "On a schedule"
+            },
+            {
+              "value": "onIncidentLabel",
+              "label": "When an incident is labelled"
+            },
+            {
+              "value": "manual",
+              "label": "Only when I run it"
+            }
+          ]
+        },
+        "notes": {
+          "type": "textarea",
+          "label": "Anything else the agent should know?",
+          "help": "Incident naming conventions, an existing retro template, who should be notified.",
+          "required": false,
+          "constraints": {
+            "maxLength": 2000
+          }
+        }
+      }
+    },
+    "message": "The user supplied these starting points. Confirm each one, ask about anything left blank, then create the automation.\n\n- Incident channel: {{form.incidentChannel}}\n- Linear team: {{form.linearTeam}}\n- Notion destination: {{form.notionDestination}}\n- Preferred trigger: {{form.triggerPreference}}\n- Notes: {{form.notes}}\n\nStill undecided and required before creation: the incident identifier format and the approved Notion retrospective template."
+  }
+}

openhands_extensions-0.11.0/automations/catalog/jira-issue-to-pr.json → openhands_extensions-0.12.0/automations/catalog/jira-issue-to-pr/manifest.json

@@ -3,12 +3,17 @@
   "name": "Jira issue to GitHub PR",
   "category": "Project management",
   "description": "Watch a Jira Cloud project for issues with a configurable label and automatically open a GitHub pull request for each new issue found. The target GitHub repo is read from the ticket body - no repo parameter required at deploy time.",
-  "requiredIntegrationIds": [
-    "jira",
-    "github"
-  ],
+  "requires": {
+    "integrations": {
+      "jira": {
+        "message": "Reads the project for issues carrying the trigger label."
+      },
+      "github": {
+        "message": "Opens a pull request on the repository named in the ticket."
+      }
+    }
+  },
   "popularityRank": 85,
   "estimatedSetupMinutes": 5,
-  "prompt": "Set up a Jira automation to create pull requests",
   "exampleImplementation": "Trigger: cron polling (e.g. every 5 minutes)\nRequired secrets: Jira API token, GitHub personal access token (repo + workflow scope)\n\n1. Collect Jira base URL, email, API token secret name, label to watch, and cron schedule from the user. No GitHub repo is needed at deploy time - each ticket must include the target repo (owner/repo) in its body.\n2. Poll POST /rest/api/3/search/jql on the Jira Cloud instance to find open issues carrying the configured label.\n3. Deduplicate against a KV-store-backed set of already-processed issue keys so re-runs never create duplicate PRs.\n4. For each new issue, start an independent OpenHands agent conversation that extracts the GitHub repo from the ticket body, clones it, creates a branch named after the Jira key, implements or scaffolds the requested change, and opens a pull request.\n5. Immediately after the conversation is created, post a Jira comment on the issue: 'I'm on it: <conversation URL>'.\n6. Persist the processed issue key immediately after dispatching so the next poll skips it."
 }