sanityops-cli 0.1.3__py3-none-any.whl

sanityops_cli/agents/scanner_agent/agent.py

@@ -0,0 +1,332 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from pathlib import Path
+
+import anyio
+from rich.console import Console
+
+from sanityops_cli.agents.scanner_agent.models.finding import FindingsResult
+from sanityops_cli.agents.scanner_agent.prompts import (
+    # New analyzer prompts
+    ANALYZE_PARENT_PROMPT,
+    INSPECT_PARENT_PROMPT,
+    PROMPT_ANALYZER_PROMPT,
+    PROMPT_FINDER_RULES,
+    SKILL_ANALYZER_PROMPT,
+    SKILL_FINDER_RULES,
+    TOOL_ANALYZER_PROMPT,
+    TOOL_FINDER_RULES,
+)
+from sanityops_cli.exceptions.base_exceptions import ValidationError
+from sanityops_cli.logging.logger import Logger
+
+# ============================================================================
+# ScannerAgent Class
+# ============================================================================
+
+console = Console()
+
+
+class ScannerAgent:
+
+    def __init__(
+        self,
+        provider,
+        max_loops: int = 30,
+        timeout: int = 120,
+        token_budget: int = 200000,
+        verbose: bool = False,
+        console: Console | None = None,
+        logger: Logger | None = None,
+    ):
+        self.provider = provider
+        self.max_loops = max_loops
+        self.timeout = timeout
+        self.token_budget = token_budget
+        self.verbose = verbose
+        self.console = console or Console()
+        self.logger: Logger | None = logger
+
+    async def scan(
+        self,
+        directory: str,
+        depth: int = 5,
+    ) -> FindingsResult:
+        path = Path(directory).resolve()
+        if not path.exists() or not path.is_dir():
+            raise ValidationError(f"Directory does not exist: {directory}")
+
+        abs_directory = str(path)
+
+        from sanityops_agent.agents import AgentFactory
+        from sanityops_agent.core.agent import AgentConfig, TerminationReason
+        from sanityops_agent.hooks.base import HookExecutor
+        from sanityops_agent.tools import ToolRegistry
+        from sanityops_agent.tools.builtins import GlobTool, TaskTool
+
+        from sanityops_cli.agents.scanner_agent.tools.grep_tool import GrepTool
+        from sanityops_cli.agents.scanner_agent.tools.listfiles_tool import ListFilesTool
+        from sanityops_cli.agents.scanner_agent.tools.readfile_tool import FileReadTool
+        from sanityops_cli.agents.scanner_agent.tools.storefindings_tool import StoreFindingsTool
+
+        registry = ToolRegistry()
+        registry.register(FileReadTool())
+        registry.register(ListFilesTool())
+        registry.register(GlobTool())
+        registry.register(GrepTool())
+        registry.register(TaskTool())
+        registry.register(StoreFindingsTool())
+
+        StoreFindingsTool._findings.clear()
+
+        system_prompt = self._build_system_prompt(abs_directory, depth)
+
+        config = AgentConfig(
+            max_loops=self.max_loops,
+            total_timeout=self.timeout,
+            token_budget=self.token_budget,
+            system_prompt=system_prompt,
+        )
+
+        hook_executor = HookExecutor()
+        if self.verbose:
+            from sanityops_cli.agents.scanner_agent.hooks.progress_hook import ProgressHook
+            hook_executor.register(
+                ProgressHook(self.console, verbose=self.verbose, logger=self.logger)
+            )
+
+        factory = AgentFactory(
+            provider=self.provider,
+            config=config,
+            tool_registry=registry,
+            hook_executor=hook_executor,
+        )
+        agent = factory.create_parent_agent(system_prompt=system_prompt)
+
+        if self.verbose:
+            self.console.print()
+
+        result = await agent.run(f"Inspect {abs_directory}")
+
+        if self.verbose:
+            self.console.print()
+
+        if result.termination_reason != TerminationReason.END_TURN:
+            error_msg = result.error or f"Agent terminated: {result.termination_reason.value}"
+            if result.error_detail:
+                error_detail_str = "\n".join(
+                    f"  - {e.error_type}: {e.message}"
+                    for e in result.error_detail
+                )
+                error_msg += f"\nError Detail:\n{error_detail_str}"
+            raise ValidationError(f"Agent execution failed: {error_msg}")
+
+        return self._build_result(abs_directory, result)
+
+    async def analyze_files(
+        self,
+        prompts: list[str],
+        tools: list[str],
+        skills: list[str],
+    ) -> FindingsResult:
+        """Analyze explicit artifact files and extract structured metadata.
+
+        Args:
+            prompts: List of absolute paths to prompt files
+            tools: List of absolute paths to tool files
+            skills: List of absolute paths to skill.md files
+
+        Returns:
+            FindingsResult with structured content for each artifact
+        """
+        from sanityops_agent.agents import AgentFactory
+        from sanityops_agent.core.agent import AgentConfig, TerminationReason
+        from sanityops_agent.hooks.base import HookExecutor
+        from sanityops_agent.tools import ToolRegistry
+        from sanityops_agent.tools.builtins import GlobTool, TaskTool
+
+        from sanityops_cli.agents.scanner_agent.tools.grep_tool import GrepTool
+        from sanityops_cli.agents.scanner_agent.tools.listfiles_tool import ListFilesTool
+        from sanityops_cli.agents.scanner_agent.tools.readfile_tool import FileReadTool
+        from sanityops_cli.agents.scanner_agent.tools.storefindings_tool import StoreFindingsTool
+
+        # Validate at least one artifact provided
+        if not prompts and not tools and not skills:
+            return FindingsResult(
+                directory="",
+                skills=[],
+                tools=[],
+                prompts=[],
+                meta={"time_elapsed": 0, "loops_used": 0, "tokens_used": 0}
+            )
+
+        # Validate all paths are absolute and exist
+        for path_list, name in [(prompts, "prompts"), (tools, "tools"), (skills, "skills")]:
+            for p in path_list:
+                path = Path(p)
+                if not path.is_absolute():
+                    raise ValidationError(f"{name} path must be absolute: {p}")
+                if not path.exists():
+                    raise ValidationError(f"{name} path does not exist: {p}")
+
+        # Build tool registry
+        registry = ToolRegistry()
+        registry.register(FileReadTool())
+        registry.register(ListFilesTool())
+        registry.register(GlobTool())
+        registry.register(GrepTool())
+        registry.register(TaskTool())
+        registry.register(StoreFindingsTool())
+
+        # Clear previous findings
+        StoreFindingsTool._findings.clear()
+
+        # Build system prompt
+        system_prompt = self._build_analyze_prompt(prompts, tools, skills)
+
+        config = AgentConfig(
+            max_loops=self.max_loops,
+            total_timeout=self.timeout,
+            token_budget=self.token_budget,
+            system_prompt=system_prompt,
+        )
+
+        # Setup hooks
+        hook_executor = HookExecutor()
+        if self.verbose:
+            from sanityops_cli.agents.scanner_agent.hooks.progress_hook import ProgressHook
+            hook_executor.register(
+                ProgressHook(self.console, verbose=self.verbose, logger=self.logger)
+            )
+
+        # Create and run agent
+        factory = AgentFactory(
+            provider=self.provider,
+            config=config,
+            tool_registry=registry,
+            hook_executor=hook_executor,
+        )
+        agent = factory.create_parent_agent(system_prompt=system_prompt)
+
+        if self.verbose:
+            self.console.print()
+
+        result = await agent.run("Analyze provided artifact files")
+
+        if self.verbose:
+            self.console.print()
+
+        if result.termination_reason != TerminationReason.END_TURN:
+            error_msg = result.error or f"Agent terminated: {result.termination_reason.value}"
+            if result.error_detail:
+                error_detail_str = "\n".join(
+                    f"  - {e.error_type}: {e.message}"
+                    for e in result.error_detail
+                )
+                error_msg += f"\nError Detail:\n{error_detail_str}"
+            raise ValidationError(f"Agent execution failed: {error_msg}")
+
+        return self._build_result("", result)
+
+    def analyze_files_sync(
+        self,
+        prompts: list[str],
+        tools: list[str],
+        skills: list[str],
+    ) -> FindingsResult:
+        """Synchronous wrapper for analyze_files."""
+        return anyio.run(self.analyze_files, prompts, tools, skills)
+
+    def scan_sync(
+        self,
+        directory: str,
+        depth: int = 5,
+    ) -> FindingsResult:
+        return anyio.run(self.scan, directory, depth)
+
+    def _build_system_prompt(self, directory: str, depth: int) -> str:
+        formatted_skill_rules = SKILL_FINDER_RULES.format(
+            directory=directory, depth=depth
+        )
+        formatted_tool_rules = TOOL_FINDER_RULES.format(
+            directory=directory, depth=depth
+        )
+        formatted_prompt_rules = PROMPT_FINDER_RULES.format(
+            directory=directory, depth=depth
+        )
+        return INSPECT_PARENT_PROMPT.format(
+            directory=directory,
+            depth=depth,
+            SKILL_FINDER_RULES=formatted_skill_rules,
+            TOOL_FINDER_RULES=formatted_tool_rules,
+            PROMPT_FINDER_RULES=formatted_prompt_rules,
+        )
+
+    def _build_analyze_prompt(
+        self,
+        prompts: list[str],
+        tools: list[str],
+        skills: list[str],
+    ) -> str:
+        """Build system prompt for file analysis mode."""
+        # Format file lists as bullet points
+        skill_files_str = "\n".join(f"- {p}" for p in skills) if skills else "(none)"
+        tool_files_str = "\n".join(f"- {p}" for p in tools) if tools else "(none)"
+        prompt_files_str = "\n".join(f"- {p}" for p in prompts) if prompts else "(none)"
+
+        formatted_skill_analyzer = SKILL_ANALYZER_PROMPT.format(
+            skill_files=skill_files_str
+        )
+        formatted_tool_analyzer = TOOL_ANALYZER_PROMPT.format(
+            tool_files=tool_files_str
+        )
+        formatted_prompt_analyzer = PROMPT_ANALYZER_PROMPT.format(
+            prompt_files=prompt_files_str
+        )
+
+        return ANALYZE_PARENT_PROMPT.format(
+            skill_count=len(skills),
+            tool_count=len(tools),
+            prompt_count=len(prompts),
+            SKILL_ANALYZER_PROMPT=formatted_skill_analyzer,
+            TOOL_ANALYZER_PROMPT=formatted_tool_analyzer,
+            PROMPT_ANALYZER_PROMPT=formatted_prompt_analyzer,
+        )
+
+    def _build_result(
+        self,
+        directory: str,
+        agent_result,
+    ) -> FindingsResult:
+        from sanityops_cli.agents.scanner_agent.models.finding import FindingType
+        from sanityops_cli.agents.scanner_agent.tools.storefindings_tool import StoreFindingsTool
+
+        findings = StoreFindingsTool._findings
+        skills = [f for f in findings if f.type == FindingType.SKILL]
+        tools = [f for f in findings if f.type == FindingType.TOOL]
+        prompts = [f for f in findings if f.type == FindingType.PROMPT]
+
+        return FindingsResult(
+            directory=directory,
+            skills=skills,
+            tools=tools,
+            prompts=prompts,
+            meta={
+                "time_elapsed": agent_result.time_elapsed,
+                "loops_used": agent_result.loops_used,
+                "tokens_used": agent_result.tokens_used,
+            }
+        )

