aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/middleware/tools/skill_resource.py

@@ -0,0 +1,338 @@
+"""Skill-attributed resource discovery and loading tool."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import posixpath
+import re
+from typing import Annotated, Any, Final, TypedDict
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, SkipValidation
+
+from aip_agents.middleware.schema import MiddlewareToolConfig
+from aip_agents.skills.errors import SkillValidationError
+from aip_agents.skills.validation import validate_skill_name
+
+MAX_SKILL_RESOURCE_CHARS: Final[int] = 20_000
+_TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+__all__ = [
+    "MAX_SKILL_RESOURCE_CHARS",
+    "SkillResourceInput",
+    "SkillResourceResult",
+    "SkillResourceSummary",
+    "SkillResourceTool",
+]
+
+
+class SkillResourceInput(BaseModel):
+    """Input schema for skill_resource."""
+
+    name: str = Field(description="Skill name that owns the resource")
+    path: str | None = Field(default=None, description="Resource backend path or skill-relative path")
+    query: str | None = Field(
+        default=None, description="Optional keyword query used to pick a resource from the manifest"
+    )
+    max_chars: int | None = Field(default=None, description="Maximum characters to return for text resources")
+
+
+class SkillResourceSummary(TypedDict, total=False):
+    """Manifest-backed resource metadata."""
+
+    backend_path: str
+    relative_path: str
+    resource_type: str
+    size_bytes: int
+    is_binary: bool
+    summary: str | None
+    score: int
+
+
+class SkillResourceResult(TypedDict, total=False):
+    """Structured output returned by `skill_resource`."""
+
+    name: str
+    backend_root: str | None
+    resource_index_path: str | None
+    resource_path: str | None
+    relative_path: str | None
+    resource_type: str | None
+    size_bytes: int | None
+    is_binary: bool | None
+    summary: str | None
+    content: str
+    content_hash: str
+    budget_truncated: bool
+    warnings: list[str]
+    matches: list[SkillResourceSummary]
+    error: str
+
+
+class SkillResourceTool(BaseTool):
+    """Tool for skill-attributed support-resource discovery and loading."""
+
+    name: str = "skill_resource"
+    description: str = (
+        "Discover or load a staged skill support resource through the skill manifest. "
+        "Use this for references, examples, scripts, and assets after skill_load so resource use is skill-attributed."
+    )
+    args_schema: type[BaseModel] = SkillResourceInput  # type: ignore[assignment]
+    tool_config_schema: type[BaseModel] = MiddlewareToolConfig
+    backend: Annotated[Any, SkipValidation()]
+    destination_root: str = "/skills"
+    skill_inventory: Annotated[Any, SkipValidation()]
+
+    def _run(
+        self,
+        name: str,
+        path: str | None = None,
+        query: str | None = None,
+        max_chars: int | None = None,
+    ) -> SkillResourceResult:
+        requested_name = name.strip()
+        try:
+            validate_skill_name(requested_name)
+        except SkillValidationError as exc:
+            return self._error_result(requested_name, f"Invalid skill name: {exc}")
+
+        skill_names = {skill.name for skill in self.skill_inventory() or []}
+        if requested_name not in skill_names:
+            return self._error_result(requested_name, f"Skill not found: {requested_name}")
+
+        backend_root = posixpath.join(self.destination_root, requested_name)
+        resource_index_path = posixpath.join(backend_root, ".aip-skill-index.json")
+        resources_result = self._load_manifest(requested_name, backend_root, resource_index_path)
+        if "error" in resources_result:
+            return resources_result
+
+        resources = resources_result["matches"]
+        selected = self._select_resource(resources, backend_root=backend_root, path=path, query=query)
+        if selected is None:
+            if path:
+                return self._error_result(requested_name, f"Resource not found in skill manifest: {path}")
+            return {
+                "name": requested_name,
+                "backend_root": backend_root,
+                "resource_index_path": resource_index_path,
+                "resource_path": None,
+                "relative_path": None,
+                "resource_type": None,
+                "size_bytes": None,
+                "is_binary": None,
+                "summary": None,
+                "content": "",
+                "content_hash": "",
+                "budget_truncated": False,
+                "warnings": ["No resource selected; inspect matches or provide path/query."],
+                "matches": self._rank_resources(resources, query),
+            }
+
+        return self._load_resource(requested_name, backend_root, resource_index_path, selected, max_chars=max_chars)
+
+    def _load_manifest(self, name: str, backend_root: str, resource_index_path: str) -> SkillResourceResult:
+        try:
+            manifest = json.loads(self.backend.read_bytes(resource_index_path).decode("utf-8"))
+        except Exception as exc:  # pragma: no cover
+            return self._error_result(
+                name, f"Unable to read resource manifest at {resource_index_path}: {exc}"
+            )  # pragma: no cover
+
+        resources = manifest.get("resources", [])
+        if not isinstance(resources, list):
+            return self._error_result(
+                name, f"Invalid resource manifest at {resource_index_path}: resources must be a list"
+            )
+
+        summaries: list[SkillResourceSummary] = []
+        for item in resources:
+            if not isinstance(item, dict):
+                continue
+            relative_path = self._normalize_manifest_relative_path(str(item.get("relative_path", "")))
+            backend_path = self._normalize_manifest_backend_path(
+                str(item.get("backend_path", "")), backend_root=backend_root, relative_path=relative_path
+            )
+            size_bytes = self._coerce_size_bytes(item.get("size_bytes", 0))
+            if backend_path is None or relative_path is None:
+                continue
+            summaries.append(
+                {
+                    "backend_path": backend_path,
+                    "relative_path": relative_path,
+                    "resource_type": str(item.get("resource_type", "asset")),
+                    "size_bytes": size_bytes,
+                    "is_binary": bool(item.get("is_binary", False)),
+                    "summary": item.get("summary") if item.get("summary") is None else str(item.get("summary")),
+                }
+            )
+        return {
+            "name": name,
+            "backend_root": backend_root,
+            "resource_index_path": resource_index_path,
+            "matches": summaries,
+        }
+
+    def _select_resource(
+        self,
+        resources: list[SkillResourceSummary],
+        *,
+        backend_root: str,
+        path: str | None,
+        query: str | None,
+    ) -> SkillResourceSummary | None:
+        normalized_path = self._normalize_requested_path(path, backend_root=backend_root) if path else None
+        if normalized_path:
+            for resource in resources:
+                if normalized_path in {resource["relative_path"], resource["backend_path"]}:
+                    return resource
+            return None
+        ranked = self._rank_resources(resources, query)
+        if query and ranked and ranked[0].get("score", 0) > 0:
+            return ranked[0]
+        return None
+
+    def _load_resource(
+        self,
+        name: str,
+        backend_root: str,
+        resource_index_path: str,
+        resource: SkillResourceSummary,
+        *,
+        max_chars: int | None,
+    ) -> SkillResourceResult:
+        resource_path = resource["backend_path"]
+        try:
+            raw_content = self.backend.read_bytes(resource_path)
+        except Exception as exc:
+            return self._resource_error_result(
+                name, backend_root, resource_index_path, resource, f"Unable to read resource at {resource_path}: {exc}"
+            )
+        content_hash = f"sha256:{hashlib.sha256(raw_content).hexdigest()}"
+        warnings: list[str] = []
+        content = ""
+        budget_truncated = False
+        if resource["is_binary"]:
+            warnings.append("Binary resource metadata returned without raw content.")
+        else:
+            decoded = raw_content.decode("utf-8", errors="replace")
+            limit = max(1, min(max_chars or MAX_SKILL_RESOURCE_CHARS, MAX_SKILL_RESOURCE_CHARS))
+            budget_truncated = len(decoded) > limit
+            content = decoded[:limit] if budget_truncated else decoded
+            if budget_truncated:
+                warnings.append(f"Resource content truncated to {limit} characters.")
+
+        return {
+            "name": name,
+            "backend_root": backend_root,
+            "resource_index_path": resource_index_path,
+            "resource_path": resource_path,
+            "relative_path": resource["relative_path"],
+            "resource_type": resource["resource_type"],
+            "size_bytes": resource["size_bytes"],
+            "is_binary": resource["is_binary"],
+            "summary": resource.get("summary"),
+            "content": content,
+            "content_hash": content_hash,
+            "budget_truncated": budget_truncated,
+            "warnings": warnings,
+            "matches": [resource],
+        }
+
+    def _rank_resources(self, resources: list[SkillResourceSummary], query: str | None) -> list[SkillResourceSummary]:
+        if not query:
+            return sorted(resources, key=lambda item: item["relative_path"])
+        query_tokens = set(_TOKEN_RE.findall(query.lower()))
+        ranked: list[SkillResourceSummary] = []
+        for resource in resources:
+            haystack = " ".join(
+                [resource["relative_path"], resource["resource_type"], str(resource.get("summary") or "")]
+            ).lower()
+            score = sum(1 for token in query_tokens if token in haystack)
+            ranked.append({**resource, "score": score})
+        return sorted(ranked, key=lambda item: (-int(item.get("score", 0)), item["relative_path"]))
+
+    def _normalize_requested_path(self, path: str | None, *, backend_root: str) -> str | None:
+        if path is None:
+            return None  # pragma: no cover
+        normalized = posixpath.normpath(path.strip().replace("\\", "/"))
+        if normalized in {"", "."}:
+            return None
+        if normalized.startswith(f"{backend_root}/"):
+            return normalized
+        if normalized.startswith("/"):
+            return normalized  # pragma: no cover
+        return normalized.lstrip("/")
+
+    def _normalize_manifest_relative_path(self, relative_path: str) -> str | None:
+        normalized = relative_path.strip().replace("\\", "/")
+        if not normalized or normalized.startswith("/") or "\x00" in normalized:
+            return None
+        if any(part == ".." for part in normalized.split("/")):
+            return None
+        normalized = posixpath.normpath(normalized)
+        if normalized in {"", "."}:
+            return None  # pragma: no cover
+        return normalized
+
+    def _normalize_manifest_backend_path(
+        self, backend_path: str, *, backend_root: str, relative_path: str | None
+    ) -> str | None:
+        if relative_path is None:
+            return None
+        normalized = posixpath.normpath(backend_path.strip().replace("\\", "/"))
+        expected = posixpath.normpath(posixpath.join(backend_root, relative_path))
+        if normalized != expected or not normalized.startswith(f"{backend_root}/"):
+            return None
+        return normalized
+
+    def _coerce_size_bytes(self, value: Any) -> int:
+        try:
+            return max(0, int(value))
+        except (TypeError, ValueError):
+            return 0
+
+    def _resource_error_result(
+        self,
+        name: str,
+        backend_root: str,
+        resource_index_path: str,
+        resource: SkillResourceSummary,
+        error: str,
+    ) -> SkillResourceResult:
+        return {
+            "name": name,
+            "backend_root": backend_root,
+            "resource_index_path": resource_index_path,
+            "resource_path": resource["backend_path"],
+            "relative_path": resource["relative_path"],
+            "resource_type": resource["resource_type"],
+            "size_bytes": resource["size_bytes"],
+            "is_binary": resource["is_binary"],
+            "summary": resource.get("summary"),
+            "content": "",
+            "content_hash": "",
+            "budget_truncated": False,
+            "warnings": [error],
+            "matches": [resource],
+            "error": error,
+        }
+
+    def _error_result(self, name: str, error: str) -> SkillResourceResult:
+        return {
+            "name": name,
+            "backend_root": None,
+            "resource_index_path": None,
+            "resource_path": None,
+            "relative_path": None,
+            "resource_type": None,
+            "size_bytes": None,
+            "is_binary": None,
+            "summary": None,
+            "content": "",
+            "content_hash": "",
+            "budget_truncated": False,
+            "warnings": [error],
+            "matches": [],
+            "error": error,
+        }

aip_agents/middleware/tools/write_file.py

@@ -0,0 +1,114 @@
+"""Write file tool for agents.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+TODO: When migrating to deepagents, replace this entire file with:
+    from deepagents.middleware.tools.write_file import WriteFileTool, WriteFileInput
+
+    Note: deepagents WriteFileTool uses ToolRuntime pattern instead of BaseTool.
+    We'll need to adapt our middleware to use deepagents' tool registration.
+"""
+
+from typing import Annotated, Any
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, SkipValidation
+
+from aip_agents.middleware.schema import MiddlewareToolConfig
+
+WRITE_FILE_TOOL_DESCRIPTION = """Writes to a new file in the filesystem.
+
+Usage:
+- The write_file tool will create the a new file.
+- Prefer to edit existing files (with the edit_file tool) over creating new ones when possible.
+"""
+
+
+class WriteFileInput(BaseModel):
+    """Input schema for ``write_file``.
+
+    Attributes:
+        path (str): Absolute destination path for the new file.
+        content (str): UTF-8 text content to write.
+    """
+
+    path: str = Field(description="Absolute path to the file to write. Must be absolute, not relative.")
+    content: str = Field(description="Content to write to the file.")
+
+
+class WriteFileTool(BaseTool):
+    """Create a new file in the configured filesystem backend.
+
+    This tool enforces create-only semantics: if the target path already exists,
+    it returns an error instead of overwriting the file.
+
+    Attributes:
+        name (str): Tool identifier exposed to the model.
+        description (str): Human-readable usage guidance for the model.
+        args_schema (type[BaseModel]): Pydantic schema for tool arguments.
+        backend (Any): Filesystem backend implementing ``read`` and ``write``.
+    """
+
+    name: str = "write_file"
+    description: str = WRITE_FILE_TOOL_DESCRIPTION
+    args_schema: type[BaseModel] = WriteFileInput
+    tool_config_schema: type[BaseModel] = MiddlewareToolConfig
+    backend: Annotated[Any, SkipValidation()]  # BackendProtocol - skip validation for Protocol type
+
+    def _file_exists(self, path: str) -> bool:
+        """Check whether a filesystem entry already exists at ``path``.
+
+        Args:
+            path (str): Absolute path to inspect.
+
+        Returns:
+            bool: ``True`` when a file or directory exists at ``path``;
+            ``False`` when the path does not exist.
+        """
+        try:
+            self.backend.read(path, line_offset=0, limit=1)
+            return True
+        except FileNotFoundError:
+            return False
+        except IsADirectoryError:
+            return True
+
+    def _run(self, path: str, content: str) -> str:
+        """Create a new file with the provided content.
+
+        Args:
+            path (str): Absolute destination path for the new file.
+            content (str): Full file content to persist.
+
+        Returns:
+            str: Success or error status message. Returns
+            ``"Successfully wrote {n} characters to {path}"`` on success,
+            or ``"Error: ..."`` when creation fails.
+
+        Notes:
+            This method catches runtime exceptions and converts them to
+            user-facing error messages; it does not raise exceptions.
+
+        Examples:
+            >>> tool._run(path="/reports/summary.md", content="# Summary")
+            'Successfully wrote 9 characters to /reports/summary.md'
+            >>> tool._run(path="/reports/summary.md", content="# New")
+            'Error: File already exists: /reports/summary.md'
+        """
+        try:
+            if self._file_exists(path):
+                return f"Error: File already exists: {path}"
+
+            if hasattr(self.backend, "ensure_parent_dir"):
+                self.backend.ensure_parent_dir(path)
+
+            result = self.backend.write(path, content)
+            if result.success:
+                return f"Successfully wrote {len(content)} characters to {path}"
+            else:
+                return f"Error: {result.error or 'Unknown error'}"
+        except PermissionError:
+            return f"Error: Permission denied: {path}"
+        except Exception as e:
+            return f"Error: {str(e)}"