@openhands/extensions 0.17.0 → 0.19.0

package/skills/openhands-sdk/SKILL.md

@@ -198,6 +198,7 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`55_persistent_memory.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/55_persistent_memory.py)
 - [`56_structured_output.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/56_structured_output.py)
 - [`57_prompt_hooks`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/57_prompt_hooks)
+- [`58_ask_oracle_tool`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/58_ask_oracle_tool)
 
 ### [`02_remote_agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server)
 

package/skills/ticket-to-code-change/.plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "ticket-to-code-change",
+  "version": "1.0.0",
+  "description": "Create pull or merge requests from Jira or Linear tickets across GitHub, GitLab, and Bitbucket.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "jira",
+    "linear",
+    "github",
+    "gitlab",
+    "bitbucket",
+    "pull-request",
+    "automation"
+  ]
+}

package/skills/ticket-to-code-change/README.md

@@ -0,0 +1,5 @@
+# Ticket to code change
+
+Sets up a Jira or Linear automation that sends implementation-ready tickets to OpenHands and opens the resulting change in GitHub, GitLab, or Bitbucket.
+
+See `SKILL.md` for prerequisites and the setup workflow.

package/skills/ticket-to-code-change/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ticket-to-code-change
+description: >
+  Set up a ticket-to-code-change automation using Jira or Linear as the issue
+  tracker and GitHub, GitLab, or Bitbucket as the source-control provider.
+  Watches for implementation-ready tickets, starts an OpenHands conversation
+  to implement and test the request, opens a pull or merge request, and links
+  the result back to the ticket.
+triggers:
+  - /ticket-to-code-change:setup
+---
+
+# Ticket to code change
+
+Create an automation that turns implementation-ready tickets into tested pull
+requests or merge requests.
+
+## Information to collect
+
+Ask the user for:
+
+1. The issue tracker: Jira Cloud or Linear.
+2. The source-control provider: GitHub, GitLab, or Bitbucket Cloud.
+3. The project or team to watch and the label or workflow state that means
+   "implementation ready".
+4. How a ticket identifies its target repository and base branch.
+5. The polling schedule or issue event to use.
+6. The ticket state to set when work starts and when the change request opens.
+7. Whether linked dependencies must be completed before dispatch.
+
+## Setup workflow
+
+1. Verify that both required integrations are connected and can read the
+   selected project and repository.
+2. Prefer an issue event trigger when the deployment can receive events;
+   otherwise use cron polling with durable issue-ID deduplication.
+3. Limit each run to a small configurable number of new tickets. On initial
+   deployment, establish a baseline instead of dispatching the entire backlog.
+4. Build a prompt that includes the full ticket, acceptance criteria,
+   dependency status, repository, base branch, and provider-specific request
+   terminology. Require the agent to run the repository's tests before opening
+   the pull request or merge request.
+5. Create the automation through the Automation backend described in
+   `<RUNTIME_SERVICES>`. Use its prompt-preset endpoint and authenticate with
+   the runtime-provided automation API key.
+6. Configure the automation to post the OpenHands conversation URL immediately
+   and the resulting pull-request or merge-request URL back to the ticket.
+
+Do not dispatch tickets with unresolved dependencies or without an unambiguous
+target repository; comment on the ticket with the missing information instead.

package/skills/ticket-to-code-change/commands/ticket-to-code-change-setup.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Set up a ticket-to-code-change automation using Jira or Linear as the issue tracker and GitHub, GitLab, or Bitbucket as the source-control provider. Watches for implementation-ready tickets, starts an OpenHands conversation to implement and test the request, opens a pull or merge request, and links the result back to the ticket.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/tests/fixtures/automations/github-repo-monitor.json

@@ -37,6 +37,17 @@
                 "type": "cron",
                 "schedule": "*/15 * * * *",
                 "timezone": "UTC"
+              },
+              "template": {
+                "id": "github-repo-monitor",
+                "version": "1.0.0",
+                "config": {
+                  "repository": "OpenHands/agent-server-gui",
+                  "triggerPhrase": "@openhands",
+                  "ref": "main",
+                  "schedule": "*/15 * * * *",
+                  "timezone": "UTC"
+                }
               }
             }
           }
@@ -67,6 +78,17 @@
               "type": "cron",
               "schedule": "*/15 * * * *",
               "timezone": "UTC"
