@openhands/extensions 0.27.0 → 0.29.0

package/skills/simplified-technical-english/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: simplified-technical-english
+description: >
+  Write explanations and chat in the style of ASD-STE100 Simplified Technical
+  English: short active sentences, one idea each, plain approved words. Use this
+  when the reader benefits from maximum clarity: summaries, PR descriptions,
+  safety- or ops-critical instructions, or any comment or reply that should be easy 
+  to read the first time. Applies to PROSE ONLY; it must never change code, identifiers,
+  APIs, or commit messages.
+license: MIT
+triggers:
+  - simplified technical english
+  - STE
+  - ASD-STE100
+---
+
+# Simplified Technical English
+
+ASD-STE100 Simplified Technical English is a controlled-language standard from
+aerospace and defense. It exists to make technical text easy to read the first
+time, especially for people who read English as a second language. This skill
+adapts its spirit for agent prose.
+
+Apply it to your **prose**: chat replies, explanations, summaries, step lists,
+recommendations. The goal is easy reading, not dumbed-down thinking. Open the
+text up and keep the substance.
+
+## Core rules
+
+- **Prefer short sentences.** Aim for 20 words or fewer, particularly for instructions.
+- **One idea per sentence, one topic per paragraph.** Split a sentence that carries two ideas.
+- **Active voice.** Write "Run the tests", not "The tests should be run".
+- **Plain, consistent words.** Prefer a common word over a fancy one. Use one word for one idea. Do not switch synonyms for the same thing mid-text.
+- **Say the thing directly.** Lead with the answer. Give the number, name, or path. Cut filler like "in terms of", "a range of", "going forward".
+- **Positive instructions.** Tell the reader what to do, not only what to avoid.
+
+## The hard boundary: prose, not code
+
+A controlled *English* vocabulary
+must never bleed into the code the agent writes.
+
+- **Do not** simplify or rename variables, functions, types, files, config keys, CLI flags, API fields, or error strings to obey "approved words". Code needs exact, domain-precise names.
+- **Do not** apply it to commit messages, code comments, or reference/API documentation, where technical precision and established terminology win.
+- **Do** keep using the project's real domain terms in prose. Naming a concept correctly beats naming it "simply".
+
+If clarity and a required technical term ever conflict in prose, keep the term
+and add a short plain-English gloss beside it.
+
+## When to use it
+
+- The user asked for plain or simple or clear text.
+- Instructions where a misread is costly (ops, deploys, security steps).
+- Long or dense explanations that need to be scannable.
+
+## When not to use it
+
+- Code, identifiers, commit messages, or API/reference docs (see the boundary above).
+- Creative or personal-voice writing, where rhythm and personality matter more than the controlled register.
+- Cases where a precise domain term must stay exact. Keep the term.
+
+## Attribution
+
+Standard: ASD-STE100 (ASD, the AeroSpace and Defence Industries Association of
+Europe). This skill adapts its principles for agent prose; it is not the
+official specification and does not reproduce its controlled dictionary.

package/tests/fixtures/automations/github-pr-reviewer.json

