@openhands/extensions 0.16.0 → 0.18.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.16.0"
+  ".": "0.18.0"
 }

package/AGENTS.md

@@ -87,6 +87,7 @@ When editing or adding skills in this repo, follow these rules (and add new skil
 ## Repository conventions
 
 - **Punctuation style**: Use plain hyphens (`-`) instead of em dashes (`—` / `\u2014`) in skill descriptions, SKILL.md content, and marketplace JSON entries.
+- **`defaultEnabled` on marketplace skill entries**: a skill entry may carry `"defaultEnabled": true`, which means the skill is enabled for every **new** workspace. Omit the field for everything else - absence already means off, so `"defaultEnabled": false` is not written. Keep the set small and provider-agnostic; anything language-, vendor- or workflow-specific should start off and be opted into from the catalog UI. `npm run build:skills` joins the flag into `skills/index.js` and exports `DEFAULT_ENABLED_SKILL_NAMES` for hosts to seed a workspace from. Seeding is all it does: the contract hosts implement is that a workspace which already saved a selection keeps it, so adding the flag to a skill later will not retroactively enable it for existing users.
 - 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.

package/README.md

@@ -89,7 +89,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 **64 extensions** (54 skills, 10 plugins).
+This repository contains **2 marketplace(s)** with **67 extensions** (57 skills, 10 plugins).
 
 ### large-codebase
 
@@ -108,7 +108,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases
 
 Official skills and plugins for OpenHands — the open-source AI software engineer.
 
-**60 extensions** (52 skills, 8 plugins)
+**63 extensions** (55 skills, 8 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
@@ -133,6 +133,8 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | frontend-design | skill | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks ... | — |
 | github | skill | Interact with GitHub repositories, pull requests, issues, and workflows using the GITHUB_TOKEN environment variable a... | — |
 | 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-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` |
@@ -146,6 +148,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | linear | skill | Interact with Linear project management - query issues, update status, create tickets using the Linear GraphQL API. | — |
 | linear-triage | skill | Create an automation that triages new Linear issues by inspecting title, description, team, and recent related issues... | `/linear-triage:setup` |
 | magic-test | plugin | A simple test plugin for verifying plugin loading. Triggers on magic words (alakazam, abracadabra) and returns a spec... | — |
+| news-digest | skill | Create an automation that reads public RSS and Atom feeds on a schedule, keeps what is new and matches the configured... | `/news-digest:setup` |
 | notion | skill | Create, search, and update Notion pages/databases using the Notion API. Use for documenting work, generating runbooks... | — |
 | npm | skill | Handle npm package installation in non-interactive environments by piping confirmations. Use when installing Node.js ... | — |
 | onboarding | plugin | Assess repository agent-readiness across five pillars, propose high-impact fixes, and generate repo-specific AGENTS.m... | — |

package/automations/README.md

@@ -2,8 +2,9 @@
 
 `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.
+configuration experience for that automation. It is the only file there. A script an automation uploads as
+a `.tar.gz` is not copied into this directory: `setup.bundle.files` names where it already lives, so a
+script shipped by both a skill and the catalog has one copy rather than two.
 
 ```
 catalog/<id>/manifest.json   one automation per directory - card metadata plus an optional `setup` block
@@ -50,7 +51,8 @@ two records of the same fact from drifting apart, and it is why the file is as s
 | `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` |
+| The create endpoint | `POST /v1/preset/prompt`, or `POST /v1` for an entry that ships a bundle |
+| 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 |
 
@@ -103,8 +105,7 @@ That way a skill can rename its trigger without leaving a stale copy behind in t
 `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.
+  `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.
 
@@ -124,11 +125,71 @@ when the deployment cannot run the direct path - a deployment whose capabilities
 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 `repo-picker` may declare `multiple: true`, and then it collects several
+repositories and its value is a list. A placeholder that is the *whole* value
+resolves to that list rather than to text, which is what lets `"repos":
+"{{form.repositories}}"` produce an array; the same placeholder inside a
+sentence still reads as text. On the preset path the list becomes one `repos[]`
+entry per repository. The created automation is named after the single
+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.
 
+### 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.
+`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.
+
+```jsonc
+"bundle": {
+  "version": "1.0.0",                 // provenance; bump when the files or config shape change
+  "entrypoint": "python3 main.py",    // run inside the extracted tarball
+  "timeout": 600,                     // when the service default is not enough
+  "files": {                          // packed path -> where it lives in this repo
+    "main.py": "skills/github-pr-reviewer/scripts/main.py"
+  },
+  "config": {                         // rendered from the form, packed as config.json
+    "repos": "{{form.repositories}}", // a whole-value placeholder, so this is a list
+    "trigger_label": "{{form.triggerLabel}}",
+    "review_tone": "{{form.reviewTone}}"
+  }
+}
+```
+
+The host packs those files plus the rendered `config.json`, `POST`s the archive
+to `uploads`, and creates from the `oh-internal://` path that comes back. What it
+sends is otherwise the same restatement of the form as the preset path, plus the
+`template` provenance that makes enabling an entry twice return the automation
+that already exists rather than a duplicate (`OpenHands/automation#344`).
+
+Two things follow from the archetype rather than being stated:
+
+- **`files` names paths, not contents.** The reviewer script is shipped by both
+  its skill and this catalog, and a second copy would drift. `npm run
+  build:automations` inlines the contents into `automations/bundle-index.js`,
+  which is what `getAutomationBundleFiles(id)` returns - a host packing the
+  archive has the published package, not this repository.
+- **`config` is the bundle's `prompt`.** Everything else in the create request is
+  read off the form; only the entry knows which key of its own script each field
+  fills. The script reads that file over its own defaults, so the agent-driven
+  skill path, which substitutes the same values as constants, keeps working
+  unchanged.
+
+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.
+
 ### Format constraints
 
 A setup block is data that instructs another repo to render copy and build a request, so the schema is the
@@ -151,10 +212,14 @@ entered and `{{automation.*}}` for the entry itself. There is deliberately no se
 
 | 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 |
+| `github-pr-reviewer` | Direct scheduled, script bundle | `cron` | an upload, then a create payload |
+| `github-repo-monitor` | Direct scheduled | `cron` | a 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`.
+
 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.
@@ -164,10 +229,10 @@ property of the archetype, not an omission.
 `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.
+They can differ in more than wording. `github-repo-monitor`'s skill polls GitHub on a cron, and its `setup`
+block declares the same polled `cron` form, so the two generations agree. (It once declared an `event`
+form; when the deployment stopped receiving webhooks it was converted to this polling one.) Retiring the
+skill path for entries that ship a `setup` block belongs to whoever promotes this to production.
 
 ## The interface manifest (`interface.json`)
 
@@ -260,6 +325,8 @@ Two findings came out of that check and are baked into the entries:
 | Endpoint | Status |
 | --- | --- |
 | `POST /v1/preset/prompt` | Exists |
+| `POST /v1/uploads` | Exists |
+| `POST /v1` | Exists; accepts `template` provenance from OpenHands/automation#344 |
 | `GET /v1/capabilities` | Exists (OpenHands/automation#270) |
 | `POST /v1/validate` | Exists (OpenHands/automation#270) |