@openhands/extensions 0.2.0 → 0.4.0

package/skills/openhands-sdk/SKILL.md

@@ -189,6 +189,7 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`49_switch_llm_tool.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/49_switch_llm_tool.py)
 - [`50_async_cancellation.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/50_async_cancellation.py)
 - [`51_agent_hooks`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/51_agent_hooks)
+- [`52_dynamic_workflow.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/52_dynamic_workflow.py)
 
 ### [`02_remote_agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server)
 

package/skills/slack-channel-monitor/README.md

@@ -66,7 +66,8 @@ The skill will:
 1. Verify your Slack token is available
 2. Resolve channel names to IDs
 3. Confirm the trigger phrase (or use the default `@openhands`)
-4. Generate and upload a customised automation script
+4. Generate and upload a customised automation script by copying the template
+   and changing only the configuration constants
 5. Create the automation with cron schedule `* * * * *`
 
 ## How It Works

package/skills/slack-channel-monitor/SKILL.md

@@ -119,8 +119,13 @@ Accepted values: any non-empty string unlikely to appear accidentally, e.g.
 
 ### Step 3  -  Generate the automation script
 
-Read `scripts/main.py` from this skill's directory. Apply exactly three
-constant substitutions near the top of the file:
+Read `scripts/main.py` from this skill's directory and **copy it verbatim**.
+Apply exactly three constant substitutions near the top of the file:
+
+> **Do not reimplement, simplify, or hand-write a replacement script.**
+> The template already contains the correct secret-loading, state-path,
+> conversation-creation, and context-forwarding logic. Only the three
+> configuration constants below should change unless syntax validation fails.
 
 | Placeholder | Replace with |
 |---|---|
@@ -131,7 +136,8 @@ constant substitutions near the top of the file:
 Write the customised script to a temporary directory:
 ```bash
 mkdir -p /tmp/slack-monitor-build
-# (write the customised main.py to /tmp/slack-monitor-build/main.py)
+# copy scripts/main.py to /tmp/slack-monitor-build/main.py
+# then replace only the three constants above
 ```
 
 Validate syntax before packaging:
