@openhands/extensions 0.22.0 → 0.23.0

package/.agents/skills/custom-codereview-guide.md

@@ -1,32 +1,99 @@
 ---
 name: custom-codereview-guide
-description: Repository-specific code review guidelines for OpenHands/extensions
+description: Repository-specific review guidance for OpenHands/extensions.
 triggers:
 - /codereview
 ---
 
-# Extensions Repo — Code Review Guidelines
+# OpenHands/extensions review guide
 
-## Repository Boundaries
+Apply this guide with the general code-review skill and `AGENTS.md`. Approve the
+current head when it has no material correctness, security, compatibility, or
+acceptance-criterion defect. Comment only on concrete failures; do not withhold
+approval for optional refactors, tone, style, or speculative improvements.
 
-Review whether a PR belongs in this public extensions registry. Skills, plugins, automations, and integrations belong here; Agent Server behavior and API endpoints belong in [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk), typed browser API access belongs in [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client), UI belongs in [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands), and scheduling/dispatch lifecycle behavior belongs in [`OpenHands/automation`](https://github.com/OpenHands/automation).
+## Repository ownership and scope
 
-If a PR is opened in the wrong repository, explicitly recommend that it may need to be closed and moved to the repository that owns the change rather than merged here. Apply the repository's contribution and review guidance to every PR.
+This repository owns reusable skills, plugins, automation bundles, and integration
+catalogs. Agent Server behavior, endpoints, and browser client code belong in
+`OpenHands/software-agent-sdk`; Canvas UI belongs in `OpenHands/OpenHands`; and
+scheduling, dispatch, run history, and sandbox lifecycle belong in
+`OpenHands/automation`.
 
+A content PR should remain focused on one extension or one shared mechanism that
+multiple extensions actually use. Flag unrelated edits to another skill, plugin,
+or automation. Shared runtime machinery belongs in the owning product repository,
+not copied into extension content.
 
-## SDK Documentation Placement
+## Blocking checkpoints
 
-If a PR adds or modifies OpenHands SDK-specific documentation (API guides, SDK usage examples, SDK feature descriptions), flag it:
+### Executable instructions and runtime parity
 
-- The canonical source of truth for SDK documentation is <https://docs.openhands.dev/sdk> and its `llms.txt` index.
-- The `skills/openhands-sdk/SKILL.md` in this repo is a thin pointer to the docs site. It should NOT contain duplicated SDK content.
-- **Push back**: ask the submitter to contribute SDK documentation changes to [OpenHands/docs](https://github.com/OpenHands/docs) instead.
+Commands, imports, environment variables, endpoints, and setup steps in extension
+content are executable contracts. Verify them against the released packages and
+the actual local and cloud environments that claim support. Do not approve an
+example that relies on an unreleased API, a developer-only dependency, a private
+path, or a variable that the production runtime does not provide.
 
-## Pre-release Integration Catalog Changes
+For a changed skill, plugin, hook, or automation, follow its documented entrypoint
+in a clean environment far enough to exercise the changed behavior. Keep local
+and cloud behavior identical unless the documentation names and explains a real
+platform capability difference.
 
-The `@openhands/extensions/mcps` catalog was experimental and pre-release. If a
-PR intentionally replaces it with the broader `integrations` catalog and updates
-known downstream consumers in the same coordinated stack, do not require
-backward-compatible `mcps` aliases or a deprecation window. Require migration
-documentation for consumers, but accept a clean breaking change for this
-pre-release surface.
+### Untrusted triggers and credentials
+
+Treat repository events, issue and PR comments, chat messages, catalog fields,
+and extension-provided arguments as untrusted. Verify who may trigger the action,
+whose identity it runs as, which repository or organization it can affect, and
+which secrets it receives. A trigger phrase alone is not authorization. Require
+an explicit allowlist, permission check, or repository policy before performing
+mutating or credentialed work.
+
+Use only the minimum documented credential set. Never place secret values in
+prompts, logs, generated files, examples, or persisted state.
+
+### Sources of truth and generated artifacts
+
+Identify the hand-authored source before reviewing a catalog or generated file.
+A change should update that source once and regenerate every derived artifact
+with the repository's existing sync/build command. Documentation must describe
+the real direction of generation; do not call a generated asset the source of
+truth or claim two runtimes read one asset when they do not.
+
+Check the marketplace entry and generated command/catalog coverage required by
+`AGENTS.md`. Do not add a parallel catalog, provider-specific copy, or manual
+compatibility layer when the repository already has a generator or schema.
+
+### Documentation claims
+
+Test copy-paste commands and verify named tools, flags, package exports, URLs, and
+installation mechanisms from authoritative sources. A plausible command is not
+evidence. Documentation that teaches the wrong data flow or setup is a material
+finding because agents execute it directly.
+
+SDK documentation belongs in `docs.openhands.dev/sdk`; the generated
+`skills/openhands-sdk/SKILL.md` remains a thin synchronized entrypoint. The
+former `@openhands/extensions/mcps` catalog was experimental and pre-release, so
+an explicitly coordinated replacement with the `integrations` catalog needs
+consumer migration documentation but not compatibility aliases or a deprecation
+window.
+
+### Dependencies and supply chain
+
+Apply the general seven-day release-recency guard to the exact dependency version,
+regardless of the package's age or popularity. Validate installation with the
+package manager and runtime used by the extension. Temporary git pins and
+unreleased package APIs are blockers for merge unless the PR is an explicit,
+coordinated stack that will replace them before release.
+
+## Evidence and comment discipline
+
+Evidence should exercise the extension as users invoke it: run the command, hook,
+plugin, or automation entrypoint and show the relevant result. Static text checks
+alone do not validate executable instructions. Require only the environments and
+paths the change affects.
+
+Do not comment on punctuation, preferred prose tone, optional DRY cleanup, or
+hypothetical non-standard configurations without a supported failure mode. Before
+raising a finding, verify that the referenced file and behavior are present in
+the current PR head and have not already been addressed in review history.

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.22.0"
+  ".": "0.23.0"
 }

package/AGENTS.md

@@ -16,6 +16,27 @@ Related repositories have distinct responsibilities:
 
 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.
 
+## Review-Facing Extension Checklist
+
+Before opening a PR:
+
+- Keep a content change focused on one skill, plugin, automation bundle, or
+  integration. Put shared product runtime behavior in the repository that owns
+  it instead of copying machinery into extension content.
+- Treat every command, import, environment variable, endpoint, setup step, and
+  package name as an executable contract. Test the documented entrypoint with
+  released packages in each local or cloud environment the extension claims to
+  support; do not rely on developer-only variables or private paths.
+- For event-, comment-, or message-triggered work, define who may trigger it,
+  whose identity executes it, what scope it may mutate, and which minimal secrets
+  it receives. A trigger phrase is not authorization.
+- Edit the hand-authored source once and regenerate derived catalogs, commands,
+  indexes, and package assets with the existing sync/build command. Document the
+  true generation direction and do not introduce a parallel source of truth.
+- Verify copy-paste commands and factual documentation claims against the actual
+  tool or authoritative source. Extension instructions are executed by agents,
+  so incorrect setup or data-flow documentation is a functional defect.
+
 ## What this repo contains
 
 - `skills/` — a catalog of skills, **one directory per skill**.
@@ -110,7 +131,7 @@ When editing or adding skills in this repo, follow these rules (and add new skil
 - 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.
 - When reviewing or editing `skills/openhands-sdk`, validate copy-paste imports against the released packages with `uv run --with openhands-tools --with openhands-workspace --with openhands-agent-server python ...`. In the current released workspace package, the exported remote workspace classes are `APIRemoteWorkspace` / `OpenHandsCloudWorkspace`; `RemoteAPIWorkspace` is not available.
-- For agent-driven plugin scripts, prefer `from openhands.sdk.plugin import PluginSource` and pass `plugins=[PluginSource(source=...)]` into `Conversation`. In the current released SDK (`openhands-sdk` 1.18.x), `Plugin` is not exported from `openhands.sdk.plugin`, so direct `Plugin.load(...)` imports can break CI.
+- For agent-driven plugin scripts, prefer `from openhands.sdk.plugin import PluginSource` and pass `plugins=[PluginSource(source=...)]` into `Conversation`. The current released SDK (`openhands-sdk` 1.49.x) exports both `PluginSource` and `Plugin` from `openhands.sdk.plugin`, so `Plugin.load(...)` imports also work (used by `tests/test_skill_plugin_loading.py`).
 - `plugins/qa-changes/action.yml` now has a preflight guard for fork PRs in `pull_request` context: if the PR comes from a fork and `LLM_API_KEY` is unavailable (normal for forks), the action exits successfully with a clear skip notice instead of failing.
 - `skills/bitbucket` should not tell agents to rewrite remotes proactively. In OpenHands, `BITBUCKET_TOKEN` is commonly kept in unencoded `user:token` form for API calls like `curl --user "$BITBUCKET_TOKEN" ...`; only split and URL-encode it when constructing a non-interactive HTTPS Git remote URL.
 

package/README.md

@@ -9,7 +9,7 @@ It contains reusable, shareable skills and plugins that customize agent behavior
 
 ## Repository boundaries
 
-`OpenHands/extensions` is the public registry for reusable skills, plugins, automations, and integrations. [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns Agent Server execution and the canonical API, [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns typed browser access to that API, [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) owns Agent Canvas UI, and [`OpenHands/automation`](https://github.com/OpenHands/automation) owns scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration.
+`OpenHands/extensions` is the public registry for reusable skills, plugins, automations, and integrations. [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns Agent Server execution, the canonical API, and typed browser access to it under `clients/typescript/`, [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) owns Agent Canvas UI, and [`OpenHands/automation`](https://github.com/OpenHands/automation) owns scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration.
 
 Put reusable extension artifacts here rather than in application repositories. If a PR is opened in the wrong repository, close and move it to the repository that owns the change.