sanityops_cli/agents/scanner_agent/hooks/progress_hook.py

@@ -0,0 +1,152 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from rich.console import Console
+from rich.markup import escape
+from rich.text import Text
+
+from sanityops_cli.logging.logger import Logger
+
+
+class ProgressHook:
+    """Hook to report agent progress to console in real-time."""
+
+    def __init__(
+        self,
+        console: Console,
+        verbose: bool = True,
+        logger: Logger | None = None,
+    ):
+        self.console = console
+        self.verbose = verbose
+        self.logger = logger
+        self._iteration = 0
+        self._tool_calls = 0
+        self._sub_agent_count = 0
+        # Will be set after lazy import
+        self._events = None
+
+    def _get_events(self):
+        """Lazy import of HookEvent."""
+        if self._events is None:
+            from sanityops_agent.hooks.base import HookEvent
+            self._events = HookEvent
+        return self._events
+
+    @property
+    def name(self) -> str:
+        return "progress"
+
+    @property
+    def description(self) -> str:
+        return "Reports agent progress to console"
+
+    @property
+    def priority(self) -> int:
+        return 5
+
+    @property
+    def events(self) -> list:
+        """Return events this hook subscribes to."""
+        events = self._get_events()
+        return [
+            events.BEFORE_LOOP,
+            events.BEFORE_LLM_CALL,
+            events.AFTER_LLM_CALL,
+            events.BEFORE_TOOL_EXEC,
+            events.AFTER_TOOL_EXEC,
+            events.ON_TERMINATION,
+        ]
+
+    def can_handle(self, event) -> bool:
+        """Whether this hook handles the given event."""
+        return event in self.events
+
+    def _emit(self, message: str) -> None:
+        """Print a progress line to console and mirror it to the logger at DEBUG."""
+        self.console.print(message)
+        if self.logger is not None:
+            self.logger.debug(Text.from_markup(message).plain.strip())
+
+    async def handle(self, ctx):
+        """Handle hook event and output progress."""
+        event = ctx.event
+        data = ctx.data
+
+        events = self._get_events()
+
+        if event == events.BEFORE_LOOP:
+            self._iteration = data.get("iteration", 0)
+            if self._iteration == 0:
+                self._emit("[bold cyan]▶ Agent started[/]")
+
+        elif event == events.BEFORE_LLM_CALL:
+            iteration = data.get("iteration", self._iteration)
+            self._emit(f"  [dim]⟳ LLM call (iteration {iteration + 1})[/]")
+
+        elif event == events.AFTER_LLM_CALL:
+            response = data.get("response")
+            if response and hasattr(response, 'usage'):
+                usage = response.usage
+                if usage:
+                    tokens = usage.get('total_tokens', 0)
+                    self._emit(f"  [dim]↓ received response (tokens: {tokens})[/]")
+
+        elif event == events.BEFORE_TOOL_EXEC:
+            tool_name = data.get("tool_name", "unknown")
+            tool_input = data.get("tool_input", {})
+            self._tool_calls += 1
+
+            if tool_name == "task":
+                goal = tool_input.get("goal", "unknown")[:50]
+                self._sub_agent_count += 1
+                self._emit(f"  [bold yellow]◇ Starting sub Agent #{self._sub_agent_count}[/]: {escape(goal)}...")
+            else:
+                if self.verbose:
+                    if tool_name == "bash":
+                        cmd = tool_input.get("command", "")[:60]
+                        self._emit(f"  [green]⚡ {tool_name}[/]: {escape(cmd)}")
+                    elif tool_name == "glob":
+                        pattern = tool_input.get("pattern", "")
+                        self._emit(f"  [green]⚡ {tool_name}[/]: {escape(pattern)}")
+                    elif tool_name == "grep":
+                        pattern = tool_input.get("pattern", "")[:40]
+                        path = tool_input.get("path", "")[:30]
+                        self._emit(f"  [green]⚡ {tool_name}[/]: '{escape(pattern)}' in {escape(path)}")
+                    elif tool_name == "file_ops":
+                        op = tool_input.get("operation", "")
+                        path = tool_input.get("path", "")[:50]
+                        self._emit(f"  [green]⚡ {tool_name}[/]: {escape(op)} {escape(path)}")
+                    else:
+                        self._emit(f"  [green]⚡ {tool_name}[/]")
+
+        elif event == events.AFTER_TOOL_EXEC:
+            tool_name = data.get("tool_name", "unknown")
+            is_error = ctx.is_error
+
+            if tool_name == "task":
+                if is_error:
+                    self.console.print("  [red]✗ Sub Agent failed[/]")
+                    if self.logger is not None:
+                        self.logger.error("Sub Agent failed")
+                else:
+                    self._emit("  [green]✓ Sub Agent completed[/]")
+
+        elif event == events.ON_TERMINATION:
+            reason = data.get("reason", "unknown")
+            self._emit(f"[bold]⏹ Agent terminated[/]: {escape(reason)}")
+            self._emit(f"  [dim]Statistics: {self._tool_calls} tool calls, {self._sub_agent_count} sub Agents[/]")
+
+        return ctx