+            },
+            "template": {
+              "id": "github-repo-monitor",
+              "version": "1.0.0",
+              "config": {
+                "repository": "OpenHands/agent-server-gui",
+                "triggerPhrase": "@openhands",
+                "ref": "main",
+                "schedule": "*/15 * * * *",
+                "timezone": "UTC"
+              }
             }
           }
         },
@@ -79,6 +101,28 @@
             "model": null,
             "name": "GitHub repository monitor - OpenHands/agent-server-gui",
             "prompt": "Poll OpenHands/agent-server-gui for any new issue or pull request comments since the last run. For every comment mentioning '@openhands', read the surrounding issue or pull request context and post a helpful reply as a comment on the same thread.",
+            "preset_metadata": {
+              "preset_type": "prompt",
+              "prompt": "Poll OpenHands/agent-server-gui for any new issue or pull request comments since the last run. For every comment mentioning '@openhands', read the surrounding issue or pull request context and post a helpful reply as a comment on the same thread.",
+              "repos": [
+                {
+                  "url": "OpenHands/agent-server-gui",
+                  "ref": "main",
+                  "provider": "github"
+                }
+              ],
+              "template": {
+                "id": "github-repo-monitor",
+                "version": "1.0.0",
+                "config": {
+                  "repository": "OpenHands/agent-server-gui",
+                  "triggerPhrase": "@openhands",
+                  "ref": "main",
+                  "schedule": "*/15 * * * *",
+                  "timezone": "UTC"
+                }
+              }
+            },
             "trigger": {
               "type": "cron",
               "schedule": "*/15 * * * *",
@@ -128,6 +172,17 @@
                 "type": "cron",
                 "schedule": "*/1 * * * *",
                 "timezone": "UTC"
+              },
+              "template": {
+                "id": "github-repo-monitor",
+                "version": "1.0.0",
+                "config": {
+                  "repository": "OpenHands/agent-server-gui",
+                  "triggerPhrase": "@openhands",
+                  "ref": "main",
+                  "schedule": "*/1 * * * *",
+                  "timezone": "UTC"
+                }
               }
             }
           }
@@ -178,6 +233,17 @@
               "type": "cron",
               "schedule": "0 0 31 2 *",
               "timezone": "UTC"
+            },
+            "template": {
+              "id": "github-repo-monitor",
+              "version": "1.0.0",
+              "config": {
+                "repository": "OpenHands/agent-server-gui",
+                "triggerPhrase": "@openhands",
+                "ref": "main",
+                "schedule": "0 0 31 2 *",
+                "timezone": "UTC"
+              }
             }
           }
         },
@@ -229,6 +295,17 @@
               "type": "cron",
               "schedule": "*/15 * * * *",
               "timezone": "UTC"
+            },
+            "template": {
+              "id": "github-repo-monitor",
+              "version": "1.0.0",
+              "config": {
+                "repository": "OpenHands/agent-server-gui",
+                "triggerPhrase": "@openhands",
+                "ref": "main",
+                "schedule": "*/15 * * * *",
+                "timezone": "UTC"
+              }
             }
           }
         },

package/tests/test_automation_setup.py

@@ -278,6 +278,16 @@ def _render_payload(entry: dict, form_values: dict, tarball_path: str = "") -> d
 
     body["trigger"] = _derive_trigger(entry, form_values)
 
+    # A versioned entry sends its provenance: the service stores it opaquely,
+    # keyed by id for idempotent creation. The form values are non-secret by
+    # design (credentials come only from connected integrations).
+    if "version" in entry:
+        body["template"] = {
+            "id": entry["id"],
+            "version": entry["version"],
+            "config": dict(form_values),
+        }
+
     return body
 
 
@@ -497,6 +507,10 @@ def test_schema_rejects_content_a_setup_block_must_never_carry() -> None:
     with_repeated_identity["setup"]["description"] = "a second description"
     rejected.append(("description", with_repeated_identity))
 
+    with_bad_version = deepcopy(entry)
+    with_bad_version["version"] = "1.0"
+    rejected.append(("'1.0' does not match", with_bad_version))
+
     for expected_fragment, invalid in rejected:
         errors = list(VALIDATOR.iter_errors(invalid))
         assert any(expected_fragment in error.message for error in errors), (
@@ -504,6 +518,28 @@ def test_schema_rejects_content_a_setup_block_must_never_carry() -> None:
         )
 
 
