@openhands/extensions 0.19.0 → 0.21.0

package/.github/workflows/check-extensions.yml

@@ -58,6 +58,8 @@ jobs:
         run: python scripts/sync_extensions.py --check
 
   sync-sdk-skill:
+    permissions:
+      contents: read
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -69,4 +71,6 @@ jobs:
           python-version: "3.12"
 
       - name: Check SDK skill is up to date
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
         run: python scripts/sync_openhands_sdk_skill.py --check

package/.github/workflows/pr-artifacts.yml

@@ -0,0 +1,294 @@
+---
+name: PR Artifacts
+
+on:
+    workflow_dispatch: # Manual trigger for testing
+    pull_request_target:
+        types: [opened, synchronize, reopened, closed]
+        branches: [main]
+    pull_request_review:
+        types: [submitted]
+
+jobs:
+  # Auto-remove .pr/ directory from same-repository PRs when approved.
+    cleanup-on-approval:
+        concurrency:
+            group: cleanup-pr-artifacts-${{ github.event.pull_request.number }}
+            cancel-in-progress: false
+        if: >-
+            github.event_name == 'pull_request_review' &&
+            github.event.review.state == 'approved' &&
+            github.event.pull_request.head.repo.full_name == github.repository
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+            pull-requests: write
+        steps:
+            # Use PAT so the push triggers CI workflows that will complete and
+            # satisfy branch protection. We can't use [skip ci] because GitHub Apps
+            # can create stuck checks that block merging.
+            - uses: actions/checkout@v7
+              with:
+                  ref: ${{ github.event.pull_request.head.ref }}
+                  token: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC }}
+
+            - name: Remove .pr/ directory
+              id: remove
+              run: |
+                  if [ -d ".pr" ]; then
+                    git config user.name "allhands-bot"
+                    git config user.email "allhands-bot@users.noreply.github.com"
+                    git rm -rf .pr/
+                    git commit -m "chore: Remove PR-only artifacts [automated]"
+                    git push || {
+                      echo "::error::Failed to push cleanup commit. Check branch protection rules."
+                      exit 1
+                    }
+                    echo "removed=true" >> "$GITHUB_OUTPUT"
+                    echo "::notice::Removed .pr/ directory"
+                  else
+                    echo "removed=false" >> "$GITHUB_OUTPUT"
+                    echo "::notice::No .pr/ directory to remove"
+                  fi
+
+            - name: Update PR comment after cleanup
+              if: steps.remove.outputs.removed == 'true'
+              uses: actions/github-script@v9
+              with:
+                  script: |
+                      const marker = '<!-- pr-artifacts-notice -->';
+                      const body = `${marker}
+                      ✅ **PR Artifacts Cleaned Up**
+
+                      The \`.pr/\` directory has been automatically removed.
+                      `;
+
+                      const comments = await github.paginate(
+                        github.rest.issues.listComments,
+                        {
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          issue_number: context.issue.number,
+                          per_page: 100,
+                        },
+                      );
+
+                      const existing = comments.find(c => c.body.includes(marker));
+                      if (existing) {
+                        await github.rest.issues.updateComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          comment_id: existing.id,
+                          body: body,
+                        });
+                      }
+
+  # Inspect the fork through the API; never check out untrusted code with a write token.
+    check-pr-artifacts:
+        if: >-
+            github.event_name == 'pull_request_target' &&
+            github.event.action != 'closed'
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            pull-requests: write
+        steps:
+            - name: Post or update PR comment
+              uses: actions/github-script@v9
+              with:
+                  script: |
+                      const marker = '<!-- pr-artifacts-notice -->';
+                      const pullRequest = context.payload.pull_request;
+                      const headRepository = pullRequest.head.repo;
+                      let exists = true;
+
+                      try {
+                        await github.rest.repos.getContent({
+                          owner: headRepository.owner.login,
+                          repo: headRepository.name,
+                          path: '.pr',
+                          ref: pullRequest.head.sha,
+                        });
+                      } catch (error) {
+                        if (error.status === 404) {
+                          exists = false;
+                        } else {
+                          throw error;
+                        }
+                      }
+
+                      const comments = await github.paginate(
+                        github.rest.issues.listComments,
+                        {
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          issue_number: context.issue.number,
+                          per_page: 100,
+                        },
+                      );
+                      const existing = comments.find(c => c.body.includes(marker));
+
+                      if (!exists) {
+                        if (existing) {
+                          await github.rest.issues.updateComment({
+                            owner: context.repo.owner,
+                            repo: context.repo.repo,
+                            comment_id: existing.id,
+                            body: `${marker}
+                            ✅ **PR Artifacts Cleaned Up**
+
+                            The \`.pr/\` directory is no longer present.
+                            `,
+                          });
+                        }
+                        return;
+                      }
+
+                      const isFork = headRepository.full_name !== context.payload.repository.full_name;
+                      const cleanup = isFork
+                        ? 'Because this is a fork PR, the workflow will **open or update a cleanup PR against `main` after merge**.'
+                        : 'The directory will be **automatically removed when the PR is approved**.';
+                      const body = `${marker}
+                      📁 **PR Artifacts Notice**
+
+                      This PR contains a \`.pr/\` directory with temporary PR-specific documents. ${cleanup}
+                      `;
+
+                      core.warning('.pr/ directory contains temporary PR-only artifacts');
+                      if (existing) {
+                        await github.rest.issues.updateComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          comment_id: existing.id,
+                          body: body,
+                        });
+                      } else {
+                        await github.rest.issues.createComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          issue_number: context.issue.number,
+                          body: body,
+                        });
+                      }
+
+  # Fork branches cannot be modified reliably. If artifacts reach the trusted base,
+  # remove them through a pull request so branch protections remain enforced.
+    cleanup-after-merge:
+        concurrency:
+            group: cleanup-pr-artifacts-${{ github.event.pull_request.base.ref }}
+            cancel-in-progress: false
+        if: >-
+            github.event_name == 'pull_request_target' &&
+            github.event.action == 'closed' &&
+            github.event.pull_request.merged == true
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+            pull-requests: write
+        steps:
+            - uses: actions/checkout@v7
+              with:
+                  ref: ${{ github.event.pull_request.base.ref }}
+                  token: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC }}
+
+            - name: Create or update cleanup PR
+              id: cleanup
+              env:
+                  BASE_REF: ${{ github.event.pull_request.base.ref }}
+                  CLEANUP_BRANCH: automation/remove-pr-artifacts
+                  GH_TOKEN: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC }}
+              run: |
+                  if [ ! -d ".pr" ]; then
+                    echo "created=false" >> "$GITHUB_OUTPUT"
+                    echo "::notice::No .pr/ directory to remove from $BASE_REF"
+                    exit 0
+                  fi
+
+                  git config user.name "allhands-bot"
+                  git config user.email "allhands-bot@users.noreply.github.com"
+                  git fetch origin \
+                    "+refs/heads/$CLEANUP_BRANCH:refs/remotes/origin/$CLEANUP_BRANCH" || true
+                  git checkout -B "$CLEANUP_BRANCH"
+                  git rm -rf .pr/
+                  git commit \
+                    -m "chore: remove merged PR artifacts" \
+                    -m "Co-authored-by: openhands <openhands@all-hands.dev>"
+                  git push --force-with-lease origin "HEAD:$CLEANUP_BRANCH"
+
+                  cleanup_pr_url=$(gh pr list \
+                    --base "$BASE_REF" \
+                    --head "$CLEANUP_BRANCH" \
+                    --state open \
+                    --json url \
+                    --jq '.[0].url')
+
+                  if [ -z "$cleanup_pr_url" ]; then
+                    cleanup_pr_url=$(gh pr create \
+                      --base "$BASE_REF" \
+                      --head "$CLEANUP_BRANCH" \
+                      --title "chore: remove merged PR artifacts" \
+                      --body-file - <<EOF
+                  ## Why
+
+                  Temporary \`.pr/\` artifacts reached \`$BASE_REF\` through one or more merged PRs.
+
+                  ## Summary
+
+                  - Remove the temporary \`.pr/\` directory from \`$BASE_REF\`.
+
+                  ## How to Test
+
+                  - Confirm this PR only deletes files under \`.pr/\`.
+                  - Let the required checks validate the cleanup commit.
+
+                  ---
+
+                  _This PR was automatically created by the PR Artifacts workflow._
+                  EOF
+                    )
+                  fi
+
+                  echo "created=true" >> "$GITHUB_OUTPUT"
+                  echo "pr_url=$cleanup_pr_url" >> "$GITHUB_OUTPUT"
+                  echo "::notice::Cleanup PR ready: $cleanup_pr_url"
+
+            - name: Update source PR comment
+              if: steps.cleanup.outputs.created == 'true'
+              uses: actions/github-script@v9
+              env:
+                  CLEANUP_PR_URL: ${{ steps.cleanup.outputs.pr_url }}
+              with:
+                  script: |
+                      const marker = '<!-- pr-artifacts-notice -->';
+                      const body = `${marker}
+                      🧹 **PR Artifact Cleanup Queued**
+
+                      The \`.pr/\` directory reached \`${context.payload.pull_request.base.ref}\` after merge. A cleanup PR has been opened or updated: ${process.env.CLEANUP_PR_URL}
+                      `;
+
+                      const comments = await github.paginate(
+                        github.rest.issues.listComments,
+                        {
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          issue_number: context.issue.number,
+                          per_page: 100,
+                        },
+                      );
+                      const existing = comments.find(c => c.body.includes(marker));
+
+                      if (existing) {
+                        await github.rest.issues.updateComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          comment_id: existing.id,
+                          body: body,
+                        });
+                      } else {
+                        await github.rest.issues.createComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          issue_number: context.issue.number,
+                          body: body,
+                        });
+                      }

