iac-code 0.1.0__py3-none-any.whl

iac_code/tools/read_file.py

@@ -0,0 +1,127 @@
+"""ReadFile tool - reads file contents with optional line range."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from iac_code.i18n import _
+from iac_code.tools.base import Tool, ToolContext, ToolResult
+
+
+class ReadFileTool(Tool):
+    @property
+    def name(self) -> str:
+        return "read_file"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Read the contents of a file. You can optionally specify a line range "
+            "to read only a portion of the file. Use start_line and end_line for "
+            "large files to read specific sections."
+        )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The path to the file to read. Can be absolute or relative to working directory.",
+                },
+                "start_line": {
+                    "type": "integer",
+                    "description": "The starting line number to read from (1-based, inclusive). Optional.",
+                },
+                "end_line": {
+                    "type": "integer",
+                    "description": "The ending line number to read to (1-based, inclusive). Optional.",
+                },
+            },
+            "required": ["path"],
+        }
+
+    def normalize_input(self, tool_input: dict[str, Any]) -> None:
+        if "file_path" in tool_input and "path" not in tool_input:
+            tool_input["path"] = tool_input.pop("file_path")
+
+    async def execute(self, *, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        path = tool_input["path"]
+        start_line = tool_input.get("start_line")
+        end_line = tool_input.get("end_line")
+
+        # Resolve relative paths
+        if not os.path.isabs(path):
+            path = os.path.join(context.cwd, path)
+
+        try:
+            with open(path, encoding="utf-8") as f:
+                lines = f.readlines()
+        except FileNotFoundError:
+            return ToolResult.error(f"File not found: {path}")
+        except PermissionError:
+            return ToolResult.error(f"Permission denied: {path}")
+        except UnicodeDecodeError:
+            return ToolResult.error(f"Cannot read binary file: {path}")
+        except Exception as e:
+            return ToolResult.error(f"Error reading file: {e}")
+
+        total_lines = len(lines)
+
+        # Apply line range if specified
+        if start_line is not None or end_line is not None:
+            start = (start_line or 1) - 1  # Convert to 0-based
+            end = end_line or total_lines
+            start = max(0, start)
+            end = min(total_lines, end)
+            selected = lines[start:end]
+            # Add line numbers
+            numbered = [f"{i + start + 1:>6}\t{line}" for i, line in enumerate(selected)]
+            content = "".join(numbered)
+            return ToolResult.success(f"File: {path} (lines {start + 1}-{end} of {total_lines})\n\n{content}")
+
+        # Return full file
+        if total_lines > 0:
+            numbered = [f"{i + 1:>6}\t{line}" for i, line in enumerate(lines)]
+            content = "".join(numbered)
+        else:
+            content = "(empty file)"
+
+        return ToolResult.success(f"File: {path} ({total_lines} lines)\n\n{content}")
+
+    # UI rendering methods
+    def render_tool_use_message(self, input: dict, *, verbose: bool = False):
+        path = input.get("path", "")
+        if not path:
+            return None
+        display_path = path if verbose else os.path.basename(path)
+        parts = [display_path]
+        if input.get("start_line") and input.get("end_line"):
+            parts.append(f"lines {input['start_line']}-{input['end_line']}")
+        elif input.get("start_line"):
+            parts.append(f"from line {input['start_line']}")
+        return " · ".join(parts)
+
+    def render_tool_result_message(self, output: str, *, is_error: bool = False, verbose: bool = False):
+        if is_error:
+            return output
+        lines = output.splitlines()
+        total = len(lines) - 2  # subtract header + blank line
+        if total < 0:
+            total = 0
+        if verbose:
+            return output.strip()
+        return _("Read {total} lines").format(total=total)
+
+    def user_facing_name(self, input: dict | None = None) -> str:
+        return _("Read")
+
+    def get_activity_description(self, input: dict | None = None) -> str:
+        if input:
+            return _("Reading {path}").format(path=input.get("path", ""))
+        return _("Reading file...")
+
+    def is_read_only(self, input: dict | None = None) -> bool:
+        return True

iac_code/tools/result_storage.py

@@ -0,0 +1,39 @@
+"""Externalize large tool results to disk to preserve context window."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_MAX_INLINE_CHARS = 50_000
+DEFAULT_PREVIEW_CHARS = 2_000
+
+
+@dataclass
+class ProcessedResult:
+    content: str
+    is_externalized: bool = False
+    file_path: str | None = None
+
+
+class ResultStorage:
+    def __init__(
+        self,
+        storage_dir: str,
+        max_inline_chars: int = DEFAULT_MAX_INLINE_CHARS,
+        preview_chars: int = DEFAULT_PREVIEW_CHARS,
+    ):
+        self._storage_dir = storage_dir
+        self._max_inline_chars = max_inline_chars
+        self._preview_chars = preview_chars
+
+    def process(self, tool_use_id: str, content: str) -> ProcessedResult:
+        if len(content) <= self._max_inline_chars:
+            return ProcessedResult(content=content)
+        os.makedirs(self._storage_dir, exist_ok=True)
+        file_path = os.path.join(self._storage_dir, f"{tool_use_id}.txt")
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(content)
+        preview = content[: self._preview_chars]
+        preview += f"\n\n... [truncated — full output ({len(content)} chars) saved to {file_path}]"
+        return ProcessedResult(content=preview, is_externalized=True, file_path=file_path)

