@openhands/extensions 0.11.0 → 0.13.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.11.0"
+  ".": "0.13.0"
 }

package/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.

package/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

package/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

package/automations/README.md

@@ -1,15 +1,307 @@
-# Automation catalog
+# Automations
 
-This directory contains recommended OpenHands automation templates.
+`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/*.json` contains one source file per recommended automation.
-- `index.js` assembles and exports the catalog for Node.js and bundlers.
-- `index.d.ts` contains the public TypeScript shape.
+```
+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
+interface.json               the production Automation interface manifest - domain-level, not per-entry
+interface.schema.json        its contract, JSON Schema draft 2020-12
+index.js                     the stable API for Node.js and bundlers
+index.d.ts                   the public TypeScript shape
+```
 
-Consumers can import the package export:
+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 } from "@openhands/extensions/automations";
+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}}. ..."
+  }
+}
 ```
 
-Each automation references required integrations by ID. Those IDs should match entries in `integrations/catalog/*.json`.
+`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 direct entry may also declare a `message`. It is the seed for the fallback conversation the host offers
+when the deployment cannot run the direct path - a deployment whose capabilities lack the entry's trigger
+kind or required features. The same 2000-character cap applies, and because the fallback fires before the
+form is trustworthy, a direct `message` should not reference `{{form.*}}`.
+
+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.
+
+## The interface manifest (`interface.json`)
+
+The catalog states what varies per automation. `interface.json` states the domain-level facts of the
+production Automation interface - the things that vary between *domains* (automations today, another
+extension surface tomorrow) rather than between entries, so each is stated once rather than eight times.
+Agent Canvas keeps its rendering components and reads every automation-specific datum from this file,
+falling back to its built-in defaults when the manifest is absent or fails admission:
+
+- **`routes`** - the list, setup, and detail routes. The host must have a registration serving each
+  declared shape, so admission verifies they match what it mounted; the manifest is the single source for
+  link construction.
+- **`navigation`** - the sidebar entry and the command-menu entry.
+- **`pages`** - page-identity copy: the list title and subtitle, the detail back label, the edit-dialog
+  title. Generic chrome - buttons, toasts, empty states, validation sentences - stays host copy, rendered
+  through the host's translations.
+- **`docsUrl`** - the automations documentation link, prefix-pinned to docs.openhands.dev by schema.
+- **`attributes`** - the input surface of an existing Automation: which attributes can be set after
+  creation, keyed by the runtime-model property the host sends (`name`, `prompt`, `model`, `timeout`,
+  `schedule`), with labels, help, and numeric bounds. How a client offers them - Agent Canvas renders an
+  edit dialog - is the client's choice, not stated here. `schedule` is a semantic type: the host owns the
+  frequency/weekday/time composite it renders, as it owns the setup form's `cron` type.
+- **`importExport`** - the export file envelope (`kind`, `version`, filename suffix) and the two facts an
+  import cannot derive from the file: the provider inferred for short repository URLs, and the placeholder
+  event source that keeps a half-imported automation inert until its real trigger is applied.
+- **`endpoints`** - service-relative paths the host calls. Relative paths only: the base path, methods,
+  headers, and auth remain the host's, so this cannot express a request to anywhere the host did not
+  choose. `{id}` marks where the host substitutes the automation id.
+- **`featuredAutomationIds`** / **`responderIntegrationIds`** - the catalog entries the list page surfaces
+  as proven, and the integrations whose automations get the responder deployment-choice dialog.
+
+`interface.schema.json` is the authoritative contract, under the same trust rules as the catalog: no
+markup in copy, no free-form URLs, closed key sets, no credentials. This narrowly reverses the `routes`
+and `submit` deletions recorded below **at the domain level only** - per-entry data still follows the
+deletion table.
+
+Changing a route or endpoint here still requires a host release that serves the declared shape, so the
+Distribution open question applies unchanged. The contract fixtures pin `/v1/preset/prompt` as the create
+endpoint; changing `endpoints.createPrompt` must regenerate them in the same release.
+
+## 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` | Exists (OpenHands/automation#270) |
+| `POST /v1/validate` | Exists (OpenHands/automation#270) |
+
+None of these appear in a catalog entry. Their service-relative paths are stated once, in
+`interface.json`'s `endpoints` block, 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 from entries. The route table is a domain-level fact, stated once in `interface.json`. |
+| `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 (and, on direct entries, as the fallback-conversation seed). The action, success navigation, and error handling are identical everywhere; the endpoints are domain-level and live in `interface.json`. |
+| `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.
+- **Delete confirmation and per-run views.** `interface.json` models the list, setup, and detail routes
+  and the settable attributes; deletion, run logs, and the dashboard sub-pages remain host-owned surfaces
+  with no manifest data of their own yet.
+- **Types from the schema.** `index.d.ts` is hand-written and mirrors `catalog.schema.json`. Generating it
+  would remove that second source of truth.

package/automations/catalog/github-pr-reviewer/manifest.json

@@ -0,0 +1,83 @@
+{
+  "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}}.",
+    "message": "This deployment cannot run the scheduled review automation directly. Set it up in this conversation instead: confirm the repository to review, the trigger label, the review tone, and the polling schedule, then create the automation."
+  }
+}

package/automations/catalog/github-repo-monitor/manifest.json

@@ -0,0 +1,83 @@
+{
+  "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}}')",
+    "message": "This deployment cannot run the webhook-driven monitor directly. Set it up in this conversation instead: confirm the repository to watch, the comment event, and the trigger phrase, then create the automation. If webhook delivery is unavailable here, build the polling variant this skill supports."
+  }
+}