sanityops_cli/agents/scanner_agent/models/finding.py

@@ -0,0 +1,120 @@
+# Copyright 2026 zipsonken
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from dataclasses import field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, ValidationInfo, field_validator, model_validator
+
+
+class FindingType(StrEnum):
+    SKILL = "skill"
+    TOOL = "tool"
+    PROMPT = "prompt"
+
+
+class Section(BaseModel):
+    """A markdown section within a skill file."""
+    title: str = Field(description="Section heading text")
+    content: str = Field(description="Section body content")
+
+
+class ToolSchema(BaseModel):
+    name: str
+    description: str = ""
+    parameters: dict = Field(default_factory=dict,description="Tool parameters, JSON Schema (Draft-07) format")
+
+
+class SkillContent(BaseModel):
+    """Extracted content from a skill.md file."""
+    name: str = Field(description="Skill name from frontmatter")
+    description: str = Field(description="Skill description from frontmatter")
+    sections: list[Section] = Field(default_factory=list, description="Parsed markdown sections")
+
+    def to_markdown(self) -> str:
+        """Reconstruct sections back to markdown string.
+
+        Returns:
+            Markdown string with all sections joined by double newlines.
+        """
+        if not self.sections:
+            return ""
+        return "\n\n".join(
+            f"## {section.title}\n\n{section.content}"
+            for section in self.sections
+        )
+
+
+class ToolContent(BaseModel):
+    """Extracted content from a tool file."""
+    name: str = Field(description="Tool name from definition")
+    description: str = Field(description="Tool description")
+    parameters: dict[str, Any] = Field(default_factory=dict, description="JSON Schema of parameters")
+
+
+class PromptContent(BaseModel):
+    content: str
+
+
+class Finding(BaseModel):
+    type: FindingType
+    relative: str
+    content: SkillContent | ToolContent | PromptContent | None = None
+
+    @field_validator("relative")
+    @classmethod
+    def validate_relative(cls, v: str, info: ValidationInfo) -> str:
+        ft = FindingType(info.data.get("type"))
+        path = Path(v)
+
+        if not path.is_absolute():
+            raise ValueError(f"relative must be an absolute path: {v}")
+
+        if not path.exists():
+            raise ValueError(f"path does not exist: {v}")
+
+        if ft == FindingType.TOOL:
+            if not path.is_file():
+                raise ValueError(f"Tool finding must be a file path: {v}")
+
+        elif ft == FindingType.SKILL:
+            # SKILL can be either a file (analyze_files mode) or directory (scan mode)
+            if not path.is_file() and not path.is_dir():
+                raise ValueError(f"Skill finding must be a file or directory path: {v}")
+
+        return v
+
+    @model_validator(mode="after")
+    def validate_content_binding(self) -> "Finding":
+        if self.type == FindingType.SKILL:
+            if self.content is not None and not isinstance(self.content, SkillContent):
+                raise ValueError("Skill finding content must be SkillContent or None")
+        elif self.type == FindingType.TOOL:
+            if self.content is not None and not isinstance(self.content, ToolContent):
+                raise ValueError("Tool finding content must be ToolContent or None")
+        elif self.type == FindingType.PROMPT:
+            if self.content is not None and not isinstance(self.content, PromptContent):
+                raise ValueError("Prompt finding content must be PromptContent or None")
+        return self
+
+
+class FindingsResult(BaseModel):
+    directory: str
+    skills: list[Finding] = field(default_factory=list)
+    tools: list[Finding] = field(default_factory=list)
+    prompts: list[Finding] = field(default_factory=list)
+    meta: dict[str, Any] = field(default_factory=dict)