@@ -68,7 +68,7 @@
               "timeout": 300,
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.8.1",
+                "version": "1.9.2",
                 "config": {
                   "repos": [
                     "OpenHands/agent-server-gui"
@@ -108,7 +108,7 @@
             "timeout": 300,
             "template": {
               "id": "github-pr-reviewer",
-              "version": "1.8.1",
+              "version": "1.9.2",
               "config": {
                 "repos": [
                   "OpenHands/agent-server-gui"
@@ -213,7 +213,7 @@
               "timeout": 300,
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.8.1",
+                "version": "1.9.2",
                 "config": {
                   "repos": [
                     "OpenHands/agent-server-gui",
@@ -254,7 +254,7 @@
             "timeout": 300,
             "template": {
               "id": "github-pr-reviewer",
-              "version": "1.8.1",
+              "version": "1.9.2",
               "config": {
                 "repos": [
                   "OpenHands/agent-server-gui",
@@ -296,7 +296,7 @@
             "preset_metadata": {
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.8.1",
+                "version": "1.9.2",
                 "config": {
                   "repos": [
                     "OpenHands/agent-server-gui",
@@ -351,7 +351,7 @@
               "timeout": 300,
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.8.1",
+                "version": "1.9.2",
                 "config": {
                   "repos": [
                     "OpenHands/agent-server-gui"
@@ -444,7 +444,7 @@
             "timeout": 300,
             "template": {
               "id": "github-pr-reviewer",
-              "version": "1.8.1",
+              "version": "1.9.2",
               "config": {
                 "repos": [
                   "OpenHands/agent-server-gui"
@@ -540,7 +540,7 @@
             "timeout": 300,
             "template": {
               "id": "github-pr-reviewer",
-              "version": "1.8.1",
+              "version": "1.9.2",
               "config": {
                 "repos": [
                   "OpenHands/agent-server-gui"
@@ -616,7 +616,7 @@
               "timeout": 300,
               "template": {
                 "id": "github-pr-reviewer",
-                "version": "1.8.1",
+                "version": "1.9.2",
                 "config": {
                   "repos": [
                     "OpenHands/automation"

package/tests/test_agent_conversation_dispatch.py

@@ -263,6 +263,91 @@ def test_new_delivery_on_a_running_new_head_still_sends_a_turn(monkeypatch):
     }
 
 
+def _errored_local_conversation(monkeypatch):
+    monkeypatch.setattr(agent_conversation, "_register_tools", lambda: None)
+    workspace = MagicMock()
+    workspace.__enter__.return_value = workspace
+    workspace.get_secrets.return_value = {}
+    monkeypatch.setattr(
+        agent_conversation, "RemoteWorkspace", lambda **kwargs: workspace
+    )
+    conversation = MagicMock()
+    conversation.state.execution_status = ConversationExecutionStatus.ERROR
+    monkeypatch.setattr(
+        agent_conversation.RemoteConversation,
+        "attach",
+        MagicMock(return_value=conversation),
+    )
+    return conversation
+
+
+def test_errored_conversation_retries_its_delivery(monkeypatch):
+    """A matched delivery whose conversation died is retried, not deduplicated.
+
+    The delivery string never changes for a stable subject, so treating ERROR as
+    "deduplicated" would strand that subject forever with its work unfinished.
+    """
+    state = {
+        _state_key("repo:pr:9"): {
+            "subject": "repo:pr:9",
+            "conversation_id": "22222222-2222-4222-8222-222222222222",
+            "delivery": "head-1",
+        }
+    }
+    _fake_kv(monkeypatch, state)
+    conversation = _errored_local_conversation(monkeypatch)
+
+    with _dispatcher(monkeypatch) as dispatcher:
+        result = dispatcher.deliver("repo:pr:9", "head-1", "old")
+
+    assert result["disposition"] == "retried"
+    conversation.update_secrets.assert_called_once_with(dispatcher._secrets)
+    conversation.send_message.assert_called_once_with("old")
+    conversation.run.assert_called_once_with(blocking=False)
+    assert state[_state_key("repo:pr:9")]["error_retries"] == 1
+
+
+def test_errored_conversation_stops_retrying_after_the_bound(monkeypatch):
+    """A conversation that keeps failing is not re-run on every scan."""
+    state = {
+        _state_key("repo:pr:9"): {
+            "subject": "repo:pr:9",
+            "conversation_id": "22222222-2222-4222-8222-222222222222",
+            "delivery": "head-1",
+            "error_retries": agent_conversation._MAX_ERROR_RETRIES,
+        }
+    }
+    _fake_kv(monkeypatch, state)
+    conversation = _errored_local_conversation(monkeypatch)
+
+    with _dispatcher(monkeypatch) as dispatcher:
+        result = dispatcher.deliver("repo:pr:9", "head-1", "old")
+
+    assert result["disposition"] == "deduplicated"
+    conversation.send_message.assert_not_called()
+    conversation.run.assert_not_called()
+
+
+def test_new_delivery_resets_the_error_retry_count(monkeypatch):
+    state = {
+        _state_key("repo:pr:9"): {
+            "subject": "repo:pr:9",
+            "conversation_id": "22222222-2222-4222-8222-222222222222",
+            "delivery": "head-1",
+            "error_retries": agent_conversation._MAX_ERROR_RETRIES,
+        }
+    }
+    _fake_kv(monkeypatch, state)
+    conversation = _errored_local_conversation(monkeypatch)
+
+    with _dispatcher(monkeypatch) as dispatcher:
+        result = dispatcher.deliver("repo:pr:9", "head-2", "new")
+
+    assert result["disposition"] == "resumed"
+    conversation.send_message.assert_called_once_with("new")
+    assert "error_retries" not in state[_state_key("repo:pr:9")]
+
+
 def test_subjects_use_independent_kv_records(monkeypatch):
     state = {}
     _fake_kv(monkeypatch, state)
@@ -421,3 +506,48 @@ def test_cloud_run_replaces_a_conversation_whose_sandbox_is_gone(monkeypatch):
     [started] = cloud.started
     assert started["id"] != gone
     assert state[_state_key("repo:pr:7")]["conversation_id"] == started["id"]
+
+
+def test_cloud_run_retries_a_delivery_whose_conversation_errored(monkeypatch):
+    # Arrange
+    state = {
+        _state_key("repo:pr:7"): {
+            "conversation_id": "22222222-2222-4222-8222-222222222222",
+            "delivery": "revision-1",
+            "head": "sha-1",
+        }
+    }
+    _fake_kv(monkeypatch, state)
+    cloud = _FakeCloud({"sandbox_status": "RUNNING", "execution_status": "error"})
+
+    # Act
+    with _cloud_dispatcher(monkeypatch, cloud) as dispatcher:
+        result = dispatcher.deliver("repo:pr:7", "revision-1", "review it", head="sha-1")
+
+    # Assert
+    assert result["disposition"] == "retried"
+    assert cloud.sent == ["review it"]
+    assert cloud.started == []
+    assert state[_state_key("repo:pr:7")]["error_retries"] == 1
+
+
+def test_cloud_run_stops_retrying_an_errored_delivery_after_the_bound(monkeypatch):
+    # Arrange
+    state = {
+        _state_key("repo:pr:7"): {
+            "conversation_id": "22222222-2222-4222-8222-222222222222",
+            "delivery": "revision-1",
+            "head": "sha-1",
+            "error_retries": agent_conversation._MAX_ERROR_RETRIES,
+        }
+    }
+    _fake_kv(monkeypatch, state)
+    cloud = _FakeCloud({"sandbox_status": "RUNNING", "execution_status": "error"})
+
+    # Act
+    with _cloud_dispatcher(monkeypatch, cloud) as dispatcher:
+        result = dispatcher.deliver("repo:pr:7", "revision-1", "review it", head="sha-1")
+
+    # Assert
+    assert result["disposition"] == "deduplicated"
+    assert cloud.sent == []

package/tests/test_github_reviewer_delivery.py

@@ -17,9 +17,11 @@ def _reviews(
     submitted_at="2026-01-02T00:00:00Z",
     sha="head-2",
     login="all-hands-bot",
+    review_id=None,
 ):
     return [
         {
+            "id": review_id,
             "body": f"Review body\n\n{verdict}",
             "commit_id": sha,
             "submitted_at": submitted_at,
@@ -114,7 +116,9 @@ def _workflow_run(
     }
 
 
-def _event(monkeypatch, *, action="review_requested", login="all-hands-bot"):
+def _event(
+    monkeypatch, *, action="review_requested", login="all-hands-bot", review_id=None
+):
     payload = {
         "action": action,
         "repository": {"full_name": "owner/repo"},
@@ -124,6 +128,8 @@ def _event(monkeypatch, *, action="review_requested", login="all-hands-bot"):
         payload["requested_reviewer"] = {"login": login}
     else:
         payload["review"] = {"user": {"login": login}}
+        if review_id is not None:
+            payload["review"]["id"] = review_id
     monkeypatch.setenv(
         "AUTOMATION_EVENT_PAYLOAD",
         json.dumps({"automation_id": "automation", "event": {"payload": payload}}),
@@ -358,6 +364,191 @@ def test_reviewer_event_hands_positive_review_to_maintainer(tmp_path, monkeypatc
     run.dispatcher.deliver.assert_not_called()
 
 
+def test_reviewer_delayed_submitted_event_completes_prior_request(
+    tmp_path, monkeypatch
+):
+    """The review a submitted delivery reports can predate the latest
+    `review_requested` event, and it still completes that work."""
+    module, run = _reviewer(tmp_path, monkeypatch)
+    _event(monkeypatch, action="submitted", review_id=555)
+    run.config["maintainers"] = "neubig, VascoSch92"
+    pr = {"number": 2, "head": {"sha": "head-2"}, "labels": []}
+    request = {
+        "id": 42,
+        "event": "review_requested",
+        "created_at": "2026-01-03T00:00:00Z",
+        "requested_reviewer": {"login": "all-hands-bot"},
+    }
+    run.gh = Mock(side_effect=[{"id": 99}, pr, pr])
+    run.gh_pages = lambda path: (
+        [request]
+        if path.endswith("/events")
+        else _reviews(submitted_at="2026-01-01T00:00:00Z", review_id=555)
+    )
+    handoff = Mock(return_value="VascoSch92")
+    monkeypatch.setattr(module, "request_maintainer_review", handoff)
+
+    run.run()
+
+    handoff.assert_called_once_with(run, pr, ["neubig", "VascoSch92"])
+    run.dispatcher.deliver.assert_not_called()
+
+
+def test_reviewer_submitted_event_completes_without_request_event(
+    tmp_path, monkeypatch
+):
+    """A review whose request is outside the issue-event window still completes
+    through its own submitted delivery."""
+    module, run = _reviewer(tmp_path, monkeypatch)
+    _event(monkeypatch, action="submitted", review_id=555)
+    run.config["maintainers"] = "neubig"
+    pr = {"number": 2, "head": {"sha": "head-2"}, "labels": []}
+    run.gh = Mock(side_effect=[{"id": 99}, pr, pr])
+    run.gh_pages = lambda path: (
+        [] if path.endswith("/events") else _reviews(review_id=555)
+    )
+    handoff = Mock(return_value="neubig")
+    monkeypatch.setattr(module, "request_maintainer_review", handoff)
+
+    run.run()
+
+    handoff.assert_called_once_with(run, pr, ["neubig"])
+    run.dispatcher.deliver.assert_not_called()
+
+
+def test_reviewer_submitted_event_matches_only_the_reported_review(
+    tmp_path, monkeypatch
+):
+    """Another decisive review on the head is not the one the delivery reports."""
+    module, run = _reviewer(tmp_path, monkeypatch)
+    _event(monkeypatch, action="submitted", review_id=556)
+    run.config["maintainers"] = "neubig"
+    pr = {"number": 2, "head": {"sha": "head-2"}, "labels": []}
+    request = {
+        "id": 42,
+        "event": "review_requested",
+        "created_at": "2026-01-01T00:00:00Z",
+        "requested_reviewer": {"login": "all-hands-bot"},
+    }
+    run.gh = Mock(side_effect=[{"id": 99}, pr])
+    run.gh_pages = lambda path: (
+        [request] if path.endswith("/events") else _reviews(review_id=555)
+    )
+    handoff = Mock()
+    monkeypatch.setattr(module, "request_maintainer_review", handoff)
+
+    run.run()
+
+    handoff.assert_not_called()
+    run.dispatcher.deliver.assert_not_called()
+
+
+
+def test_reviewer_delayed_submitted_approval_yields_to_a_newer_verdict(
+    tmp_path, monkeypatch
+):
+    """A late delivery for an earlier approval does not hand off when this
+    account has since requested changes on the same head."""
+    module, run = _reviewer(tmp_path, monkeypatch)
+    _event(monkeypatch, action="submitted", review_id=555)
+    run.config["maintainers"] = "neubig"
+    pr = {"number": 2, "head": {"sha": "head-2"}, "labels": []}
+    request = {
+        "id": 42,
+        "event": "review_requested",
+        "created_at": "2026-01-03T00:00:00Z",
+        "requested_reviewer": {"login": "all-hands-bot"},
+    }
+    reviews = _reviews(submitted_at="2026-01-02T00:00:00Z", review_id=555) + _reviews(
+        verdict="🔄 CHANGES REQUESTED",
+        submitted_at="2026-01-04T00:00:00Z",
+        review_id=556,
+    )
+    run.gh = Mock(side_effect=[{"id": 99}, pr, pr])
+    run.gh_pages = lambda path: [request] if path.endswith("/events") else reviews
+    handoff = Mock()
+    monkeypatch.setattr(module, "request_maintainer_review", handoff)
+
+    run.run()
+
+    handoff.assert_not_called()
+    run.dispatcher.deliver.assert_not_called()
+
+
+def test_reviewer_submitted_event_ignores_a_dismissed_review(tmp_path, monkeypatch):
+    module, run = _reviewer(tmp_path, monkeypatch)
+    _event(monkeypatch, action="submitted", review_id=555)
+    run.config["maintainers"] = "neubig"
+    pr = {"number": 2, "head": {"sha": "head-2"}, "labels": []}
+    reviews = _reviews(review_id=555)
+    reviews[0]["state"] = "DISMISSED"
+    run.gh = Mock(side_effect=[{"id": 99}, pr, pr])
+    run.gh_pages = lambda path: [] if path.endswith("/events") else reviews
+    handoff = Mock()
+    monkeypatch.setattr(module, "request_maintainer_review", handoff)
+
+    run.run()
+
+    handoff.assert_not_called()
+    run.dispatcher.deliver.assert_not_called()
+
+def test_reviewer_delayed_submitted_event_without_roster_is_a_noop(
+    tmp_path, monkeypatch
+):
+    module, run = _reviewer(tmp_path, monkeypatch)
+    _event(monkeypatch, action="submitted", review_id=555)
+    pr = {"number": 2, "head": {"sha": "head-2"}, "labels": []}
+    request = {
+        "id": 42,
+        "event": "review_requested",
+        "created_at": "2026-01-03T00:00:00Z",
+        "requested_reviewer": {"login": "all-hands-bot"},
+    }
+    run.gh = Mock(side_effect=[{"id": 99}, pr, pr])
+    run.gh_pages = lambda path: (
+        [request]
+        if path.endswith("/events")
+        else _reviews(submitted_at="2026-01-01T00:00:00Z", review_id=555)
+    )
+    handoff = Mock()
+    monkeypatch.setattr(module, "request_maintainer_review", handoff)
+
+    run.run()
+
+    handoff.assert_not_called()
+    run.dispatcher.deliver.assert_not_called()
+
+
+def test_reviewer_subsequent_review_request_for_new_head_starts_new_review(
+    tmp_path, monkeypatch
+):
+    """A completed review of an earlier head does not swallow a later explicit
+    request once the head has moved."""
+    _module, run = _reviewer(tmp_path, monkeypatch)
+    _event(monkeypatch)
+    pr = {"number": 2, "head": {"sha": "head-3"}, "labels": []}
+    request = {
+        "id": 43,
+        "event": "review_requested",
+        "created_at": "2026-01-03T00:00:00Z",
+        "requested_reviewer": {"login": "all-hands-bot"},
+    }
+    run.gh = Mock(side_effect=[{"id": 99}, pr])
+    run.gh_pages = lambda path: (
+        [request]
+        if path.endswith("/events")
+        else _reviews(sha="head-2", submitted_at="2026-01-02T00:00:00Z", review_id=555)
+    )
+    run.dispatcher.deliver.return_value = {
+        "disposition": "created",
+        "conversation_id": "conversation",
+    }
+
+    run.run()
+
+    assert run.dispatcher.deliver.call_args.kwargs["delivery"] == "43:head-3"
+
+
 def test_reviewer_submitted_non_decisive_review_does_not_dispatch(
     tmp_path, monkeypatch
 ):
@@ -1088,6 +1279,38 @@ def test_reviewer_waits_for_a_workflow_run_that_has_not_finished(
     assert "`Tests`" in body
 
 
+
+def test_reviewer_waits_on_a_fork_workflow_run_awaiting_approval(
+    tmp_path, monkeypatch
+):
+    """On a fork head, GitHub parks the workflow run itself at action_required
+    and creates no check runs until a maintainer approves it."""
+    _module, run = _reviewer(tmp_path, monkeypatch)
+    pr = _labeled_pr()
+    run.gh_pages = _gate_pages(pr, [])
+    run.gh = Mock(side_effect=[{"id": 99}, pr, {"id": 1234}])
+    run.workflow_runs = lambda sha: [
+        _workflow_run(
+            "Tests",
+            "completed",
+            "action_required",
+            run_id=4,
+            suite_id=4004,
+            workflow_id=236324519,
+            sha=sha,
+        )
+    ]
+
+    run.run()
+
+    run.dispatcher.deliver.assert_not_called()
+    posted = [call for call in _gate_comment_calls(run) if call.args[0] == "POST"]
+    assert len(posted) == 1
+    body = posted[0].args[2]["body"]
+    assert "<!-- openhands-review-gate:waiting:head-2 -->" in body
+    assert "`Tests (awaiting maintainer approval)`" in body
+    assert "A maintainer needs to approve the workflow runs" in body
+
 def test_reviewer_ignores_workflow_runs_from_an_obsolete_head(
     tmp_path, monkeypatch
 ):
@@ -1372,7 +1595,9 @@ def test_reviewer_fails_closed_on_an_unknown_conclusion(tmp_path, monkeypatch):
     pr = _labeled_pr()
     run.gh_pages = _gate_pages(pr, [])
     run.gh = Mock(side_effect=[{"id": 99}, pr, {"id": 1234}])
-    run.check_runs = lambda sha: _checks(("mystery", "completed", "action_required"), sha=sha)
+    run.check_runs = lambda sha: _checks(
+        ("mystery", "completed", "some_new_conclusion"), sha=sha
+    )
 
     run.run()
 
@@ -1385,6 +1610,35 @@ def test_reviewer_fails_closed_on_an_unknown_conclusion(tmp_path, monkeypatch):
     assert "<!-- openhands-review-gate:blocked:head-2 -->" in body
 
 
+
+def test_reviewer_waits_on_a_run_awaiting_maintainer_approval(tmp_path, monkeypatch):
+    """A fork head parked at action_required is waiting on a maintainer.
+
+    GitHub sets this conclusion on a fork head's workflow runs until a
+    maintainer approves them. That is not a failure, and the explanation must
+    ask for the approval rather than say no action is needed.
+    """
+    _module, run = _reviewer(tmp_path, monkeypatch)
+    pr = _labeled_pr()
+    run.gh_pages = _gate_pages(pr, [])
+    run.gh = Mock(side_effect=[{"id": 99}, pr, {"id": 1234}])
+    run.check_runs = lambda sha: _checks(
+        ("tests", "completed", "action_required"), sha=sha
+    )
+
+    run.run()
+
+    run.dispatcher.deliver.assert_not_called()
+    body = [
+        call.args[2]["body"]
+        for call in _gate_comment_calls(run)
+        if call.args[0] == "POST"
+    ][0]
+    assert "<!-- openhands-review-gate:waiting:head-2 -->" in body
+    assert "`tests (awaiting maintainer approval)`" in body
+    assert "A maintainer needs to approve the workflow runs" in body
+    assert "No action is needed" not in body
+
 def test_reviewer_does_not_duplicate_the_gate_comment_for_the_same_head(
     tmp_path, monkeypatch
 ):
@@ -2792,3 +3046,26 @@ def test_scan_reads_every_pull_request_but_starts_only_the_quota(
     ]
     assert len(full_reads) == 40
     assert _examined(one) == [1, 2, 3, 4, 5]
+
+
+def test_a_retried_conversation_uses_a_launch_slot(tmp_path, monkeypatch):
+    """Retrying errored reviews must not bypass the per-scan launch bound."""
+    module = worker("github-pr-reviewer", tmp_path, monkeypatch)
+    intake = module.ReviewIntake()
+    started = []
+    for number in (1, 2, 3):
+        intake.register(
+            {
+                "priority": 1,
+                "created_at": f"2026-01-0{number}T00:00:00Z",
+                "repository": "owner/repo",
+                "number": number,
+                "config": {"max_new_per_run": 1},
+                "start": lambda number=number: started.append(number)
+                or {"disposition": "retried", "conversation_id": str(number)},
+            }
+        )
+
+    intake.drain()
+
+    assert started == [1]