+IMPACT_REJECTIONS: list[tuple[str, dict]] = [
+    ("a basis the host does not know how to compute", {"basis": "run-counter"}),
+    ("markup in a phrase", {"one": "<b>1 sweep</b>"}),
+    ("a placeholder from another namespace", {"other": "{{count}} sweeps for {{form.repo}}"}),
+    ("a plural phrase that hides the count", {"other": "many sweeps completed"}),
+    ("an extra key beside the declared three", {"detail": "and saved hours"}),
+]
+
+
+@pytest.mark.parametrize(
+    ("case", "override"),
+    [pytest.param(case, override, id=case) for case, override in IMPACT_REJECTIONS],
+)
+def test_schema_refuses_an_impact_statement_the_host_must_never_render(
+    case: str, override: dict
+) -> None:
+    entry = deepcopy(_load(CATALOG_DIR / "github-pr-reviewer" / "manifest.json"))
+    entry["impact"].update(override)
+
+    assert list(VALIDATOR.iter_errors(entry)), f"schema admitted {case}"
+
+
 @pytest.mark.parametrize("entry_path", list(_setup_paths()))
 def test_form_placeholders_reference_declared_fields(entry_path: Path) -> None:
     """A {{form.x}} that names no field renders as an empty value at runtime."""
@@ -520,6 +556,26 @@ def test_form_placeholders_reference_declared_fields(entry_path: Path) -> None:
     assert referenced - fields == set()
 
 