@@ -139,7 +145,19 @@ Validate syntax before packaging:
 python3 -m py_compile /tmp/slack-monitor-build/main.py && echo "Syntax OK"
 ```
 
-Fix any syntax errors before proceeding.
+Then run a quick integrity check to confirm the template structure is still
+present and only the configuration block was customised:
+```bash
+grep -n 'TRIGGER_PHRASE = "' /tmp/slack-monitor-build/main.py
+grep -n 'CHANNEL_IDS: list\[str\] =' /tmp/slack-monitor-build/main.py
+grep -n 'DEFAULT_OPENHANDS_URL = "' /tmp/slack-monitor-build/main.py
+grep -n 'def get_secret' /tmp/slack-monitor-build/main.py
+grep -n 'def _state_file_path' /tmp/slack-monitor-build/main.py
+grep -n 'def create_conversation' /tmp/slack-monitor-build/main.py
+```
+
+If any of those checks fail, stop and re-copy the template instead of trying to
+repair a hand-written variant.
 
 ### Step 4  -  Package and upload
 

package/tests/test_github_pr_review_skill.py

@@ -0,0 +1,114 @@
+"""Tests for the github-pr-review skill content.
+
+These tests guard the guidance the agent reads when it builds a GitHub review
+with inline suggestions. The skill must teach the agent how GitHub
+``suggestion`` blocks actually behave (range replacement), so accepted
+suggestions don't silently duplicate or delete lines, and so the prose
+description always matches the resulting change.
+
+See: https://github.com/OpenHands/extensions/issues/292
+"""
+
+from pathlib import Path
+
+import pytest
+
+SKILL_PATH = (
+    Path(__file__).parent.parent / "skills" / "github-pr-review" / "SKILL.md"
+)
+
+
+@pytest.fixture(scope="module")
+def skill_text() -> str:
+    return SKILL_PATH.read_text(encoding="utf-8")
+
+
+def test_skill_file_exists():
+    assert SKILL_PATH.is_file(), f"missing skill file: {SKILL_PATH}"
+
+
+def test_skill_does_not_claim_suggestion_must_match_range_length(skill_text: str):
+    """Regression: the old "same number of lines as the range" rule was wrong.
+
+    GitHub replaces the targeted range with the suggestion body regardless of
+    how many lines the body contains. Telling the agent the counts must match
+    pushed it to either delete lines (when shrinking a block) or duplicate
+    lines (when expanding one), depending on which side it adjusted to satisfy
+    the bogus rule. The skill must no longer state that constraint.
+    """
+    forbidden_phrases = [
+        "suggestion must have the same number of lines as the range",
+        "must have the same number of lines as the range",
+    ]
+    for phrase in forbidden_phrases:
+        assert phrase not in skill_text, (
+            f"SKILL.md still contains the misleading rule {phrase!r}; "
+            "GitHub suggestions replace the range with any number of lines."
+        )
+
+
+def test_skill_explains_replace_semantics(skill_text: str):
+    """The skill must say in plain language that suggestions REPLACE the range."""
+    assert "How Suggestions Actually Work" in skill_text
+    # Mention replacement explicitly so the agent does not treat the suggestion
+    # body as "extra lines added on top of the original".
+    lowered = skill_text.lower()
+    assert "replace" in lowered
+    assert "any number of lines" in lowered
+
+
+def test_skill_covers_add_remove_change_patterns(skill_text: str):
+    """The skill should give explicit recipes for the three intents that
+    most commonly produced broken suggestions: changing, adding, and
+    deleting lines. Without these, the agent invents wrong patterns.
+    """
+    for keyword in ("Change line", "Add", "Delete"):
+        assert keyword in skill_text, (
+            f"SKILL.md is missing guidance for intent {keyword!r}; "
+            "see issue #292."
+        )
+
+
+def test_skill_warns_about_duplicated_and_deleted_lines(skill_text: str):
+    """The skill must call out the two failure modes from issue #292:
+    accepted suggestions that duplicate or remove lines."""
+    lowered = skill_text.lower()
+    assert "duplicat" in lowered, (
+        "SKILL.md should warn about suggestions that duplicate lines."
+    )
+    # "disappear"/"disappearing" is unique to the failure-mode description in
+    # the "Common Mistakes" section. The generic terms "delete" and "remove"
+    # also appear in the recipe table for intentional deletions, so checking
+    # for those would let the failure-mode guidance be removed silently.
+    assert "disappear" in lowered, (
+        "SKILL.md should warn about suggestions that silently drop lines "
+        "(see 'Disappearing lines' under Common Mistakes)."
+    )
+
+
+def test_skill_requires_description_to_match_suggestion(skill_text: str):
+    """The skill must explicitly require the prose description to match the
+    actual code change in the suggestion block (the third bug from #292)."""
+    lowered = skill_text.lower()
+    assert any(phrase in lowered for phrase in ("description does not match", "prose description", "description must match"))
+    # The text should connect the description to the resulting code change.
+    assert (
+        "match" in lowered
+    ), "SKILL.md should say the description must match the change."
+
+
+def test_skill_has_pre_post_verification_step(skill_text: str):
+    """Before posting, the agent must verify the suggestion against the file."""
+    assert "Mandatory Verification" in skill_text or "Verification" in skill_text
+    # Should point the agent at the real file content, not just the diff.
+    assert "sed -n" in skill_text or "read the actual file" in skill_text.lower()
+
+
+def test_skill_offers_prose_fallback(skill_text: str):
+    """When unsure, the agent should drop the suggestion block and use prose
+    instead — a correct comment beats a broken one-click fix."""
+    lowered = skill_text.lower()
+    assert "prose" in lowered, (
+        "SKILL.md should tell the agent to fall back to a prose comment "
+        "when the suggestion cannot be verified."
+    )

package/tests/test_skills_catalog.py

@@ -0,0 +1,336 @@
+"""Tests for the skills catalog codegen (scripts/build-skills-catalog.mjs).
+
+Covers:
+- parseFrontmatter edge cases (hyphenated keys, multiline, list items, etc.)
+- End-to-end buildCatalog against temp fixtures
+- Generated skills/index.js validity and structure
+- Determinism: re-running the script produces identical output
+"""
+
+import json
+import subprocess
+import textwrap
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = ROOT / "scripts" / "build-skills-catalog.mjs"
+SKILLS_INDEX = ROOT / "skills" / "index.js"
+
+
+def run_node(script: str, *, cwd: str | Path = ROOT, check: bool = True) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["node", "--input-type=module", "-e", script],
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        check=check,
+    )
+
+
+# ---------------------------------------------------------------------------
+# parseFrontmatter unit tests (via Node subprocess)
+# ---------------------------------------------------------------------------
+
+class TestParseFrontmatter:
+    """Unit tests for parseFrontmatter, exercised via Node import."""
+
+    def _parse(self, frontmatter_body: str) -> dict:
+        """Run parseFrontmatter on *frontmatter_body* and return the result."""
+        escaped = json.dumps(frontmatter_body)
+        script = textwrap.dedent(f"""\
+            import {{ parseFrontmatter }} from './scripts/build-skills-catalog.mjs';
+            const result = parseFrontmatter({escaped});
+            process.stdout.write(JSON.stringify(result));
+        """)
+        result = run_node(script)
+        return json.loads(result.stdout)
+
+    def test_simple_key_value(self):
+        fm = self._parse("name: my-skill\ndescription: A test skill")
+        assert fm["name"] == "my-skill"
+        assert fm["description"] == "A test skill"
+
+    def test_hyphenated_keys(self):
+        fm = self._parse("name: my-skill\ncompatibility: works-everywhere")
+        assert fm["compatibility"] == "works-everywhere"
+
+    def test_hyphenated_key_not_silently_dropped(self):
+        """Keys like event-key: should be parsed, not ignored."""
+        # We verify indirectly: if a hyphenated key precedes a list,
+        # the list items must be collected under that key.
+        script = textwrap.dedent("""\
+            import { parseFrontmatter } from './scripts/build-skills-catalog.mjs';
+            // parseFrontmatter returns a fixed shape, so test the internal
+            // parsing by checking a known hyphenated output key.
+            const fm = parseFrontmatter("license: MIT");
+            // Also verify a raw parse captures hyphenated keys internally
+            // by re-implementing a quick check:
+            const raw = "event-key: hello";
+            const match = raw.match(/^[\\w-]+:\\s*(.*)/);
+            if (!match) { console.error("Regex failed for hyphenated key"); process.exit(1); }
+            process.stdout.write("ok");
+        """)
+        result = run_node(script)
+        assert result.stdout == "ok"
+
+    def test_list_items(self):
+        fm = self._parse("name: test\ntriggers:\n- github\n- git\n- pull request")
+        assert fm["triggers"] == ["github", "git", "pull request"]
+
+    def test_empty_triggers_when_scalar(self):
+        fm = self._parse("name: test\ntriggers: not-a-list")
+        assert fm["triggers"] == []
+
+    def test_multiline_description_folded(self):
+        fm = self._parse("name: test\ndescription: >\n  This is a long\n  description text")
+        assert "This is a long" in fm["description"]
+        assert "description text" in fm["description"]
+
+    def test_multiline_description_literal(self):
+        fm = self._parse("name: test\ndescription: |\n  Line one\n  Line two")
+        assert "Line one" in fm["description"]
+        assert "Line two" in fm["description"]
+
+    def test_missing_name_returns_empty(self):
+        fm = self._parse("description: no name here")
+        assert fm["name"] == ""
+
+    def test_missing_description_returns_empty(self):
+        fm = self._parse("name: test")
+        assert fm["description"] == ""
+        assert fm["triggers"] == []
+
+    def test_optional_fields_omitted_when_absent(self):
+        fm = self._parse("name: test\ndescription: desc")
+        assert "license" not in fm
+        assert "compatibility" not in fm
+
+    def test_optional_fields_present_when_set(self):
+        fm = self._parse("name: test\nlicense: MIT\ncompatibility: all platforms")
+        assert fm["license"] == "MIT"
+        assert fm["compatibility"] == "all platforms"
+
+    def test_empty_input(self):
+        fm = self._parse("")
+        assert fm["name"] == ""
+        assert fm["description"] == ""
+        assert fm["triggers"] == []
+
+
+# ---------------------------------------------------------------------------
+# End-to-end codegen tests with temp fixtures (using buildCatalog)
+# ---------------------------------------------------------------------------
+
+class TestCodegenEndToEnd:
+    """Run buildCatalog against temp SKILL.md fixtures."""
+
+    def _run_codegen(self, tmp_path: Path, skills: dict[str, str]) -> list[dict]:
+        """Create temp skill dirs, run buildCatalog, return parsed catalog."""
+        skills_dir = tmp_path / "skills"
+        skills_dir.mkdir()
+
+        for name, content in skills.items():
+            skill_dir = skills_dir / name
+            skill_dir.mkdir()
+            (skill_dir / "SKILL.md").write_text(content)
+
+        script = textwrap.dedent(f"""\
+            import {{ buildCatalog }} from './scripts/build-skills-catalog.mjs';
+            const entries = buildCatalog({json.dumps(str(skills_dir))});
+            process.stdout.write(JSON.stringify(entries));
+        """)
+        result = run_node(script)
+        return json.loads(result.stdout)
+
+    def test_basic_skill(self, tmp_path):
+        entries = self._run_codegen(tmp_path, {
+            "my-skill": "---\nname: my-skill\ndescription: A skill\ntriggers:\n- test\n---\nBody content here"
+        })
+        assert len(entries) == 1
+        assert entries[0]["name"] == "my-skill"
+        assert entries[0]["description"] == "A skill"
+        assert entries[0]["triggers"] == ["test"]
+        assert entries[0]["content"] == "Body content here"
+
+    def test_name_falls_back_to_directory(self, tmp_path):
+        entries = self._run_codegen(tmp_path, {
+            "fallback-dir": "---\ndescription: no name field\n---\nBody"
+        })
+        assert entries[0]["name"] == "fallback-dir"
+
+    def test_missing_frontmatter_skipped(self, tmp_path):
+        entries = self._run_codegen(tmp_path, {
+            "good-skill": "---\nname: good\ndescription: yes\n---\nBody",
+            "bad-skill": "No frontmatter delimiters at all",
+        })
+        assert len(entries) == 1
+        assert entries[0]["name"] == "good"
+
+    def test_missing_frontmatter_warns(self, tmp_path):
+        """SKILL.md without frontmatter should produce a stderr warning."""
+        skills_dir = tmp_path / "skills"
+        skills_dir.mkdir()
+        (skills_dir / "bad").mkdir()
+        (skills_dir / "bad" / "SKILL.md").write_text("No frontmatter here")
+
+        script = textwrap.dedent(f"""\
+            import {{ buildCatalog }} from './scripts/build-skills-catalog.mjs';
+            buildCatalog({json.dumps(str(skills_dir))});
+        """)
+        result = run_node(script)
+        assert "Warning" in result.stderr
+        assert "missing frontmatter" in result.stderr
+
+    def test_body_with_triple_dashes_preserved(self, tmp_path):
+        content = "---\nname: test\ndescription: d\n---\nBefore\n---\nAfter"
+        entries = self._run_codegen(tmp_path, {"test-skill": content})
+        assert "---" in entries[0]["content"]
+        assert "Before" in entries[0]["content"]
+        assert "After" in entries[0]["content"]
+
+    def test_generated_file_is_valid_js(self, tmp_path):
+        """Write a catalog to a file and verify it's importable as JS."""
+        skills_dir = tmp_path / "skills"
+        skills_dir.mkdir()
+        for name in ("alpha", "beta"):
+            (skills_dir / name).mkdir()
+            (skills_dir / name / "SKILL.md").write_text(
+                f"---\nname: {name}\ndescription: {name} desc\n---\nBody {name}"
+            )
+
+        output = tmp_path / "output.js"
+        script = textwrap.dedent(f"""\
+            import {{ writeFileSync }} from "node:fs";
+            import {{ buildCatalog }} from './scripts/build-skills-catalog.mjs';
+            const entries = buildCatalog({json.dumps(str(skills_dir))});
+            const src = "export const SKILLS_CATALOG = " + JSON.stringify(entries) + ";\\nexport default SKILLS_CATALOG;\\n";
+            writeFileSync({json.dumps(str(output))}, src);
+        """)
+        run_node(script)
+
+        verify = textwrap.dedent(f"""\
+            const mod = await import({json.dumps(str(output))});
+            if (!Array.isArray(mod.SKILLS_CATALOG)) process.exit(1);
+            if (mod.SKILLS_CATALOG.length !== 2) process.exit(1);
+            if (mod.default !== mod.SKILLS_CATALOG) process.exit(1);
+        """)
+        run_node(verify)
+
+    def test_entries_sorted_by_directory_name(self, tmp_path):
+        entries = self._run_codegen(tmp_path, {
+            "zebra": "---\nname: zebra\ndescription: z\n---\nZ",
+            "alpha": "---\nname: alpha\ndescription: a\n---\nA",
+            "middle": "---\nname: middle\ndescription: m\n---\nM",
+        })
+        names = [e["name"] for e in entries]
+        assert names == ["alpha", "middle", "zebra"]
+
+    def test_optional_fields_included_when_present(self, tmp_path):
+        entries = self._run_codegen(tmp_path, {
+            "lic": "---\nname: lic\ndescription: d\nlicense: MIT\ncompatibility: all\n---\nBody"
+        })
+        assert entries[0]["license"] == "MIT"
+        assert entries[0]["compatibility"] == "all"
+
+    def test_optional_fields_omitted_when_absent(self, tmp_path):
+        entries = self._run_codegen(tmp_path, {
+            "bare": "---\nname: bare\ndescription: d\n---\nBody"
+        })
+        assert "license" not in entries[0]
+        assert "compatibility" not in entries[0]
+
+    def test_directories_without_skill_md_ignored(self, tmp_path):
+        skills_dir = tmp_path / "skills"
+        skills_dir.mkdir()
+        (skills_dir / "has-skill").mkdir()
+        (skills_dir / "has-skill" / "SKILL.md").write_text("---\nname: ok\ndescription: d\n---\nBody")
+        (skills_dir / "no-skill").mkdir()  # no SKILL.md
+
+        script = textwrap.dedent(f"""\
+            import {{ buildCatalog }} from './scripts/build-skills-catalog.mjs';
+            const entries = buildCatalog({json.dumps(str(skills_dir))});
+            process.stdout.write(JSON.stringify(entries));
+        """)
+        result = run_node(script)
+        entries = json.loads(result.stdout)
+        assert len(entries) == 1
+        assert entries[0]["name"] == "ok"
+
+
+# ---------------------------------------------------------------------------
+# Generated skills/index.js validation (real repo data)
+# ---------------------------------------------------------------------------
+
+class TestGeneratedSkillsIndex:
+    """Validate the checked-in skills/index.js against the live SKILL.md files."""
+
+    def test_index_js_is_valid_and_exports_array(self):
+        """The generated skills/index.js is valid JS with a non-empty array export."""
+        script = textwrap.dedent("""\
+            import { SKILLS_CATALOG } from './skills/index.js';
+            if (!Array.isArray(SKILLS_CATALOG)) process.exit(1);
+            if (SKILLS_CATALOG.length === 0) process.exit(1);
+            import SKILLS from './skills/index.js';
+            if (SKILLS !== SKILLS_CATALOG) process.exit(1);
+        """)
+        run_node(script)
+
+    def test_every_entry_has_required_fields(self):
+        """Each catalog entry must have name, description, triggers, and content."""
+        script = textwrap.dedent("""\
+            import { SKILLS_CATALOG } from './skills/index.js';
+            for (const entry of SKILLS_CATALOG) {
+              if (typeof entry.name !== 'string' || !entry.name) {
+                console.error('Missing name:', JSON.stringify(entry).slice(0, 100));
+                process.exit(1);
+              }
+              if (typeof entry.description !== 'string') {
+                console.error('Missing description for:', entry.name);
+                process.exit(1);
+              }
+              if (!Array.isArray(entry.triggers)) {
+                console.error('Missing triggers for:', entry.name);
+                process.exit(1);
+              }
+              if (typeof entry.content !== 'string') {
+                console.error('Missing content for:', entry.name);
+                process.exit(1);
+              }
+            }
+        """)
+        run_node(script)
+
+    def test_no_duplicate_names(self):
+        """Skill names should be unique in the catalog."""
+        script = textwrap.dedent("""\
+            import { SKILLS_CATALOG } from './skills/index.js';
+            const names = SKILLS_CATALOG.map(e => e.name);
+            const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+            if (dupes.length > 0) {
+              console.error('Duplicate names:', dupes);
+              process.exit(1);
+            }
+        """)
+        run_node(script)
+
+    def test_catalog_is_sorted(self):
+        """Entries should be sorted alphabetically by name."""
+        script = textwrap.dedent("""\
+            import { SKILLS_CATALOG } from './skills/index.js';
+            const names = SKILLS_CATALOG.map(e => e.name);
+            const sorted = [...names].sort();
+            for (let i = 0; i < names.length; i++) {
+              if (names[i] !== sorted[i]) {
+                console.error('Not sorted: ' + names[i] + ' should be ' + sorted[i]);
+                process.exit(1);
+              }
+            }
+        """)
+        run_node(script)
+
+    def test_index_is_up_to_date(self):
+        """Re-running the codegen script should produce identical output."""
+        before = SKILLS_INDEX.read_text()
+        subprocess.run(["node", str(SCRIPT)], cwd=str(ROOT), check=True, capture_output=True)
+        after = SKILLS_INDEX.read_text()
+        assert before == after, "skills/index.js is out of date — run: node scripts/build-skills-catalog.mjs"

package/tests/test_sync_extensions.py

@@ -198,6 +198,20 @@ class TestCollectNeededCommands:
             assert spec.path.parent.name == "commands"
             assert spec.path.suffix == ".md"
 
+    def test_colon_triggers_are_normalized_for_filenames(self, tmp_path, monkeypatch):
+        skill_dir = tmp_path / "skills" / "test-skill"
+        skill_dir.mkdir(parents=True)
+        (skill_dir / "SKILL.md").write_text(
+            "---\nname: test-skill\ndescription: Test\ntriggers:\n  - /test:command\n---\nBody\n"
+        )
+
+        monkeypatch.setattr("sync_extensions.SKILL_DIRS", [tmp_path / "skills"])
+
+        specs = collect_needed_commands()
+        assert [spec.path.relative_to(tmp_path).as_posix() for spec in specs] == [
+            "skills/test-skill/commands/test-command.md"
+        ]
+
 
 # ── load_marketplaces ────────────────────────────────────────────────