iac_code/tools/tool_executor.py

@@ -0,0 +1,165 @@
+"""Concurrent tool execution engine with read/write partitioning and input validation."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, cast
+
+from iac_code.services.telemetry import add_metric, log_event, start_span
+from iac_code.services.telemetry.config import should_capture_content_on_span
+from iac_code.services.telemetry.content_serializer import serialize_tool_arguments, serialize_tool_result
+from iac_code.services.telemetry.names import Events, GenAiAttr, GenAiOperationName, GenAiSpanKind, Metrics, Spans
+from iac_code.services.telemetry.sanitize import sanitize_error_message, sanitize_tool_name
+from iac_code.tools.base import ToolContext, ToolResult
+
+if TYPE_CHECKING:
+    from iac_code.tools.base import ToolRegistry
+
+
+class _ToolWithEventQueue(Protocol):
+    _event_queue: asyncio.Queue | None
+
+
+@dataclass
+class ToolCallRequest:
+    id: str
+    name: str
+    input: dict
+    event_queue: asyncio.Queue | None = None
+
+
+class ToolExecutor:
+    def __init__(
+        self,
+        registry: "ToolRegistry",
+        max_concurrency: int = 10,
+        tool_timeout: float = 120.0,
+    ):
+        self._registry = registry
+        self._max_concurrency = max_concurrency
+        self._tool_timeout = tool_timeout
+
+    def partition(self, calls: list[ToolCallRequest]) -> tuple[list[ToolCallRequest], list[ToolCallRequest]]:
+        """Partition calls into concurrent (read-only) and serial (write) batches."""
+        concurrent, serial = [], []
+        for call in calls:
+            tool = self._registry.get(call.name)
+            if tool and tool.is_concurrency_safe(call.input):
+                concurrent.append(call)
+            else:
+                serial.append(call)
+        return concurrent, serial
+
+    async def _validate_and_execute(self, call: ToolCallRequest, context: ToolContext) -> ToolResult:
+        """Validate input then execute. Returns error ToolResult on validation failure."""
+        tool = self._registry.get(call.name)
+        if not tool:
+            return ToolResult.error(f"Unknown tool: {call.name}")
+
+        # Input validation
+        valid, error = tool.validate_input(call.input)
+        if not valid:
+            return ToolResult.error(
+                f"Invalid input for tool '{call.name}': {error}. "
+                f"Please provide all required parameters as defined in the tool schema."
+            )
+
+        # Pass event_queue to tool if provided (for sub-agent event forwarding)
+        if call.event_queue is not None and hasattr(tool, "_event_queue"):
+            cast(_ToolWithEventQueue, tool)._event_queue = call.event_queue
+
+        # Pass event_queue from call to context for tools that emit progress events
+        if call.event_queue is not None:
+            context = ToolContext(cwd=context.cwd, event_queue=call.event_queue)
+
+        timeout = tool.timeout if tool.timeout is not None else self._tool_timeout
+
+        # Telemetry instrumentation
+        tool_name = sanitize_tool_name(call.name)
+        started = time.monotonic()
+
+        span_name = f"{Spans.TOOL_EXECUTE} {tool_name}"
+        span_attrs: dict = {
+            GenAiAttr.SPAN_KIND: GenAiSpanKind.TOOL,
+            GenAiAttr.OPERATION_NAME: GenAiOperationName.EXECUTE_TOOL,
+            GenAiAttr.TOOL_NAME: tool_name,
+            GenAiAttr.TOOL_TYPE: "function",
+            GenAiAttr.TOOL_CALL_ID: call.id,
+        }
+        if tool.description:
+            span_attrs[GenAiAttr.TOOL_DESCRIPTION] = tool.description
+        if should_capture_content_on_span():
+            span_attrs[GenAiAttr.TOOL_CALL_ARGUMENTS] = serialize_tool_arguments(call.input)
+
+        try:
+            with start_span(span_name, span_attrs) as span:
+                result = await asyncio.wait_for(
+                    tool.execute(tool_input=call.input, context=context),
+                    timeout=timeout,
+                )
+                duration_ms = int((time.monotonic() - started) * 1000)
+                if should_capture_content_on_span():
+                    span.set_attribute(GenAiAttr.TOOL_CALL_RESULT, serialize_tool_result(result))
+                log_event(Events.TOOL_USE_SUCCEEDED, {"tool_name": tool_name, "duration_ms": duration_ms})
+                add_metric(Metrics.TOOL_USE_COUNT, 1, {"tool_name": tool_name, "outcome": "success"})
+                return result
+        except asyncio.TimeoutError:
+            log_event(
+                Events.TOOL_USE_FAILED,
+                {
+                    "tool_name": tool_name,
+                    "error_type": "TimeoutError",
+                    "error_message": sanitize_error_message(f"Timeout after {timeout}s"),
+                },
+            )
+            add_metric(Metrics.TOOL_USE_COUNT, 1, {"tool_name": tool_name, "outcome": "error"})
+            return ToolResult.error(f"Tool '{call.name}' timed out after {timeout}s")
+        except Exception as e:
+            log_event(
+                Events.TOOL_USE_FAILED,
+                {
+                    "tool_name": tool_name,
+                    "error_type": type(e).__name__,
+                    "error_message": sanitize_error_message(str(e)),
+                },
+            )
+            add_metric(Metrics.TOOL_USE_COUNT, 1, {"tool_name": tool_name, "outcome": "error"})
+            return ToolResult.error(f"Tool '{call.name}' failed: {e}")
+
+    async def _execute_concurrent(
+        self, calls: list[ToolCallRequest], context: ToolContext
+    ) -> list[tuple[str, ToolResult]]:
+        if not calls:
+            return []
+        sem = asyncio.Semaphore(self._max_concurrency)
+
+        async def run(call: ToolCallRequest) -> tuple[str, ToolResult]:
+            async with sem:
+                result = await self._validate_and_execute(call, context)
+                return call.id, result
+
+        tasks = [asyncio.create_task(run(c)) for c in calls]
+        return list(await asyncio.gather(*tasks))
+
+    async def _execute_serial(self, calls: list[ToolCallRequest], context: ToolContext) -> list[tuple[str, ToolResult]]:
+        results = []
+        for call in calls:
+            result = await self._validate_and_execute(call, context)
+            results.append((call.id, result))
+        return results
+
+    async def execute_batch(self, calls: list[ToolCallRequest], context: ToolContext) -> list[ToolResult]:
+        """Execute tool calls with read/write partitioning.
+
+        1. Partition into concurrent (read-only) and serial (write) batches
+        2. Execute concurrent batch in parallel (up to max_concurrency)
+        3. Execute serial batch sequentially
+        4. Return results in original request order
+        """
+        concurrent, serial = self.partition(calls)
+        concurrent_results = await self._execute_concurrent(concurrent, context)
+        serial_results = await self._execute_serial(serial, context)
+        result_map = {call_id: result for call_id, result in concurrent_results + serial_results}
+        return [result_map[call.id] for call in calls]

iac_code/tools/web_fetch.py

@@ -0,0 +1,177 @@
+"""WebFetchTool - fetches web page content."""
+
+from __future__ import annotations
+
+import html as html_lib
+import re
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from iac_code.i18n import _
+from iac_code.tools.base import Tool, ToolContext, ToolResult
+
+
+def _extract_text_from_html(html: str) -> str:
+    """Extract plain text from HTML by removing tags and decoding entities.
+
+    Steps:
+    1. Remove <script>...</script> blocks (including content).
+    2. Remove <style>...</style> blocks (including content).
+    3. Strip all remaining HTML tags.
+    4. Decode HTML entities (e.g. &amp; -> &).
+    5. Collapse whitespace runs to a single space.
+
+    Args:
+        html: Raw HTML string.
+
+    Returns:
+        Plain text extracted from the HTML.
+    """
+    if not html:
+        return ""
+
+    # Remove script tags and their content
+    text = re.sub(r"<script[^>]*>.*?</script>", "", html, flags=re.DOTALL | re.IGNORECASE)
+
+    # Remove style tags and their content
+    text = re.sub(r"<style[^>]*>.*?</style>", "", text, flags=re.DOTALL | re.IGNORECASE)
+
+    # Strip all remaining HTML tags
+    text = re.sub(r"<[^>]+>", " ", text)
+
+    # Decode HTML entities
+    text = html_lib.unescape(text)
+
+    # Collapse whitespace (spaces, tabs, newlines) to single space
+    text = re.sub(r"[ \t]+", " ", text)
+
+    # Collapse multiple blank lines to a single newline
+    text = re.sub(r"\n\s*\n+", "\n", text)
+
+    return text.strip()
+
+
+class WebFetchTool(Tool):
+    """Tool for fetching web page content via HTTP/HTTPS."""
+
+    @property
+    def name(self) -> str:
+        return "web_fetch"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Fetch the content of a web page. Supports HTTP and HTTPS URLs. "
+            "For HTML pages, the content is extracted as plain text (scripts and styles removed). "
+            "Returns the page content truncated to max_length characters."
+        )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "The URL of the web page to fetch. Must include scheme (http:// or https://).",
+                },
+                "max_length": {
+                    "type": "integer",
+                    "description": "Maximum number of characters to return. Defaults to 50000.",
+                },
+            },
+            "required": ["url"],
+        }
+
+    async def execute(self, *, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        url: str = tool_input.get("url", "")
+        max_length: int = int(tool_input.get("max_length", 50000))
+
+        # Validate URL is not empty
+        if not url or not url.strip():
+            return ToolResult.error(_("URL cannot be empty."))
+
+        # Validate URL has scheme and netloc
+        parsed = urlparse(url)
+        if not parsed.scheme:
+            return ToolResult.error(
+                _("Invalid URL: missing scheme (e.g. http:// or https://). Got: {url}").format(url=url)
+            )
+        if not parsed.netloc:
+            return ToolResult.error(_("Invalid URL: missing host/netloc. Got: {url}").format(url=url))
+
+        headers = {"User-Agent": ("Mozilla/5.0 (compatible; iac-code/1.0; +https://github.com/ros-group/iac-code)")}
+
+        try:
+            async with httpx.AsyncClient(
+                timeout=30,
+                follow_redirects=True,
+                headers=headers,
+            ) as client:
+                response = await client.get(url)
+                response.raise_for_status()
+
+                content_type = response.headers.get("content-type", "")
+                text = response.text
+
+                if "text/html" in content_type:
+                    text = _extract_text_from_html(text)
+
+                # Truncate to max_length
+                if len(text) > max_length:
+                    text = text[:max_length]
+
+                return ToolResult.success(text)
+
+        except httpx.HTTPStatusError as e:
+            return ToolResult.error(_("HTTP error {status}: {url}").format(status=e.response.status_code, url=url))
+        except httpx.HTTPError as e:
+            return ToolResult.error(_("Failed to fetch {url}: {error}").format(url=url, error=str(e)))
+        except Exception as e:
+            return ToolResult.error(_("Unexpected error fetching {url}: {error}").format(url=url, error=str(e)))
+
+    # UI rendering methods
+    def render_tool_use_message(self, input: dict, *, verbose: bool = False):
+        url = input.get("url", "")
+        if not url:
+            return None
+        return url
+
+    def render_tool_result_message(self, output: str, *, is_error: bool = False, verbose: bool = False):
+        if is_error:
+            return output
+        lines = output.strip().splitlines()
+        char_count = len(output.strip())
+        summary = _("Fetched {chars} chars, {lines} lines").format(chars=char_count, lines=len(lines))
+        if verbose:
+            preview = "\n".join(lines[:50])
+            if len(lines) > 50:
+                preview += f"\n... ({len(lines) - 50} more lines)"
+            return f"{summary}\n{preview}"
+        return summary
+
+    def render_tool_use_error_message(self, error: str):
+        return error
+
+    def user_facing_name(self, input: dict | None = None) -> str:
+        return _("Fetch")
+
+    def get_activity_description(self, input: dict | None = None) -> str:
+        if input:
+            url = input.get("url", "")
+            short_url = url[:60] + "..." if len(url) > 60 else url
+            return _("Fetching {url}").format(url=short_url)
+        return _("Fetching web page...")
+
+    def get_tool_use_summary(self, input: dict | None = None) -> str | None:
+        if input:
+            return input.get("url", "")[:80]
+        return None
+
+    def is_read_only(self, input: dict | None = None) -> bool:
+        return True
+
+    def is_destructive(self, input: dict | None = None) -> bool:
+        return False

iac_code/tools/write_file.py

@@ -0,0 +1,88 @@
+"""WriteFile tool - creates or overwrites files."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from iac_code.i18n import _
+from iac_code.tools.base import Tool, ToolContext, ToolResult
+
+
+class WriteFileTool(Tool):
+    @property
+    def name(self) -> str:
+        return "write_file"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Write content to a file. Creates the file if it doesn't exist, or "
+            "overwrites it if it does. Creates parent directories as needed. "
+            "Use EditFile for making targeted changes to existing files."
+        )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The path to write the file to.",
+                },
+                "content": {
+                    "type": "string",
+                    "description": "The content to write to the file.",
+                },
+            },
+            "required": ["path", "content"],
+        }
+
+    def normalize_input(self, tool_input: dict[str, Any]) -> None:
+        if "file_path" in tool_input and "path" not in tool_input:
+            tool_input["path"] = tool_input.pop("file_path")
+
+    async def execute(self, *, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        path = tool_input["path"]
+        content = tool_input["content"]
+
+        if not os.path.isabs(path):
+            path = os.path.join(context.cwd, path)
+
+        try:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(content)
+        except PermissionError:
+            return ToolResult.error(f"Permission denied: {path}")
+        except Exception as e:
+            return ToolResult.error(f"Error writing file: {e}")
+
+        lines = content.count("\n") + (1 if content and not content.endswith("\n") else 0)
+        return ToolResult.success(_("Successfully wrote {lines} lines to {path}").format(lines=lines, path=path))
+
+    # UI rendering methods
+    def render_tool_use_message(self, input: dict, *, verbose: bool = False):
+        path = input.get("path", "")
+        if not path:
+            return None
+        return path
+
+    def render_tool_result_message(self, output: str, *, is_error: bool = False, verbose: bool = False):
+        # Write results are already short, show same in both modes
+        return output
+
+    def user_facing_name(self, input: dict | None = None) -> str:
+        return _("Write")
+
+    def get_activity_description(self, input: dict | None = None) -> str:
+        if input:
+            return _("Writing {path}").format(path=input.get("path", ""))
+        return _("Writing file...")
+
+    def is_read_only(self, input: dict | None = None) -> bool:
+        return False
+
+    def is_destructive(self, input: dict | None = None) -> bool:
+        return True

iac_code/types/__init__.py

@@ -0,0 +1,40 @@
+"""Type definitions module"""
+
+from iac_code.types.permissions import PermissionMode, PermissionResult
+from iac_code.types.stream_events import (
+    CompactionEvent,
+    ErrorEvent,
+    MessageEndEvent,
+    MessageStartEvent,
+    PermissionRequestEvent,
+    StreamEvent,
+    TaskNotificationEvent,
+    TextDeltaEvent,
+    ThinkingDeltaEvent,
+    TombstoneEvent,
+    ToolInputDeltaEvent,
+    ToolResultEvent,
+    ToolUseEndEvent,
+    ToolUseStartEvent,
+    Usage,
+)
+
+__all__ = [
+    "CompactionEvent",
+    "ErrorEvent",
+    "MessageEndEvent",
+    "MessageStartEvent",
+    "PermissionMode",
+    "PermissionRequestEvent",
+    "PermissionResult",
+    "StreamEvent",
+    "TaskNotificationEvent",
+    "TextDeltaEvent",
+    "ThinkingDeltaEvent",
+    "TombstoneEvent",
+    "ToolInputDeltaEvent",
+    "ToolResultEvent",
+    "ToolUseEndEvent",
+    "ToolUseStartEvent",
+    "Usage",
+]

iac_code/types/permissions.py

@@ -0,0 +1,26 @@
+"""Permission types for the tool system."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+
+class PermissionMode(str, Enum):
+    """Permission mode."""
+
+    DEFAULT = "default"  # Write operations require user confirmation
+    PLAN = "plan"  # Read-only operations auto-allowed
+    AUTO = "auto"  # All operations auto-allowed
+
+
+@dataclass
+class PermissionResult:
+    """Permission check result."""
+
+    behavior: Literal["allow", "deny", "ask"]
+    message: str = ""
+
+
+PermissionDecision = Literal["always_allow", "always_deny"]

iac_code/types/skill_source.py

@@ -0,0 +1,11 @@
+"""Skill source enum — shared by commands/ and skills/ to avoid circular imports."""
+
+from enum import Enum
+
+
+class SkillSource(str, Enum):
+    """Where a skill was loaded from."""
+
+    BUNDLED = "bundled"
+    USER = "user"
+    PROJECT = "project"