@ngocsangairvds/vsaf 4.0.6 → 4.0.8

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/unit/test_provider.py

@@ -0,0 +1,316 @@
+"""Tests for vds_agent_core.llm.provider."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from pydantic import BaseModel
+from vds_agent_core.llm.provider import (
+    HttpxDirectClient,
+    LiteLLMClient,
+    LLMSettings,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _SampleSchema(BaseModel):
+    answer: str
+    score: float
+
+
+# ---------------------------------------------------------------------------
+# Protocol structural conformance
+# ---------------------------------------------------------------------------
+
+
+def test_litellm_client_satisfies_protocol() -> None:
+    """LiteLLMClient structurally conforms to LLMClient Protocol."""
+    client = LiteLLMClient()
+    assert hasattr(client, "chat")
+    assert hasattr(client, "chat_json")
+    # Verify async callables
+    assert inspect.iscoroutinefunction(client.chat)
+    assert inspect.iscoroutinefunction(client.chat_json)
+
+
+def test_httpx_client_satisfies_protocol() -> None:
+    """HttpxDirectClient structurally conforms to LLMClient Protocol."""
+    client = HttpxDirectClient()
+    assert hasattr(client, "chat")
+    assert hasattr(client, "chat_json")
+    assert inspect.iscoroutinefunction(client.chat)
+    assert inspect.iscoroutinefunction(client.chat_json)
+
+
+# ---------------------------------------------------------------------------
+# LLMSettings — instantiation and select_model
+# ---------------------------------------------------------------------------
+
+
+def test_llm_settings_defaults(monkeypatch: pytest.MonkeyPatch) -> None:
+    """LLMSettings loads with sane defaults."""
+    # Clear any env vars that might interfere
+    monkeypatch.delenv("VDS_AGENT_CORE__API_KEY", raising=False)
+    monkeypatch.delenv("VDS_AGENT_CORE__BASE_URL", raising=False)
+    settings = LLMSettings()
+    assert settings.model_standard == "gpt-4o-mini"
+    assert settings.model_complex == "gpt-4o"
+
+
+def test_select_model_tiers(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("VDS_AGENT_CORE__API_KEY", raising=False)
+    settings = LLMSettings()
+    assert settings.select_model("simple") == settings.model_simple
+    assert settings.select_model("standard") == settings.model_standard
+    assert settings.select_model("complex") == settings.model_complex
+
+
+def test_select_model_unknown_tier_falls_back(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("VDS_AGENT_CORE__API_KEY", raising=False)
+    settings = LLMSettings()
+    assert settings.select_model("nonexistent") == settings.model_standard
+
+
+# ---------------------------------------------------------------------------
+# build_client — litellm available vs not
+# ---------------------------------------------------------------------------
+
+
+def test_build_client_returns_httpx_when_litellm_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("VDS_AGENT_CORE__API_KEY", raising=False)
+    settings = LLMSettings(base_url="https://example.com/v1", api_key="test-key")
+
+    with patch.dict("sys.modules", {"litellm": None}):
+        # Force ImportError on litellm
+        import builtins
+
+        real_import = builtins.__import__
+
+        def mock_import(name: str, *args: Any, **kwargs: Any) -> Any:
+            if name == "litellm":
+                raise ImportError("mocked")
+            return real_import(name, *args, **kwargs)
+
+        monkeypatch.setattr(builtins, "__import__", mock_import)
+        client = settings.build_client()
+
+    assert isinstance(client, HttpxDirectClient)
+    assert client._base_url == "https://example.com/v1"
+    assert client._api_key == "test-key"
+
+
+def test_build_client_returns_litellm_when_available(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("VDS_AGENT_CORE__API_KEY", raising=False)
+    settings = LLMSettings()
+
+    mock_litellm = MagicMock()
+    with patch.dict("sys.modules", {"litellm": mock_litellm}):
+        client = settings.build_client()
+
+    assert isinstance(client, LiteLLMClient)
+
+
+# ---------------------------------------------------------------------------
+# HttpxDirectClient.chat — mocked httpx
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_httpx_chat_success() -> None:
+    client = HttpxDirectClient(base_url="https://test.api/v1", api_key="sk-test")
+
+    mock_response = MagicMock()
+    mock_response.json.return_value = {
+        "choices": [{"message": {"content": "Hello from LLM"}}],
+    }
+    mock_response.raise_for_status = MagicMock()
+
+    mock_http_client = AsyncMock()
+    mock_http_client.post.return_value = mock_response
+    mock_http_client.__aenter__ = AsyncMock(return_value=mock_http_client)
+    mock_http_client.__aexit__ = AsyncMock(return_value=False)
+
+    with patch("httpx.AsyncClient", return_value=mock_http_client):
+        result = await client.chat(
+            [{"role": "user", "content": "hi"}],
+            model="gpt-4o",
+        )
+
+    assert result == "Hello from LLM"
+    mock_http_client.post.assert_called_once()
+    call_kwargs = mock_http_client.post.call_args
+    assert "Bearer sk-test" in str(call_kwargs)
+
+
+@pytest.mark.asyncio
+async def test_httpx_chat_json_strips_fences() -> None:
+    client = HttpxDirectClient()
+
+    json_content = '```json\n{"answer": "yes", "score": 0.95}\n```'
+    mock_response = MagicMock()
+    mock_response.json.return_value = {
+        "choices": [{"message": {"content": json_content}}],
+    }
+    mock_response.raise_for_status = MagicMock()
+
+    mock_http_client = AsyncMock()
+    mock_http_client.post.return_value = mock_response
+    mock_http_client.__aenter__ = AsyncMock(return_value=mock_http_client)
+    mock_http_client.__aexit__ = AsyncMock(return_value=False)
+
+    with patch("httpx.AsyncClient", return_value=mock_http_client):
+        result = await client.chat_json(
+            [{"role": "user", "content": "test"}],
+            model="gpt-4o",
+            schema=_SampleSchema,
+        )
+
+    assert isinstance(result, _SampleSchema)
+    assert result.answer == "yes"
+    assert result.score == 0.95
+
+
+# ---------------------------------------------------------------------------
+# HttpxDirectClient — no api_key
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_httpx_chat_no_api_key() -> None:
+    """When no api_key, Authorization header is omitted."""
+    client = HttpxDirectClient(api_key=None)
+
+    mock_response = MagicMock()
+    mock_response.json.return_value = {
+        "choices": [{"message": {"content": "ok"}}],
+    }
+    mock_response.raise_for_status = MagicMock()
+
+    mock_http_client = AsyncMock()
+    mock_http_client.post.return_value = mock_response
+    mock_http_client.__aenter__ = AsyncMock(return_value=mock_http_client)
+    mock_http_client.__aexit__ = AsyncMock(return_value=False)
+
+    with patch("httpx.AsyncClient", return_value=mock_http_client):
+        result = await client.chat(
+            [{"role": "user", "content": "hi"}],
+            model="gpt-4o",
+        )
+
+    assert result == "ok"
+    call_args = mock_http_client.post.call_args
+    headers = call_args.kwargs.get("headers", call_args[1].get("headers", {}))
+    assert "Authorization" not in headers
+
+
+# ---------------------------------------------------------------------------
+# LiteLLMClient — ImportError on missing dep
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_litellm_chat_raises_on_missing_dep(monkeypatch: pytest.MonkeyPatch) -> None:
+    import builtins
+
+    real_import = builtins.__import__
+
+    def mock_import(name: str, *args: Any, **kwargs: Any) -> Any:
+        if name == "litellm":
+            raise ImportError("mocked")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", mock_import)
+
+    client = LiteLLMClient()
+    with pytest.raises(ImportError, match="vds-agent-core\\[litellm\\]"):
+        await client.chat([{"role": "user", "content": "hi"}], model="gpt-4o")
+
+
+# ---------------------------------------------------------------------------
+# LiteLLMClient — ImportError on chat_json missing dep
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_litellm_chat_json_raises_on_missing_dep(monkeypatch: pytest.MonkeyPatch) -> None:
+    """LiteLLMClient.chat_json raises ImportError when litellm not installed."""
+    import builtins
+
+    real_import = builtins.__import__
+
+    def mock_import(name: str, *args: Any, **kwargs: Any) -> Any:
+        if name == "litellm":
+            raise ImportError("mocked")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", mock_import)
+
+    class _Schema(BaseModel):
+        result: str
+
+    client = LiteLLMClient()
+    with pytest.raises(ImportError, match="vds-agent-core\\[litellm\\]"):
+        await client.chat_json(
+            [{"role": "user", "content": "hi"}],
+            model="gpt-4o",
+            schema=_Schema,
+        )
+
+
+# ---------------------------------------------------------------------------
+# LLMSettings.build_pydantic_ai_model — ImportError on missing pydantic_ai
+# ---------------------------------------------------------------------------
+
+
+def test_build_pydantic_ai_model_raises_on_missing_pydantic_ai(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """build_pydantic_ai_model raises ImportError when pydantic_ai.providers.litellm is absent."""
+    import builtins
+
+    real_import = builtins.__import__
+
+    def mock_import(name: str, *args: Any, **kwargs: Any) -> Any:
+        if name in ("pydantic_ai.providers.litellm", "pydantic_ai.models.openai"):
+            raise ImportError("mocked pydantic_ai")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", mock_import)
+    monkeypatch.delenv("VDS_AGENT_CORE__API_KEY", raising=False)
+
+    settings = LLMSettings(api_key="test", base_url="http://localhost:4000")
+    with pytest.raises(ImportError):
+        settings.build_pydantic_ai_model()
+
+
+# ---------------------------------------------------------------------------
+# LiteLLMClient — successful chat (mocked litellm)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_litellm_chat_success_with_mock() -> None:
+    """LiteLLMClient.chat returns content when litellm is available."""
+    import types
+
+    mock_litellm = types.ModuleType("litellm")
+
+    async def fake_acompletion(**kwargs: Any) -> Any:
+        response = MagicMock()
+        response.choices = [MagicMock()]
+        response.choices[0].message.content = "mocked response"
+        return response
+
+    mock_litellm.acompletion = fake_acompletion  # type: ignore[attr-defined]
+
+    with patch.dict("sys.modules", {"litellm": mock_litellm}):
+        client = LiteLLMClient()
+        result = await client.chat([{"role": "user", "content": "hi"}], model="openai/gpt-4o")
+
+    assert result == "mocked response"

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/unit/test_schemas.py

@@ -0,0 +1,63 @@
+"""Unit tests for vds_agent_core.llm.schemas — ProbeScore and parse_llm_response."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from vds_agent_core.llm.schemas import ProbeScore, parse_llm_response
+
+
+class TestProbeScore:
+    def test_default_instantiation(self) -> None:
+        probe = ProbeScore(name="existence", score=8.0, reasoning="Found evidence")
+        assert probe.name == "existence"
+        assert probe.score == 8.0
+        assert probe.max_score == 10.0
+        assert probe.evidence_refs == []
+
+    def test_score_bounds(self) -> None:
+        with pytest.raises(Exception):
+            ProbeScore(name="x", score=11.0, reasoning="over max")
+        with pytest.raises(Exception):
+            ProbeScore(name="x", score=-1.0, reasoning="under min")
+
+    def test_evidence_refs(self) -> None:
+        probe = ProbeScore(
+            name="content",
+            score=5.0,
+            reasoning="partial",
+            evidence_refs=["path/to/file.py", "README.md"],
+        )
+        assert len(probe.evidence_refs) == 2
+
+    def test_custom_max_score(self) -> None:
+        probe = ProbeScore(name="quality", score=2.0, max_score=4.0, reasoning="ok")
+        assert probe.max_score == 4.0
+
+
+class TestParseLlmResponse:
+    def test_parse_plain_json(self) -> None:
+        data = {"name": "test", "score": 7.5, "reasoning": "good", "max_score": 10.0}
+        result = parse_llm_response(json.dumps(data), ProbeScore)
+        assert isinstance(result, ProbeScore)
+        assert result.score == 7.5
+
+    def test_parse_markdown_json_block(self) -> None:
+        text = '```json\n{"name": "test", "score": 5.0, "reasoning": "ok"}\n```'
+        result = parse_llm_response(text, ProbeScore)
+        assert isinstance(result, ProbeScore)
+        assert result.score == 5.0
+
+    def test_parse_plain_code_block(self) -> None:
+        text = '```\n{"name": "test", "score": 3.0, "reasoning": "low"}\n```'
+        result = parse_llm_response(text, ProbeScore)
+        assert result.score == 3.0
+
+    def test_invalid_json_raises(self) -> None:
+        with pytest.raises(ValueError, match="Failed to parse"):
+            parse_llm_response("not json at all", ProbeScore)
+
+    def test_invalid_schema_raises(self) -> None:
+        with pytest.raises(ValueError, match="Failed to validate"):
+            parse_llm_response('{"score": 999}', ProbeScore)  # score > 10.0

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/unit/test_skill_executor.py