+@pytest.mark.parametrize("entry_path", list(_setup_paths()))
+def test_the_declared_features_match_the_archetype(entry_path: Path) -> None:
+    """A bundle needs a deployment that runs a client-supplied tarball; a prompt
+    needs the preset endpoint. Declaring the other one's features is a check the
+    host runs against the wrong capability, so the entry is either offered where
+    it cannot run or withheld where it can."""
+    entry = _load(entry_path)
+    features = set(entry["requires"].get("features", []))
+
+    if _is_bundle(entry):
+        assert "customTarball" in features, f"{entry['id']}: a bundle must declare customTarball"
+        assert "presetPrompt" not in features, (
+            f"{entry['id']}: a bundle creates through {BUNDLE_CREATE_PATH}, not the preset endpoint"
+        )
+    else:
+        assert "customTarball" not in features, (
+            f"{entry['id']}: only a bundle uploads a tarball"
+        )
+
+
 @pytest.mark.parametrize("entry_path", list(_setup_paths()))
 def test_select_fields_offer_options(entry_path: Path) -> None:
     """A select without options is an empty dropdown the user cannot get past.

package/tests/test_catalogs.py

@@ -34,8 +34,10 @@ def test_catalog_ids_are_unique_and_automations_reference_things_that_exist():
 
     known_integration_ids = set(integration_ids)
     for automation in automations:
+        # May be empty: an automation that needs nothing connected says so with
+        # an empty object rather than by leaving the key out. What it may not do
+        # is name an integration that does not exist.
         required = automation["requires"]["integrations"]
-        assert required
         assert set(required) - known_integration_ids == set()
 
         # The launch command is looked up from this skill rather than stored on
@@ -91,7 +93,7 @@ def test_remote_no_auth_mcp_entries_are_intentionally_public():
             transport = option.get("transport", {})
             # An option with `headerFields` still requires the user to supply
             # credentials (just via named headers, e.g. Datadog's
-            # DD_API_KEY/DD_APPLICATION_KEY), so it is NOT "public/no-auth".
+            # DD-API-KEY/DD-APPLICATION-KEY), so it is NOT "public/no-auth".
             has_header_credentials = bool(transport.get("headerFields"))
             if (
                 option["provider"] == "mcp"
@@ -117,7 +119,7 @@ def test_datadog_mcp_uses_documented_api_key_headers():
 
     assert [
         field["key"] for field in api_option["transport"]["headerFields"]
-    ] == ["DD_API_KEY", "DD_APPLICATION_KEY"]
+    ] == ["DD-API-KEY", "DD-APPLICATION-KEY"]
 
 
 def test_credential_fields_have_helper_text_and_link():

package/tests/test_check_issue_readiness.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+
+def _load_prod_module():
+    repo_root = Path(__file__).resolve().parents[1]
+    script_path = repo_root / ".github" / "scripts" / "check_issue_readiness.py"
+    name = "check_issue_readiness"
+    spec = importlib.util.spec_from_file_location(name, script_path)
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+_prod = _load_prod_module()
+evaluate_readiness = _prod.evaluate_readiness
+extract_sections = _prod.extract_sections
+
+
+ENHANCEMENT_READY = """### Problem or Use Case
+
+The integration catalog lacks a Linear entry.
+
+### Desired Behavior
+
+`integrations/catalog/linear.json` describes the Linear MCP server so the
+catalog build picks it up.
+
+### Acceptance Criteria
+
+- [ ] `npm run build:integrations` succeeds with the new entry
+- [ ] `getIntegrationCatalogEntry("linear")` returns the Linear catalog model
+"""
+
+BUG_READY = """### Actual Behavior
+
+Running `uv run --group test pytest tests/` fails in
+`test_skills_catalog.py` with a KeyError when a skill is missing from the
+marketplace.
+
+### Acceptance Criteria
+
+- [ ] `uv run --group test pytest tests/` passes with a clear error message
+"""
+
+
+def test_extract_sections_splits_on_headings():
+    sections = extract_sections("### Alpha\n\ntext\n\n### Beta\n\nmore\n")
+    assert sections["alpha"] == "\ntext\n\n"
+    assert sections["beta"] == "\nmore\n"
+
+
+def test_enhancement_ready_passes():
+    result = evaluate_readiness(ENHANCEMENT_READY, ["enhancement"])
+    assert result.ready is True
+    assert result.reasons == []
+
+
+def test_enhancement_missing_acceptance_criteria_fails():
+    body = "### Desired Behavior\n\nSome desired change.\n"
+    result = evaluate_readiness(body, ["enhancement"])
+    assert result.ready is False
+    assert any("Acceptance Criteria" in r for r in result.reasons)
+
+
+def test_enhancement_missing_desired_behavior_fails():
+    body = ENHANCEMENT_READY.replace(
+        "### Desired Behavior\n\n"
+        "`integrations/catalog/linear.json` describes the Linear MCP server so the\n"
+        "catalog build picks it up.\n\n",
+        "",
+    )
+    result = evaluate_readiness(body, ["enhancement"])
+    assert result.ready is False
+    assert any("Desired Behavior" in r for r in result.reasons)
+
+
+def test_bug_ready_passes():
+    result = evaluate_readiness(BUG_READY, ["bug"])
+    assert result.ready is True
+    assert result.reasons == []
+
+
+def test_bug_missing_run_method_fails():
+    body = BUG_READY.replace(
+        "Running `uv run --group test pytest tests/` fails",
+        "Running the test suite fails",
+    )
+    result = evaluate_readiness(body, ["bug"])
+    assert result.ready is False
+    assert any("reproducible command" in r for r in result.reasons)
+
+
+def test_bug_npm_build_command_is_a_valid_run_method():
+    body = BUG_READY.replace(
+        "Running `uv run --group test pytest tests/` fails in\n"
+        "`test_skills_catalog.py` with a KeyError when a skill is missing from the\n"
+        "marketplace.",
+        "Running `npm run build:skills` fails with a schema error.",
+    )
+    result = evaluate_readiness(body, ["bug"])
+    assert result.ready is True
+    assert result.reasons == []
+
+
+def test_bug_acceptance_needs_checklist_item():
+    body = BUG_READY.replace(
+        "- [ ] `uv run --group test pytest tests/` passes with a clear error message",
+        "Make the test error message clearer",
+    )
+    result = evaluate_readiness(body, ["bug"])
+    assert result.ready is False
+    assert any("checklist item" in r for r in result.reasons)
+
+
+def test_no_response_field_counts_as_empty():
+    body = BUG_READY.replace(
+        "### Acceptance Criteria\n\n- [ ] `uv run --group test pytest tests/` "
+        "passes with a clear error message\n",
+        "### Acceptance Criteria\n\n_No response_\n",
+    )
+    result = evaluate_readiness(body, ["bug"])
+    assert result.ready is False
+    assert any("Acceptance Criteria" in r for r in result.reasons)
+
+
+def test_no_bug_or_enhancement_label_not_ready():
+    result = evaluate_readiness(ENHANCEMENT_READY, [])
+    assert result.ready is False
+    assert any("bug" in r and "enhancement" in r for r in result.reasons)