package/.github/workflows/pr-description-check.yml

@@ -17,13 +17,15 @@ jobs:
     validate-pr-description:
         name: Validate PR description
         # Draft PRs may still have incomplete descriptions; validate when review starts.
-        # Release PRs are generated by the trusted prepare-release workflow without
+        # Release and artifact-cleanup PRs are generated by trusted workflows without
         # the standard human-authored PR template.
         if: >-
             github.event.pull_request.draft == false &&
             github.event.pull_request.user.login != 'dependabot[bot]' &&
             !(github.event.pull_request.head.repo.full_name == github.repository &&
-            startsWith(github.event.pull_request.head.ref, 'release-please-'))
+            (startsWith(github.event.pull_request.head.ref, 'release-please-') ||
+            (github.event.pull_request.base.ref == 'main' &&
+            github.event.pull_request.head.ref == 'automation/remove-pr-artifacts')))
         runs-on: ubuntu-latest
         steps:
             - name: Checkout trusted workflow scripts

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.19.0"
+  ".": "0.21.0"
 }

package/AGENTS.md

@@ -10,12 +10,11 @@ This repository owns the public registry of reusable OpenHands skills, plugins,
 
 Related repositories have distinct responsibilities:
 
-- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and canonical API.
-- [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns the browser-compatible typed Agent Server client.
+- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, canonical API, and browser-compatible TypeScript Agent Server client under `clients/typescript/`.
 - [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) owns Agent Canvas UI and local-stack orchestration.
 - [`OpenHands/automation`](https://github.com/OpenHands/automation) owns scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration.
 
-Put reusable skills, plugins, automations, and integrations here; put backend execution behavior in the SDK, typed API access in `typescript-client`, application UI in Agent Canvas, and scheduling/dispatch lifecycle code in `automation`. If a PR is opened in the wrong repository, explicitly recommend closing and moving it to the owning repository. PRs must follow this repository's applicable contribution and code-review guidance.
+Put reusable skills, plugins, automations, and integrations here; put backend execution behavior and typed API access in the SDK, application UI in Agent Canvas, and scheduling/dispatch lifecycle code in `automation`. If a PR is opened in the wrong repository, explicitly recommend closing and moving it to the owning repository. PRs must follow this repository's applicable contribution and code-review guidance.
 
 ## What this repo contains
 
@@ -106,7 +105,7 @@ When editing or adding skills in this repo, follow these rules (and add new skil
 - 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_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.
+- `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 variants a deployment can offer (the keys of `setup.form.triggers`; multiple keys mean any supported selected variant can run), schedule limits, timezone lists, event choices, and model profiles (the `cron`, `timezone`, `event-source`, `event-type`, and `llm-profile` field types), the preflight call, the create request's `name`/`repos`/`model`/`timeout`/`trigger` (rebuilt from same-named form fields when present, the repo-picker field, and the selected key 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.
@@ -118,6 +117,31 @@ When editing or adding skills in this repo, follow these rules (and add new skil
 - `plugins/release-notes` now has a standalone validator at `plugins/release-notes/scripts/validate_release_notes.py`; it rebuilds the deterministic tag-range context, fails if a change bullet omits explicit PR/commit refs or matching author handles, and enforces full PR/author coverage by appending a compact `### 🔎 Small Fixes/Internal Changes` appendix grouped by author when the agent omits lower-signal items. New contributor detection in `generate_release_notes.py` should use merged PR history for human authors (excluding bots) rather than commit-author lookup.
 
 
+## PR-specific documents (`.pr/`)
+
+When working on a PR that requires design documents, live-test logs, development-only scripts, or other temporary artifacts that should **not** be merged to `main`, store them in a `.pr/` directory at the repository root.
+
+```bash
+mkdir -p .pr
+
+.pr/
+├── design.md       # Design decisions and architecture notes
+├── analysis.md     # Investigation or debugging notes
+└── notes.md        # Any other PR-specific content
+```
+
+The `PR Artifacts` workflow (`.github/workflows/pr-artifacts.yml`) owns the lifecycle of this directory:
+
+1. **Notification**: When a PR contains `.pr/`, a single comment is posted to the PR conversation alerting reviewers.
+2. **Auto-cleanup on approval**: For same-repository PRs, the directory is automatically removed by a follow-up commit when the PR is approved.
+3. **Post-merge cleanup**: If artifacts reach `main`, including through a fork PR, the workflow opens or updates a cleanup PR against `main`.
+
+Important notes:
+
+- Do not put anything in `.pr/` that needs to be preserved.
+- The `.pr/` check is informational during development; it posts a notice rather than blocking the PR.
+- Cleanup PRs follow the normal review and required-check protections for `main`.
+
 ## CI / validation gotchas
 
 - The test suite expects **every directory under `skills/`** to be listed in a marketplace. If you add a new skill (or rebase onto a main branch that added skills), update the appropriate marketplace file or CI will fail with `Skills missing from marketplace: [...]`.

package/README.md

@@ -96,7 +96,7 @@ The JS and Python versions are kept in lock-step by `release-please` and guarded
 ## Extensions Catalog
 
 <!-- BEGIN AUTO-GENERATED CATALOG -->
-This repository contains **2 marketplace(s)** with **68 extensions** (58 skills, 10 plugins).
+This repository contains **2 marketplace(s)** with **71 extensions** (61 skills, 10 plugins).
 
 ### large-codebase
 
@@ -115,7 +115,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases
 
 Official skills and plugins for OpenHands — the open-source AI software engineer.
 
-**64 extensions** (56 skills, 8 plugins)
+**67 extensions** (59 skills, 8 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
@@ -142,10 +142,12 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | github-actions | skill | Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating wo... | — |
 | github-agents-md-maintainer | skill | Create an automation that keeps AGENTS.md current in one or more GitHub repositories. On a schedule an agent reads th... | `/agents-md:setup` |
 | github-issue-to-pr | skill | Create an automation that implements GitHub issues when a configurable trigger label is applied. Clones the default b... | `/issue-to-pr:setup` |
+| github-issue-triage | skill | Prioritize open issues and establish acceptance criteria before marking them ready for development. | `/github-issue-triage` |
 | github-pr-review | skill | Post structured PR reviews to GitHub with inline comments/suggestions in a single API call. | `/github-pr-review` |
 | github-pr-reviewer | skill | Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed fi... | `/pr-reviewer:setup` |
 | github-repo-monitor | skill | Create a cron automation that polls a GitHub repository for issue and PR comments containing a configurable trigger p... | `/github-monitor:poll` |
 | gitlab | skill | Interact with GitLab repositories, merge requests, and APIs using the GITLAB_TOKEN environment variable. Use when wor... | — |
+| gitlab-issue-to-mr | skill | Create an automation that implements GitLab issues when a configurable trigger label is applied. Clones the default b... | `/issue-to-mr:setup` |
 | incident-retrospective | skill | Create an automation that drafts incident retrospectives by gathering incident-channel messages from Slack, collectin... | `/incident-retro:setup` |
 | iterate | skill | Iterate on a GitHub pull request — drive it through CI, code review, and QA until merge-ready. Monitors state, fixes ... | `/iterate`, `/verify`, `/babysit` |
 | jira-issue-to-pr | skill | Deploy a cron-based OpenHands automation that watches a Jira Cloud project for issues labeled with a configurable lab... | — |
@@ -162,6 +164,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | openhands | plugin | Unified OpenHands plugin — bundles Cloud CLI, REST API (openhands-api), and Automations (openhands-automation) into a... | `/openhands-cloud` |
 | openhands-api | skill | Use the OpenHands Cloud REST API (V1) and agent-server APIs to create and manage Cloud or local backend conversations... | — |
 | openhands-automation | skill | Create and manage OpenHands automations - scheduled tasks that run in sandboxes. Use the prompt preset to create auto... | `/automation:create` |
+| openhands-enterprise-troubleshooting | skill | Diagnose and resolve common issues on OpenHands Enterprise self-hosted installations. Covers sandbox startup failures... | — |
 | openhands-sdk | skill | Reference skill for the OpenHands Software Agent SDK - build AI agents with custom tools, LLM configuration, conversa... | `/sdk` |
 | pdflatex | skill | Install and use pdflatex to compile LaTeX documents into PDFs on Linux. Use when generating academic papers, research... | — |
 | plain-english-content | skill | Write and edit clear, accessible prose in a plain English content style: active voice, front-loaded content, sentence... | — |

package/automations/README.md

@@ -42,16 +42,17 @@ two records of the same fact from drifting apart, and it is why the file is as s
 | 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 trigger variants a deployment can offer | The keys of `setup.form.triggers`; an entry with multiple keys is usable when at least one variant is supported |
+| Schedule limits, timezone list, event choices, and model profiles | The `cron`, `timezone`, `event-source`, `event-type`, and `llm-profile` field types |
+| Local validation rules | The `required` flag and `constraints` on each field, applied to the selected trigger variant |
 | 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 |
+| The created automation's name | A form field named `name`, or the entry's `name` plus the repository that was picked |
+| `repos` in the create request | The repo-picker field, its declared `provider`, and a non-empty field named `ref` if there is one |
+| `model` and `timeout` in the create request | Same-named form fields when they have values |
+| `trigger` in the create request | The selected 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`, or `POST /v1` for an entry that ships a bundle |
+| The create endpoint | `POST /v1/preset/prompt`, `POST /v1/preset/plugin`, or `POST /v1` for an uploaded or bundled tarball |
 | The files a bundle packs | `setup.bundle.files`, read from this repository at build time |
 | Where a success navigates | The created automation, or the started conversation |
 | The analytics stages | The same stages for every automation |
@@ -64,7 +65,7 @@ checks them against the recorded fixtures, so these deletions stay honest rather
 ```jsonc
 {
   "id": "github-pr-reviewer",
-  "name": "GitHub Code Review Agent",
+  "name": "GitHub code review",
   "category": "Code review",
   "description": "...",
   "requires": {
@@ -97,32 +98,40 @@ three entries whose names differ from their skill state it. The command that lau
 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.
+`setup` is optional. Entries that carry one never repeat `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` and `github-repo-monitor` each ask for a schedule and a timezone.
-- **`form.args`** is everything else: the arguments to the automation itself, such as the repository to
-  clone and the tone of the review.
+  If an entry declares more than one key, the host renders those keys as selectable variants and validates
+  only the selected variant's fields before building the payload.
+- **`form.args`** is everything else that is common to every creation path, such as the automation name,
+  model profile, or timeout.
+- **`setup.actions`** is optional and declares user-selectable creation paths for one card. The host renders
+  the common form plus the selected action's `args`, checks that action's `features`, and creates through
+  the endpoint implied by the action key: `prompt` -> `/v1/preset/prompt`, `plugin` -> `/v1/preset/plugin`,
+  and `upload` -> `/v1/uploads` followed by `/v1`.
 
 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: "direct"`** declares exactly one creation archetype: a `prompt`, a repository-shipped `bundle`,
+  or `actions`. A prompt creates through `/v1/preset/prompt`. A bundle is packed and uploaded by the host,
+  then creates through `/v1`. An actions block lets the user choose between prompt, plugin, and uploaded
+  tarball paths in one card. The rest of the create request restates the form, so it is not written out. A
+  form field named `name`, `model`, or `timeout` fills the matching top-level create property. An event
+  trigger may also declare a `filter`, because composing form values into a JMESPath expression is the one
+  part of an event trigger that cannot always 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
+when the deployment cannot run the direct path - a deployment whose capabilities lack every declared trigger
+variant 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 `repo-picker` may declare `multiple: true`, and then it collects several
@@ -135,17 +144,17 @@ repository when there is one and after the count when there are several, since a
 list of names does not fit a name.
 
 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.
+`trigger.schedule` and `trigger.timezone`; `source` and `on` under `triggers.event` become `trigger.source`
+and `trigger.on`; a field named `ref` becomes `repos[].ref` when it has a value. Any other field under a
+trigger kind, such as a phrase to match, is an input to `filter` rather than a trigger property.
 
 ### Entries that ship a script
 
-`mode: "direct"` produces either a `prompt` or a `bundle`, never both. A prompt
-is the right shape when the automation *is* the judgement: the agent reads the
-prompt and does the work. A bundle is the right shape when most of what the
-automation does is deterministic machinery - polling, dedupe, state, fixed API
-calls - and the agent is needed only for the part that genuinely needs judgement.
+`mode: "direct"` produces exactly one of `prompt`, `bundle`, or `actions`. A
+prompt is the right shape when the automation *is* the judgement: the agent
+reads the prompt and does the work. A bundle is the right shape when most of
+what the automation does is deterministic machinery - polling, dedupe, state,
+fixed API calls - and the agent is needed only for the part that genuinely needs judgement.
 `github-pr-reviewer` is the first: its script owns discovery, label-event
 dedupe, per-repo state and the review checkout, and starts a conversation only
 once a pull request actually needs reviewing.
@@ -188,7 +197,10 @@ Two things follow from the archetype rather than being stated:
 A bundle declares `requires.features: ["customTarball"]`: a deployment that
 cannot run a client-supplied tarball cannot run the entry, whatever trigger kinds
 it offers. It never declares `repos` - the raw create endpoint has no such field,
-and a bundle fetches what it needs itself.
+and a bundle fetches what it needs itself. In an `actions` entry, creation-path
+features move down to each action (`presetPrompt`, `presetPlugin`, or
+`customTarball`) so a deployment can offer the supported choices without needing
+every creation path.
 
 ### Format constraints
 
@@ -208,17 +220,19 @@ trust boundary. It enforces:
 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
+### The archetypes
 
 | Entry | Archetype | Trigger | Produces |
 | --- | --- | --- | --- |
 | `github-pr-reviewer` | Direct scheduled, script bundle | `cron` | an upload, then a create payload |
 | `github-repo-monitor` | Direct scheduled | `cron` | a create payload |
+| `qa-changes` | Direct event | `event` | a create payload |
+| `custom-automation` | Direct custom action with prompt, plugin, or upload variants | `cron` or `event` | a create payload, or an upload then create payload |
 | `incident-retrospective-drafter` | Assisted conversation | decided during the conversation | a seed message |
 
-An event archetype is still expressible - `github-repo-monitor` used one until its deployment could no
-longer receive webhooks, and was converted to the polled `cron` form. The schema keeps supporting `event`
-triggers for deployments that can. See the `event` key under `setup.form.triggers` in `catalog.schema.json`.
+An entry can declare both `cron` and `event` under `setup.form.triggers`. The host treats those keys as
+selectable variants and creates the payload from the selected one; a deployment that only supports one of
+the variants can still offer that supported path.
 
 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
@@ -300,9 +314,11 @@ import scenarios from "@openhands/extensions/testing/automations/github-pr-revie
 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.
+Each scenario carries whichever blocks apply: `formValues`, `selectedTrigger`, `integrationState`,
+`localValidation`, `preflight`, `create`, `conversation`, `expectedFieldErrors`,
+`expectedPrerequisiteOutcome`. `selectedTrigger` is required when an entry declares multiple trigger
+variants and the scenario records a create or preflight payload. `capabilities.json` holds 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`:
@@ -359,7 +375,7 @@ questions to this work. What changed and why:
 | `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. |
+| `triggerKindsAnyOf` | Removed. The keys of `form.triggers` are the available trigger variants, and multiple keys already mean the host can offer any supported one. |
 | `{{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. |