@@ -0,0 +1,297 @@
+"""Unit tests for vds_agent_core.skills.executor."""
+
+from __future__ import annotations
+
+import importlib
+import subprocess
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+from vds_agent_core.skills.executor import (
+    SkillExecutor,
+    SubprocessRunner,
+)
+
+# Canonical patch target for shutil.which inside the executor module.
+_WHICH_TARGET = "vds_agent_core.skills.executor.shutil.which"
+# A fixed absolute path returned by the which mock in happy-path tests.
+_VDS_CLI_PATH = "/usr/local/bin/vds-cli"
+
+
+class MockRunner:
+    """Test double for CommandRunner."""
+
+    def __init__(self, stdout: str = "", stderr: str = "", returncode: int = 0) -> None:
+        self.stdout = stdout
+        self.stderr = stderr
+        self.returncode = returncode
+        self.calls: list[dict[str, Any]] = []
+
+    def run(self, cmd: list[str], **kwargs: Any) -> subprocess.CompletedProcess:
+        self.calls.append({"cmd": cmd, "kwargs": kwargs})
+        return subprocess.CompletedProcess(
+            args=cmd,
+            returncode=self.returncode,
+            stdout=self.stdout,
+            stderr=self.stderr,
+        )
+
+
+class TestSubprocessRunner:
+    def test_instantiation(self) -> None:
+        runner = SubprocessRunner()
+        assert runner is not None
+
+    def test_conforms_to_protocol(self) -> None:
+        runner = SubprocessRunner()
+        assert hasattr(runner, "run")
+        assert callable(runner.run)
+
+
+class TestCommandRunnerProtocol:
+    def test_structural_conformance(self) -> None:
+        """Any object with a run() method satisfies CommandRunner."""
+        runner = MockRunner()
+        # Protocol is structural -- just verify it has the right shape
+        assert hasattr(runner, "run")
+        result = runner.run(["echo", "hello"])
+        assert isinstance(result, subprocess.CompletedProcess)
+
+    def test_mock_runner_is_valid_command_runner(self) -> None:
+        """MockRunner can be used wherever CommandRunner is expected."""
+        mock = MockRunner(stdout="output", returncode=0)
+        executor = SkillExecutor(runner=mock)
+        assert executor._runner is mock
+
+
+class TestSkillExecutorInit:
+    def test_default_runner_is_subprocess(self) -> None:
+        executor = SkillExecutor()
+        assert isinstance(executor._runner, SubprocessRunner)
+
+    def test_custom_runner_injected(self) -> None:
+        mock = MockRunner()
+        executor = SkillExecutor(runner=mock)
+        assert executor._runner is mock
+
+    def test_none_runner_uses_default(self) -> None:
+        executor = SkillExecutor(runner=None)
+        assert isinstance(executor._runner, SubprocessRunner)
+
+
+class TestVdsCLIExec:
+    def test_success_returns_stdout(self) -> None:
+        with patch(_WHICH_TARGET, return_value=_VDS_CLI_PATH):
+            mock = MockRunner(stdout="hello world\n", returncode=0)
+            executor = SkillExecutor(runner=mock)
+            result = executor.vds_cli_exec(["--help"])
+        assert result == "hello world\n"
+
+    def test_failure_returns_stderr(self) -> None:
+        with patch(_WHICH_TARGET, return_value=_VDS_CLI_PATH):
+            mock = MockRunner(stderr="error: unknown command\n", returncode=1)
+            executor = SkillExecutor(runner=mock)
+            result = executor.vds_cli_exec(["bad-cmd"])
+        assert "error" in result
+
+    def test_cmd_uses_which_resolved_path(self) -> None:
+        # FR-11: command is [<abs-path>, *args], no longer ["uv", "run", "vds-cli", ...]
+        with patch(_WHICH_TARGET, return_value=_VDS_CLI_PATH):
+            mock = MockRunner(stdout="ok", returncode=0)
+            executor = SkillExecutor(runner=mock)
+            executor.vds_cli_exec(["memory", "health"])
+        assert mock.calls[0]["cmd"] == [_VDS_CLI_PATH, "memory", "health"]
+
+    def test_records_tool_usage(self) -> None:
+        SkillExecutor.reset_usage()
+        with patch(_WHICH_TARGET, return_value=_VDS_CLI_PATH):
+            mock = MockRunner(stdout="ok", returncode=0)
+            executor = SkillExecutor(runner=mock)
+            executor.vds_cli_exec(["--version"])
+        usage = SkillExecutor.consume_usage()
+        assert len(usage) == 1
+        assert usage[0]["tool"] == "vds_cli_exec"
+        assert usage[0]["success"] is True
+
+
+class TestRecordToolUsage:
+    def test_record_and_consume(self) -> None:
+        SkillExecutor.reset_usage()
+        SkillExecutor.record_tool_usage({"tool": "test_tool", "action": "run"})
+        usage = SkillExecutor.consume_usage()
+        assert len(usage) == 1
+        assert usage[0]["tool"] == "test_tool"
+
+    def test_consume_clears_usage(self) -> None:
+        SkillExecutor.reset_usage()
+        SkillExecutor.record_tool_usage({"tool": "x"})
+        SkillExecutor.consume_usage()
+        assert SkillExecutor.consume_usage() == []
+
+    def test_reset_clears_usage(self) -> None:
+        SkillExecutor.record_tool_usage({"tool": "x"})
+        SkillExecutor.reset_usage()
+        assert SkillExecutor.consume_usage() == []
+
+
+class TestVdsCLIExecException:
+    def test_exception_returns_error_string(self) -> None:
+        class _RaisingRunner:
+            def run(self, cmd: list[str], **kwargs: Any) -> subprocess.CompletedProcess:
+                raise RuntimeError("subprocess exploded")
+
+        with patch(_WHICH_TARGET, return_value=_VDS_CLI_PATH):
+            executor = SkillExecutor(runner=_RaisingRunner())
+            result = executor.vds_cli_exec(["memory", "health"])
+        assert "subprocess exploded" in result
+
+    def test_exception_records_failed_usage(self) -> None:
+        SkillExecutor.reset_usage()
+
+        class _RaisingRunner:
+            def run(self, cmd: list[str], **kwargs: Any) -> subprocess.CompletedProcess:
+                raise OSError("no such file")
+
+        with patch(_WHICH_TARGET, return_value=_VDS_CLI_PATH):
+            executor = SkillExecutor(runner=_RaisingRunner())
+            executor.vds_cli_exec(["--version"])
+        usage = SkillExecutor.consume_usage()
+        assert len(usage) == 1
+        assert usage[0]["success"] is False
+        assert "no such file" in usage[0]["error"]
+
+    def test_failure_records_duration_ms(self) -> None:
+        SkillExecutor.reset_usage()
+        with patch(_WHICH_TARGET, return_value=_VDS_CLI_PATH):
+            mock = MockRunner(stderr="oops", returncode=1)
+            executor = SkillExecutor(runner=mock)
+            executor.vds_cli_exec(["bad"])
+        usage = SkillExecutor.consume_usage()
+        assert "duration_ms" in usage[0]
+        assert isinstance(usage[0]["duration_ms"], int)
+
+    def test_success_records_args(self) -> None:
+        SkillExecutor.reset_usage()
+        with patch(_WHICH_TARGET, return_value=_VDS_CLI_PATH):
+            mock = MockRunner(stdout="ok", returncode=0)
+            executor = SkillExecutor(runner=mock)
+            executor.vds_cli_exec(["memory", "search", "foo"])
+        usage = SkillExecutor.consume_usage()
+        assert usage[0]["args"] == ["memory", "search", "foo"]
+
+
+class TestGrepaiSearch:
+    def test_success_with_path(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = subprocess.CompletedProcess(
+                args=[], returncode=0, stdout='[{"file": "a.py"}]', stderr=""
+            )
+            SkillExecutor.reset_usage()
+            result = SkillExecutor._grepai_search("auth pattern", path="/some/repo")
+        assert result["success"] is True
+        assert result["results"] == [{"file": "a.py"}]
+        assert result["path"] == "/some/repo"
+
+    def test_success_empty_output(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
+            result = SkillExecutor._grepai_search("query", path="/repo")
+        assert result["success"] is True
+        assert result["results"] == []
+
+    def test_failure_nonzero_returncode(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = subprocess.CompletedProcess(args=[], returncode=1, stdout="", stderr="grepai error")
+            result = SkillExecutor._grepai_search("query", path="/repo")
+        assert result["success"] is False
+        assert "grepai error" in result["error"]
+
+    def test_json_parse_error(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = subprocess.CompletedProcess(args=[], returncode=0, stdout="not-json", stderr="")
+            result = SkillExecutor._grepai_search("query", path="/repo")
+        assert result["success"] is False
+        assert "parse" in result["error"].lower()
+
+    def test_timeout_expired(self) -> None:
+        with patch("subprocess.run", side_effect=subprocess.TimeoutExpired(cmd="grepai", timeout=60)):
+            result = SkillExecutor._grepai_search("query", path="/repo")
+        assert result["success"] is False
+        assert "timed out" in result["error"]
+
+    def test_file_not_found(self) -> None:
+        with patch("subprocess.run", side_effect=FileNotFoundError("grepai not found")):
+            result = SkillExecutor._grepai_search("query", path="/repo")
+        assert result["success"] is False
+        assert "not found" in result["error"]
+
+    def test_generic_exception(self) -> None:
+        with patch("subprocess.run", side_effect=ValueError("unexpected")):
+            result = SkillExecutor._grepai_search("query", path="/repo")
+        assert result["success"] is False
+        assert "unexpected" in result["error"]
+
+    def test_no_path_emits_deprecation_warning(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = subprocess.CompletedProcess(args=[], returncode=0, stdout="[]", stderr="")
+            with pytest.warns(DeprecationWarning, match="deprecated"):
+                result = SkillExecutor._grepai_search("query")
+        assert "warning" in result
+
+    def test_records_tool_usage_on_success(self) -> None:
+        SkillExecutor.reset_usage()
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = subprocess.CompletedProcess(args=[], returncode=0, stdout="[]", stderr="")
+            SkillExecutor._grepai_search("query", path="/repo")
+        usage = SkillExecutor.consume_usage()
+        assert len(usage) == 1
+        assert usage[0]["tool"] == "_grepai_search"
+        assert usage[0]["scoped"] is True
+
+    def test_result_dict_from_object_output(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = subprocess.CompletedProcess(
+                args=[], returncode=0, stdout='{"results": [{"file": "b.py"}]}', stderr=""
+            )
+            result = SkillExecutor._grepai_search("query", path="/repo")
+        assert result["success"] is True
+        assert result["results"] == [{"file": "b.py"}]
+
+
+# ---------------------------------------------------------------------------
+# FR-11 / T-11: shutil.which-based vds-cli dispatch
+# ---------------------------------------------------------------------------
+
+
+class TestVdsCLIExecFR11:
+    """Tests for FR-11: shutil.which-based vds-cli dispatch (spec v0.5.0)."""
+
+    def test_vds_cli_exec_uses_shutil_which_absolute_path(self) -> None:
+        """Hit branch: shutil.which returns a path -- command uses that path directly."""
+        with patch(_WHICH_TARGET, return_value="/absolute/path/to/vds-cli"):
+            mock = MockRunner(stdout="ok", returncode=0)
+            executor = SkillExecutor(runner=mock)
+            executor.vds_cli_exec(["status"])
+        assert mock.calls[0]["cmd"] == ["/absolute/path/to/vds-cli", "status"]
+
+    def test_vds_cli_exec_raises_runtime_error_when_not_on_path(self) -> None:
+        """Miss branch: shutil.which returns None -- RuntimeError with install hint."""
+        with patch(_WHICH_TARGET, return_value=None):
+            mock = MockRunner(stdout="", returncode=0)
+            executor = SkillExecutor(runner=mock)
+            with pytest.raises(RuntimeError) as exc_info:
+                executor.vds_cli_exec(["status"])
+        error_msg = str(exc_info.value)
+        assert "uv tool install --editable" in error_msg
+        assert "PATH" in error_msg
+
+    def test_executor_module_imports_with_shutil_which_returning_none(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Import safety: shutil.which is called inside the method, not at module import time."""
+        import vds_agent_core.skills.executor as executor_mod
+
+        monkeypatch.setattr("shutil.which", lambda _name: None)
+        # Reload to confirm module-level code does not call shutil.which
+        reloaded = importlib.reload(executor_mod)
+        assert reloaded is not None
+        assert hasattr(reloaded, "SkillExecutor")