hermes-agent/tests/agent/test_skill_commands.py

"""Tests for agent/skill_commands.py — skill slash command scanning and platform filtering."""

import os
from unittest.mock import patch

import pytest

import tools.skills_tool as skills_tool_module
from agent.skill_commands import (
    build_preloaded_skills_prompt,
    build_skill_invocation_message,
    resolve_skill_command_key,
    scan_skill_commands,
)


def _make_skill(
    skills_dir, name, frontmatter_extra="", body="Do the thing.", category=None
):
    """Helper to create a minimal skill directory with SKILL.md."""
    if category:
        skill_dir = skills_dir / category / name
    else:
        skill_dir = skills_dir / name
    skill_dir.mkdir(parents=True, exist_ok=True)
    content = f"""\
---
name: {name}
description: Description for {name}.
{frontmatter_extra}---

# {name}

{body}
"""
    (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
    return skill_dir


class TestScanSkillCommands:


    def test_loads_skill_invocation_from_symlinked_skill_dir(self, tmp_path):
        """Slash commands should load skills symlinked under the local skills dir."""
        external_root = tmp_path / "external"
        skills_root = tmp_path / "skills"
        skills_root.mkdir()
        real_skill_dir = _make_skill(
            external_root,
            "impeccable",
            body="Apply impeccable design craft.",
        )
        symlink_path = skills_root / "impeccable"
        try:
            symlink_path.symlink_to(real_skill_dir, target_is_directory=True)
        except (OSError, NotImplementedError) as exc:
            pytest.skip(f"symlinks unavailable in test environment: {exc}")

        with patch("tools.skills_tool.SKILLS_DIR", skills_root):
            result = scan_skill_commands()
            message = build_skill_invocation_message("/impeccable")

        assert "/impeccable" in result
        assert message is not None
        assert "Apply impeccable design craft." in message

    def test_get_skill_commands_rescans_when_platform_scope_changes(self, tmp_path):
        """Platform-specific disabled-skill caches must not leak across platforms.

        Regression test for #14536: a gateway process serving Telegram
        and Discord concurrently would seed the process-global cache
        with whichever platform scanned first, and subsequent
        ``get_skill_commands()`` calls from the other platform silently
        inherited that filter.
        """
        import agent.skill_commands as sc_mod
        from agent.skill_commands import get_skill_commands

        def _disabled_skills():
            platform = os.getenv("HERMES_PLATFORM")
            if platform == "telegram":
                return {"telegram-only"}
            if platform == "discord":
                return {"discord-only"}
            return set()

        with (
            patch("tools.skills_tool.SKILLS_DIR", tmp_path),
            patch("tools.skills_tool._get_disabled_skill_names", side_effect=_disabled_skills),
            patch.object(sc_mod, "_skill_commands_by_key", {}),
        ):
            _make_skill(tmp_path, "shared")
            _make_skill(tmp_path, "telegram-only")
            _make_skill(tmp_path, "discord-only")

            with patch.dict(os.environ, {"HERMES_PLATFORM": "telegram"}):
                telegram_commands = dict(get_skill_commands())

            assert "/shared" in telegram_commands
            assert "/discord-only" in telegram_commands
            assert "/telegram-only" not in telegram_commands

            with patch.dict(os.environ, {"HERMES_PLATFORM": "discord"}):
                discord_commands = dict(get_skill_commands())

            assert "/shared" in discord_commands
            assert "/telegram-only" in discord_commands
            assert "/discord-only" not in discord_commands

            # Switching back to telegram must also rescan — not re-serve
            # the discord view that was just cached.
            with patch.dict(os.environ, {"HERMES_PLATFORM": "telegram"}):
                telegram_again = dict(get_skill_commands())

            assert "/telegram-only" not in telegram_again
            assert "/discord-only" in telegram_again

    def test_get_skill_commands_rescans_when_session_platform_changes(self, tmp_path):
        """``HERMES_SESSION_PLATFORM`` from the gateway session context must
        also trigger a rescan, not just ``HERMES_PLATFORM`` (#14536).

        Exercises the real ContextVar path: the gateway sets the active
        adapter via ``set_session_vars(platform=...)`` and the resolver
        reads it via ``get_session_env``. Setting ``HERMES_SESSION_PLATFORM``
        in ``os.environ`` would only test ``get_session_env``'s legacy
        env-var fallback — a regression that swapped ``get_session_env``
        for plain ``os.getenv`` would still pass while breaking concurrent
        gateway sessions, which is the bug the ContextVar plumbing exists
        to prevent in the first place.
        """
        import agent.skill_commands as sc_mod
        from agent.skill_commands import get_skill_commands
        from gateway.session_context import (
            clear_session_vars,
            get_session_env,
            set_session_vars,
        )

        def _disabled_skills():
            platform = (
                os.getenv("HERMES_PLATFORM")
                or get_session_env("HERMES_SESSION_PLATFORM")
            )
            if platform == "telegram":
                return {"telegram-only"}
            if platform == "discord":
                return {"discord-only"}
            return set()

        with (
            patch("tools.skills_tool.SKILLS_DIR", tmp_path),
            patch("tools.skills_tool._get_disabled_skill_names", side_effect=_disabled_skills),
            patch.object(sc_mod, "_skill_commands_by_key", {}),
        ):
            _make_skill(tmp_path, "shared")
            _make_skill(tmp_path, "telegram-only")
            _make_skill(tmp_path, "discord-only")

            # First simulated gateway request: telegram handler.
            tokens = set_session_vars(platform="telegram")
            try:
                telegram_commands = dict(get_skill_commands())
            finally:
                clear_session_vars(tokens)

            assert "/shared" in telegram_commands
            assert "/discord-only" in telegram_commands
            assert "/telegram-only" not in telegram_commands

            # Second simulated gateway request: discord handler. The cache
            # was just populated for telegram; the rescan trigger must fire
            # off the ContextVar change, not just an env-var change.
            tokens = set_session_vars(platform="discord")
            try:
                discord_commands = dict(get_skill_commands())
            finally:
                clear_session_vars(tokens)

            assert "/shared" in discord_commands
            assert "/telegram-only" in discord_commands
            assert "/discord-only" not in discord_commands

    def test_get_skill_commands_rescans_when_profile_home_changes(self, tmp_path):
        """Switching profiles must rescan even when the platform is unchanged
        (#88023): a Desktop session that switches profiles mid-session keeps
        the same platform scope, so only ``HERMES_HOME`` moves. Each profile
        declares its own ``skills.external_dirs``, and the previous profile's
        skill list must not leak into the new one.
        """
        import agent.skill_commands as sc_mod
        from agent.skill_commands import get_skill_commands
        from hermes_constants import reset_hermes_home_override, set_hermes_home_override

        empty_local_dir = tmp_path / "no-local-skills"
        empty_local_dir.mkdir()

        profile_a = tmp_path / "profile_a"
        profile_b = tmp_path / "profile_b"
        external_a = tmp_path / "external_a"
        external_b = tmp_path / "external_b"
        profile_a.mkdir()
        profile_b.mkdir()
        _make_skill(external_a, "a-only")
        _make_skill(external_b, "b-only")
        (profile_a / "config.yaml").write_text(
            f"skills:\n  external_dirs:\n    - {external_a}\n"
        )
        (profile_b / "config.yaml").write_text(
            f"skills:\n  external_dirs:\n    - {external_b}\n"
        )

        with (
            patch("tools.skills_tool.SKILLS_DIR", empty_local_dir),
            patch.object(sc_mod, "_skill_commands_by_key", {}),
        ):
            token = set_hermes_home_override(profile_a)
            try:
                profile_a_commands = dict(get_skill_commands())
            finally:
                reset_hermes_home_override(token)

            assert "/a-only" in profile_a_commands
            assert "/b-only" not in profile_a_commands

            # Switching profiles without touching the cache directly must
            # rescan — not keep serving profile_a's stale view.
            token = set_hermes_home_override(profile_b)
            try:
                profile_b_commands = dict(get_skill_commands())
            finally:
                reset_hermes_home_override(token)

            assert "/b-only" in profile_b_commands
            assert "/a-only" not in profile_b_commands

    def test_get_skill_commands_scans_profile_skills_dir_not_frozen_import_dir(self, tmp_path):
        """Under a profile home override the scan must read <profile>/skills/,
        not the launch home's import-time ``SKILLS_DIR`` (#67277): a
        multiplexed webhook routed to profile B otherwise sees default's skills.
        Deliberately does NOT patch ``tools.skills_tool.SKILLS_DIR``.
        """
        import agent.skill_commands as sc_mod
        from agent.skill_commands import build_skill_invocation_message, get_skill_commands
        from hermes_constants import reset_hermes_home_override, set_hermes_home_override

        profile_b = tmp_path / "profiles" / "b"
        _make_skill(profile_b / "skills", "b-only", body="Body of b-only.")
        (profile_b / "config.yaml").write_text("{}\n", encoding="utf-8")

        with (
            patch.object(sc_mod, "_skill_commands_by_key", {}),
        ):
            token = set_hermes_home_override(profile_b)
            try:
                commands = dict(get_skill_commands())
                assert "/b-only" in commands
                # Frozen SKILLS_DIR (the launch home) must not leak in.
                launch_dir = str(skills_tool_module._SKILLS_DIR_AT_IMPORT)
                assert not any(
                    info["skill_dir"].startswith(launch_dir) for info in commands.values()
                )
                # And the absolute skill_dir round-trips through skill_view
                # (normalize_skill_lookup_name must use the same live root).
                msg = build_skill_invocation_message("/b-only", user_instruction="go")
            finally:
                reset_hermes_home_override(token)
        assert msg is not None and "Body of b-only." in msg

    def test_get_skill_commands_rescans_when_leaving_platform_scope(self, tmp_path, monkeypatch):
        """Returning to no-platform-scope (CLI / cron / RL) after a gateway
        session must rescan so the unfiltered view is repopulated (#14536).

        A long-lived process running both gateway sessions and bare CLI
        invocations would otherwise stay stuck on whichever platform's
        filter was last applied.
        """
        import agent.skill_commands as sc_mod
        from agent.skill_commands import get_skill_commands

        def _disabled_skills():
            if os.getenv("HERMES_PLATFORM") == "telegram":
                return {"telegram-only"}
            return set()

        with (
            patch("tools.skills_tool.SKILLS_DIR", tmp_path),
            patch("tools.skills_tool._get_disabled_skill_names", side_effect=_disabled_skills),
            patch.object(sc_mod, "_skill_commands_by_key", {}),
        ):
            _make_skill(tmp_path, "shared")
            _make_skill(tmp_path, "telegram-only")

            monkeypatch.setenv("HERMES_PLATFORM", "telegram")
            telegram_commands = dict(get_skill_commands())
            assert "/telegram-only" not in telegram_commands

            # Drop back to no platform scope — bare CLI / cron / RL rollouts.
            monkeypatch.delenv("HERMES_PLATFORM", raising=False)
            bare_commands = dict(get_skill_commands())

            assert "/telegram-only" in bare_commands
            # Platform cache is multi-slot now — just verify rescans happened


    # -- core-command collision guard (#31204 / #53450) ---------------------


    # -- inter-skill slug collision dedup (#50304 / #63305) ------------------

    def test_slug_collision_keeps_first_skill(self, tmp_path):
        """Two skills whose names normalize to the same slug do not clobber.

        ``git_helper`` and ``git-helper`` are distinct frontmatter names but
        both reduce to the ``/git-helper`` command. The first one scanned must
        keep the command rather than being silently overwritten by the second.
        """
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            # ``a-first`` sorts before ``z-second`` so the index walk visits the
            # underscore-named skill first; that one must win the slash command.
            first = tmp_path / "a-first"
            first.mkdir()
            (first / "SKILL.md").write_text(
                "---\nname: git_helper\ndescription: First skill.\n---\n\nBody.\n"
            )
            second = tmp_path / "z-second"
            second.mkdir()
            (second / "SKILL.md").write_text(
                "---\nname: git-helper\ndescription: Second skill.\n---\n\nBody.\n"
            )
            result = scan_skill_commands()
        assert "/git-helper" in result
        # First-wins: the entry resolves to the first skill, not the shadowing one.
        assert result["/git-helper"]["name"] == "git_helper"
        assert result["/git-helper"]["skill_dir"] == str(first)


    # -- concurrent scans (#74574) ------------------------------------------

    def test_concurrent_scans_do_not_report_skills_as_claiming_themselves(
        self, tmp_path, caplog
    ):
        """Two overlapping scans must not see each other's partial results.

        ``scan_skill_commands`` published into a module-global dict while it
        built, but deduped against a *local* ``seen_names``. A second scan
        starting mid-flight therefore found every slug already present and
        logged one "already claimed" warning per skill — each naming the very
        same skill as the incumbent. A gateway serving several platforms hits
        this on startup, flooding errors.log with one line per installed skill.
        """
        import logging as _logging
        import threading

        import tools.skills_tool as _skills_tool

        skill_count = 5
        for index in range(skill_count):
            _make_skill(tmp_path, f"skill-{index}")

        real_parse = _skills_tool._parse_frontmatter
        parked = threading.Event()
        other_scan_finished = threading.Event()
        already_parked = threading.local()

        def parking_parse(content):
            # Park the background scan once, before it has published anything,
            # so the foreground scan runs to completion underneath it.
            if (
                threading.current_thread().name == "parked-scan"
                and not getattr(already_parked, "done", False)
            ):
                already_parked.done = True
                parked.set()
                other_scan_finished.wait(timeout=10)
            return real_parse(content)

        with patch("tools.skills_tool.SKILLS_DIR", tmp_path), patch(
            "tools.skills_tool._parse_frontmatter", parking_parse
        ):
            with caplog.at_level(_logging.WARNING, logger="agent.skill_commands"):
                background = threading.Thread(
                    target=scan_skill_commands, name="parked-scan", daemon=True
                )
                background.start()
                assert parked.wait(timeout=10), "background scan never parked"

                foreground = scan_skill_commands()

                other_scan_finished.set()
                background.join(timeout=10)
                assert not background.is_alive()

        collisions = [r for r in caplog.records if "already claimed" in r.message]
        assert collisions == [], (
            "overlapping scans reported self-collisions: "
            f"{[r.getMessage() for r in collisions]}"
        )
        # Both scans still produce the full, correct map.
        assert len(foreground) == skill_count
        assert foreground["/skill-0"]["name"] == "skill-0"

    def test_publication_and_lookup_share_one_lock(self, tmp_path):
        """A reader must not land between the map and platform-tag writes.

        They are two separate global assignments. A reader in between sees the
        NEW map still carrying the OLD platform tag; if that stale tag matches
        its own platform it accepts the map without rescanning and serves
        another platform's disabled-skill view — the leak #14536 closed.
        Holding the publish lock must therefore block a reader outright.
        """
        import threading

        import agent.skill_commands as skill_commands_module
        from agent.skill_commands import get_skill_commands

        _make_skill(tmp_path, "shared")

        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            scan_skill_commands()

            done = threading.Event()

            def _read():
                with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
                    get_skill_commands()
                done.set()

            with skill_commands_module._publish_lock:
                reader = threading.Thread(target=_read, daemon=True)
                reader.start()
                # The reader must be unable to complete its freshness lookup
                # while publication is in progress.
                assert not done.wait(timeout=0.5), (
                    "get_skill_commands read the (map, platform) pair without "
                    "the publish lock"
                )

            assert done.wait(timeout=10), "reader did not finish after release"
            reader.join(timeout=10)

    def test_scan_never_publishes_a_partially_built_map(self, tmp_path):
        """A reader during a scan sees the previous map, never a half-built one."""

        import agent.skill_commands as skill_commands_module
        import tools.skills_tool as _skills_tool

        skill_count = 5
        for index in range(skill_count):
            _make_skill(tmp_path, f"skill-{index}")

        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            scan_skill_commands()

        real_parse = _skills_tool._parse_frontmatter
        observed_sizes = []

        def observing_parse(content):
            # Cache is now _skill_commands_by_key; count skill commands in the cached map (for this identity)
            key = (
                skill_commands_module._resolve_skill_commands_platform(),
                skill_commands_module._resolve_skill_commands_home(),
                skill_commands_module._resolve_skill_commands_project(),
            )
            cached_map = skill_commands_module._skill_commands_by_key.get(key, {})
            observed_sizes.append(len(cached_map))
            return real_parse(content)

        with patch("tools.skills_tool.SKILLS_DIR", tmp_path), patch(
            "tools.skills_tool._parse_frontmatter", observing_parse
        ):
            scan_skill_commands()

        # Every mid-scan observation shows the complete previous map, never a
        # partial one growing from 0.
        assert observed_sizes == [skill_count] * skill_count

    def test_non_ascii_name_registers_command(self, tmp_path):
        """A CJK skill name slugs to itself (punctuation still stripped) instead of "" and being
        silently dropped (#12351); ``resolve_skill_command_key`` round-trips it."""
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            skill_dir = tmp_path / "novel-clipper"
            skill_dir.mkdir()
            (skill_dir / "SKILL.md").write_text(
                "---\nname: 小说+拆条\ndescription: Split novels into clips.\n---\n\nBody.\n", encoding="utf-8"
            )
            result = scan_skill_commands()
            assert "/小说拆条" in result
            assert result["/小说拆条"]["name"] == "小说+拆条"
            assert resolve_skill_command_key("小说拆条") == "/小说拆条"


class TestResolveSkillCommandKey:
    """Telegram bot-command names disallow hyphens, so the menu registers
    skills with hyphens swapped for underscores. When Telegram autocomplete
    sends the underscored form back, we need to find the hyphenated key.
    """

    def test_hyphenated_form_matches_directly(self, tmp_path):
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            _make_skill(tmp_path, "claude-code")
            scan_skill_commands()
            assert resolve_skill_command_key("claude-code") == "/claude-code"


    def test_unknown_command_returns_none(self, tmp_path):
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            _make_skill(tmp_path, "claude-code")
            scan_skill_commands()
            assert resolve_skill_command_key("does_not_exist") is None
            assert resolve_skill_command_key("does-not-exist") is None


class TestBuildPreloadedSkillsPrompt:
    def test_builds_prompt_for_multiple_named_skills(self, tmp_path):
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            _make_skill(tmp_path, "first-skill")
            _make_skill(tmp_path, "second-skill")
            prompt, loaded, missing = build_preloaded_skills_prompt(
                ["first-skill", "second-skill"]
            )

        assert missing == []
        assert loaded == ["first-skill", "second-skill"]
        assert "first-skill" in prompt
        assert "second-skill" in prompt
        assert "preloaded" in prompt.lower()


    def test_skips_disabled_skill(self, tmp_path, monkeypatch):
        """A globally-disabled skill must not be force-loaded via -s /
        HERMES_TUI_SKILLS preloading (mirrors the bundle gate, #59156)."""
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            _make_skill(tmp_path, "enabled-skill", body="Enabled content.")
            _make_skill(tmp_path, "disabled-skill", body="SECRET DISABLED CONTENT.")

            import agent.skill_utils as su_module
            monkeypatch.setattr(
                su_module, "get_disabled_skill_names", lambda platform=None: {"disabled-skill"}
            )

            prompt, loaded, missing = build_preloaded_skills_prompt(
                ["enabled-skill", "disabled-skill"]
            )

        assert loaded == ["enabled-skill"]
        assert missing == ["disabled-skill"]
        assert "SECRET DISABLED CONTENT." not in prompt
        assert "enabled-skill" in prompt


class TestDuplicateNamesAgreeAcrossSurfaces:
    def test_every_surface_resolves_duplicates_like_skill_view(self, tmp_path, monkeypatch, caplog):
        """#64392: list, prompt index, slash commands, skill_view, -s preload and cron agree. A same-tier
        duplicate is advertised only by its exact path and every loader names those paths; a cross-tier
        duplicate (same relative path, local + external) loads the local copy everywhere."""
        import json

        from agent import prompt_builder as pb, skill_utils
        from cron.scheduler_prompt import _load_cron_skill_parts
        from tools.skills_tool import skill_view, skills_list
        local, ext = tmp_path / "local", tmp_path / "ext"
        _make_skill(local, "dup-demo", category="a", body="BODY A")
        (local / "a" / "dup-demo").rename(local / "a" / "one")
        _make_skill(local, "dup-demo", category="b", body="BODY B")
        (local / "b" / "dup-demo").rename(local / "b" / "two")
        _make_skill(local, "xdup", category="productivity", body="LOCAL XDUP")
        _make_skill(ext, "xdup", category="productivity", body="EXTERNAL XDUP")
        monkeypatch.setattr(skills_tool_module, "SKILLS_DIR", local)
        monkeypatch.setattr(skills_tool_module, "_SKILLS_CACHE", {})
        monkeypatch.setattr(skill_utils, "get_external_skills_dirs", lambda: [ext])
        monkeypatch.setattr(pb, "get_skills_dir", lambda: local)
        monkeypatch.setattr(pb, "get_disabled_skill_names", lambda *a, **k: set())
        monkeypatch.setattr(pb, "_skills_prompt_snapshot_path", lambda: tmp_path / "snap.json")
        pb.clear_skills_system_prompt_cache()

        ambiguous = "Ambiguous skill name dup-demo: use one of a/one, b/two"
        assert sorted(s["name"] for s in json.loads(skills_list())["skills"]) == ["a/one", "b/two", "xdup"]
        index = [ln.strip() for ln in pb.build_skills_system_prompt().splitlines() if ln.startswith("    - ")]
        assert index == ["- a/one: Description for dup-demo.", "- b/two: Description for dup-demo.",
                         "- xdup: Description for xdup."]
        assert sorted(scan_skill_commands()) == ["/xdup"]
        assert json.loads(skill_view("dup-demo"))["load_names"] == ["a/one", "b/two"]
        for ident in ("xdup", "productivity/xdup"):
            assert "LOCAL XDUP" in json.loads(skill_view(ident))["content"]
        _, loaded, missing = build_preloaded_skills_prompt(["dup-demo", "xdup", "a/one"])
        assert (loaded, missing) == (["xdup", "dup-demo"], [ambiguous])
        from hermes_cli.oneshot import _build_preloaded_skills_prompt
        with caplog.at_level("WARNING"):  # partial preload: the skip warning keeps the Ambiguous wording
            assert _build_preloaded_skills_prompt(["dup-demo", "xdup"])
        assert f"Skipping {ambiguous}. Continuing with: xdup" in caplog.text and "Unknown" not in caplog.text
        parts = _load_cron_skill_parts({"id": "j"}, ["dup-demo", "xdup"])
        assert ambiguous in parts[0] and "LOCAL XDUP" in "\n".join(parts)

        # Disabling a duplicate by the exact path its row shows (what `hermes skills` / the web toggle
        # save) hides it from list and index and refuses the load — but not an unrelated, uniquely named
        # skill in another tier that merely sits at the same relative path.
        _make_skill(ext, "other", category="a", body="UNRELATED OTHER")
        (ext / "a" / "other").rename(ext / "a" / "one")
        disabled = {"a/one"}
        monkeypatch.setattr(skill_utils, "get_disabled_skill_names", lambda *a, **k: disabled)
        monkeypatch.setattr(pb, "get_disabled_skill_names", lambda *a, **k: disabled)
        monkeypatch.setattr(skills_tool_module, "_is_skill_disabled", lambda *n, platform=None: not disabled.isdisjoint(n))
        monkeypatch.setattr(skills_tool_module, "_SKILLS_CACHE", {})
        pb.clear_skills_system_prompt_cache()
        assert sorted(s["name"] for s in json.loads(skills_list())["skills"]) == ["b/two", "other", "xdup"]
        index = [ln.strip() for ln in pb.build_skills_system_prompt().splitlines() if ln.startswith("    - ")]
        assert index == ["- other: Description for other.", "- b/two: Description for dup-demo.",
                         "- xdup: Description for xdup."]
        for ident in ("a/one", "one"):  # refused by any alias, as list/index hide it
            assert "disabled" in json.loads(skill_view(ident))["error"]
        assert "UNRELATED OTHER" in json.loads(skill_view("other"))["content"]
        assert build_preloaded_skills_prompt(["other"])[1:] == (["other"], [])
        # Still refused when that copy is also hidden at offer time (requires_apps).
        a_one = local / "a" / "one" / "SKILL.md"
        a_one.write_text(a_one.read_text().replace("---\n", "---\nrequires_apps: [no-such-app]\n", 1))
        monkeypatch.setattr(skills_tool_module, "_SKILLS_CACHE", {})
        for ident in ("a/one", "one"):
            assert "disabled" in json.loads(skill_view(ident))["error"]


class TestBuildSkillInvocationMessage:


    def test_uses_shared_skill_loader_for_secure_setup(self, tmp_path, monkeypatch):
        monkeypatch.delenv("TENOR_API_KEY", raising=False)
        calls = []

        def fake_secret_callback(var_name, prompt, metadata=None):
            calls.append((var_name, prompt, metadata))
            os.environ[var_name] = "stored-in-test"
            return {
                "success": True,
                "stored_as": var_name,
                "validated": False,
                "skipped": False,
            }

        monkeypatch.setattr(
            skills_tool_module,
            "_secret_capture_callback",
            fake_secret_callback,
            raising=False,
        )

        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            _make_skill(
                tmp_path,
                "test-skill",
                frontmatter_extra=(
                    "required_environment_variables:\n"
                    "  - name: TENOR_API_KEY\n"
                    "    prompt: Tenor API key\n"
                ),
            )
            scan_skill_commands()
            msg = build_skill_invocation_message("/test-skill", "do stuff")

        assert msg is not None
        assert "test-skill" in msg
        assert len(calls) == 1
        assert calls[0][0] == "TENOR_API_KEY"

    def test_gateway_still_loads_skill_but_returns_setup_guidance(
        self, tmp_path, monkeypatch
    ):
        monkeypatch.delenv("TENOR_API_KEY", raising=False)

        def fail_if_called(var_name, prompt, metadata=None):
            raise AssertionError(
                "gateway flow should not try secure in-band secret capture"
            )

        monkeypatch.setattr(
            skills_tool_module,
            "_secret_capture_callback",
            fail_if_called,
            raising=False,
        )

        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            from gateway.session_context import clear_session_vars, set_session_vars

            tokens = set_session_vars(platform="telegram")
            try:
                _make_skill(
                    tmp_path,
                    "test-skill",
                    frontmatter_extra=(
                        "required_environment_variables:\n"
                        "  - name: TENOR_API_KEY\n"
                        "    prompt: Tenor API key\n"
                    ),
                )
                scan_skill_commands()
                msg = build_skill_invocation_message("/test-skill", "do stuff")
            finally:
                clear_session_vars(tokens)

        assert msg is not None
        assert "local cli" in msg.lower()


class TestSkillDirectoryHeader:
    """The activation message must expose the absolute skill directory and
    explain how to resolve relative paths, so skills with bundled scripts
    don't force the agent into a second ``skill_view()`` round-trip."""

    def test_header_contains_absolute_skill_dir(self, tmp_path):
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            skill_dir = _make_skill(tmp_path, "abs-dir-skill")
            scan_skill_commands()
            msg = build_skill_invocation_message("/abs-dir-skill", "go")

        assert msg is not None
        assert str(skill_dir) in msg


class TestTemplateVarSubstitution:
    """``${HERMES_SKILL_DIR}`` and ``${HERMES_SESSION_ID}`` in SKILL.md body
    are replaced before the agent sees the content."""

    def test_substitutes_skill_dir(self, tmp_path):
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            skill_dir = _make_skill(
                tmp_path,
                "templated",
                body="Run: node ${HERMES_SKILL_DIR}/scripts/foo.js",
            )
            scan_skill_commands()
            msg = build_skill_invocation_message("/templated")

        assert msg is not None
        assert f"node {skill_dir}/scripts/foo.js" in msg
        # The literal template token must not leak through.
        assert "${HERMES_SKILL_DIR}" not in msg.split("[Skill directory:")[0]


    def test_disable_template_vars_via_config(self, tmp_path):
        with (
            patch("tools.skills_tool.SKILLS_DIR", tmp_path),
            patch(
                "agent.skill_commands._load_skills_config",
                return_value={"template_vars": False},
            ),
        ):
            _make_skill(
                tmp_path,
                "no-sub",
                body="Run: node ${HERMES_SKILL_DIR}/scripts/foo.js",
            )
            scan_skill_commands()
            msg = build_skill_invocation_message("/no-sub")

        assert msg is not None
        # Template token must survive when substitution is disabled.
        assert "${HERMES_SKILL_DIR}/scripts/foo.js" in msg


class TestInlineShellExpansion:
    """Inline ``!`cmd`` snippets in SKILL.md run before the agent sees the
    content — but only when the user has opted in via config."""


    @pytest.mark.platforms("linux")
    def test_inline_shell_runs_in_skill_directory(self, tmp_path):
        """Inline snippets get the skill dir as CWD so relative paths work."""
        with (
            patch("tools.skills_tool.SKILLS_DIR", tmp_path),
            patch(
                "agent.skill_commands._load_skills_config",
                return_value={"template_vars": True, "inline_shell": True,
                              "inline_shell_timeout": 5},
            ),
        ):
            skill_dir = _make_skill(
                tmp_path,
                "dyn-cwd",
                body="Here: !`pwd`",
            )
            scan_skill_commands()
            msg = build_skill_invocation_message("/dyn-cwd")

        assert msg is not None
        assert f"Here: {skill_dir}" in msg

    def test_inline_shell_timeout_does_not_break_message(self, tmp_path):
        with (
            patch("tools.skills_tool.SKILLS_DIR", tmp_path),
            patch(
                "agent.skill_commands._load_skills_config",
                return_value={"template_vars": True, "inline_shell": True,
                              "inline_shell_timeout": 1},
            ),
        ):
            _make_skill(
                tmp_path,
                "dyn-slow",
                body="Slow: !`sleep 5 && printf DYN_MARKER`",
            )
            scan_skill_commands()
            msg = build_skill_invocation_message("/dyn-slow")

        assert msg is not None
        # Timeout is surfaced as a marker instead of propagating as an error,
        # and the rest of the skill message still renders.
        assert "inline-shell timeout" in msg
        # The command's intended stdout never made it through — only the
        # timeout marker (which echoes the command text) survives.
        assert "DYN_MARKER" not in msg.replace("sleep 5 && printf DYN_MARKER", "")


class TestStackedSkillCommands:
    """Stacked slash-skill invocations — inspired by Claude Code v2.1.199."""

    def _setup_three_skills(self, tmp_path):
        _make_skill(tmp_path, "skill-a", body="Body A.")
        _make_skill(tmp_path, "skill-b", body="Body B.")
        _make_skill(tmp_path, "skill-c", body="Body C.")


    def test_split_stops_at_non_skill_token(self, tmp_path):
        from agent.skill_commands import split_stacked_skill_commands
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            self._setup_three_skills(tmp_path)
            scan_skill_commands()
            keys, instruction = split_stacked_skill_commands(
                "/skill-b /not-a-skill /skill-c hello"
            )
        assert keys == ["/skill-b"]
        # Parsing stops at the first unresolvable token; everything from
        # there on is the user instruction (slash included).
        assert instruction == "/not-a-skill /skill-c hello"


    def test_split_caps_at_five_total(self, tmp_path):
        from agent.skill_commands import split_stacked_skill_commands
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            for i in range(7):
                _make_skill(tmp_path, f"stk-{i}")
            scan_skill_commands()
            rest = " ".join(f"/stk-{i}" for i in range(1, 7)) + " run"
            keys, instruction = split_stacked_skill_commands(rest)
        # First skill was already consumed by the caller — split returns at
        # most 4 extras so the total stays at 5.
        assert len(keys) == 4
        assert instruction.startswith("/stk-5")


    def test_stacked_message_skips_missing_skills(self, tmp_path):
        from agent.skill_commands import build_stacked_skill_invocation_message
        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
            self._setup_three_skills(tmp_path)
            scan_skill_commands()
            result = build_stacked_skill_invocation_message(
                ["/skill-a", "/gone"], "go"
            )
        assert result is not None
        msg, loaded, missing = result
        assert loaded == ["skill-a"]
        assert missing == ["gone"]
        assert "gone" in msg