agents-function-tools 0.2.0__py3-none-any.whl

function_tools/openai_tools.py

@@ -0,0 +1,398 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from agents import function_tool
+
+from .archive import ZipArchive
+from .command import CommandPolicy, LocalCommandRunner
+from .errors import FoundationToolError
+from .host import HostInspector
+from .http import HttpPolicy, HttpTextClient
+from .responses import ToolResponse
+from .workspace import Workspace
+
+
+@dataclass(frozen=True)
+class ToolConfig:
+    workspace_root: Path
+    command_programs: Mapping[str, str] = field(default_factory=dict)
+    max_read_bytes: int = 1_000_000
+    max_write_bytes: int = 1_000_000
+    max_command_timeout_seconds: int = 300
+    max_command_output_chars: int = 65_536
+    http_allowed_hosts: frozenset[str] = frozenset()
+    http_max_response_bytes: int = 1_000_000
+    http_timeout_seconds: int = 15
+    environment_variables: frozenset[str] = frozenset()
+
+
+@dataclass(frozen=True)
+class FunctionToolBundle:
+    """Tools grouped by the approval policy that must guard them."""
+
+    safe_read: tuple[Any, ...]
+    workspace_write: tuple[Any, ...]
+    workspace_execution: tuple[Any, ...]
+
+    @property
+    def all(self) -> tuple[Any, ...]:
+        return self.safe_read + self.workspace_write + self.workspace_execution
+
+
+def create_function_tools(config: ToolConfig) -> FunctionToolBundle:
+    """Create SDK function tools bound to one host-controlled workspace and policy."""
+
+    workspace = Workspace(
+        config.workspace_root,
+        max_read_bytes=config.max_read_bytes,
+        max_write_bytes=config.max_write_bytes,
+    )
+    archives = ZipArchive(workspace)
+    host = HostInspector(config.environment_variables)
+    http = HttpTextClient(
+        HttpPolicy(
+            allowed_hosts=config.http_allowed_hosts,
+            max_response_bytes=config.http_max_response_bytes,
+            timeout_seconds=config.http_timeout_seconds,
+        )
+    )
+    command_policy = CommandPolicy(
+        programs=config.command_programs,
+        max_timeout_seconds=config.max_command_timeout_seconds,
+        max_output_chars=config.max_command_output_chars,
+    )
+    command_runner = LocalCommandRunner(
+        workspace,
+        command_policy,
+    )
+
+    @function_tool
+    def workspace_list(path: str = ".", recursive: bool = False, max_entries: int = 200) -> str:
+        """List files inside the configured workspace.
+
+        This is read-only and retry-safe. Paths must be workspace-relative. Set
+        recursive only when nested entries are needed; output is capped by max_entries.
+        """
+
+        return _respond(
+            "workspace_list",
+            "safe_read",
+            lambda: workspace.list_directory(path, recursive=recursive, max_entries=max_entries),
+        )
+
+    @function_tool
+    def workspace_read_text(path: str, max_bytes: int | None = None) -> str:
+        """Read one UTF-8 text file inside the configured workspace.
+
+        This is read-only and retry-safe. Binary files, oversized files, absolute
+        paths, and paths outside the workspace are rejected.
+        """
+
+        return _respond(
+            "workspace_read_text",
+            "safe_read",
+            lambda: workspace.read_text(path, max_bytes=max_bytes),
+        )
+
+    @function_tool
+    def workspace_stat(path: str) -> str:
+        """Return type, size, and timestamps for one workspace-relative path.
+
+        This is read-only and retry-safe. File content is never returned.
+        """
+
+        return _respond("workspace_stat", "safe_read", lambda: workspace.stat_path(path))
+
+    @function_tool
+    def workspace_find(
+        pattern: str,
+        path: str = ".",
+        kind: str = "any",
+        max_entries: int = 200,
+    ) -> str:
+        """Find workspace paths with a glob-style filename pattern.
+
+        This is read-only and retry-safe. Restrict kind to file, directory, or
+        symlink when a narrower search is useful. Results are capped.
+        """
+
+        return _respond(
+            "workspace_find",
+            "safe_read",
+            lambda: workspace.find_paths(pattern, path=path, kind=kind, max_entries=max_entries),
+        )
+
+    @function_tool
+    def workspace_hash_file(path: str, algorithm: str = "sha256") -> str:
+        """Calculate a SHA-256, SHA-512, or BLAKE2b hash of one bounded workspace file.
+
+        This is read-only and retry-safe. File contents are not returned.
+        """
+
+        return _respond(
+            "workspace_hash_file",
+            "safe_read",
+            lambda: workspace.hash_file(path, algorithm=algorithm),
+        )
+
+    @function_tool
+    def workspace_disk_usage() -> str:
+        """Return storage capacity available to the configured workspace.
+
+        This is read-only and retry-safe. It does not inspect other filesystems.
+        """
+
+        return _respond("workspace_disk_usage", "safe_read", workspace.disk_usage)
+
+    @function_tool
+    def fetch_https_text(url: str) -> str:
+        """Fetch a bounded text response from a host-configured HTTPS allowlist.
+
+        This is read-only but not retry-safe because remote content may change.
+        Redirects, credentials in URLs, private network addresses, binary content,
+        and hosts not configured by the service are rejected.
+        """
+
+        return _respond("fetch_https_text", "safe_read", lambda: http.fetch(url))
+
+    @function_tool
+    def host_system_info() -> str:
+        """Return non-sensitive operating system and Python runtime metadata.
+
+        This is read-only and retry-safe. Secrets, users, process lists, network
+        configuration, and installed software are intentionally excluded.
+        """
+
+        return _respond("host_system_info", "safe_read", host.system_info)
+
+    @function_tool
+    def host_current_time() -> str:
+        """Return the current UTC timestamp from the host.
+
+        This is read-only and not retry-safe because time advances.
+        """
+
+        return _respond("host_current_time", "safe_read", host.current_time)
+
+    @function_tool
+    def host_environment_get(name: str) -> str:
+        """Read one explicitly allowlisted environment variable.
+
+        This is read-only and retry-safe. The service configuration controls which
+        variable names are readable; no variables are readable by default.
+        """
+
+        return _respond("host_environment_get", "safe_read", lambda: host.environment(name))
+
+    @function_tool
+    def command_policy_info() -> str:
+        """Describe available command aliases and execution limits.
+
+        This is read-only and retry-safe. Host executable paths are not revealed.
+        """
+
+        return _respond("command_policy_info", "safe_read", command_policy.describe)
+
+    @function_tool(needs_approval=True)
+    def workspace_write_text(
+        path: str,
+        content: str,
+        overwrite: bool = False,
+        create_parents: bool = False,
+    ) -> str:
+        """Write one UTF-8 text file inside the configured workspace.
+
+        This changes the workspace and is not retry-safe unless the caller uses the
+        same content and overwrite policy. Expose it only after write approval.
+        """
+
+        return _respond(
+            "workspace_write_text",
+            "workspace_write",
+            lambda: workspace.write_text(
+                path,
+                content,
+                overwrite=overwrite,
+                create_parents=create_parents,
+            ),
+        )
+
+    @function_tool(needs_approval=True)
+    def workspace_create_directory(path: str, parents: bool = True, exist_ok: bool = False) -> str:
+        """Create a directory inside the configured workspace.
+
+        This changes the workspace. Expose it only after write approval. The
+        workspace root itself is protected.
+        """
+
+        return _respond(
+            "workspace_create_directory",
+            "workspace_write",
+            lambda: workspace.create_directory(path, parents=parents, exist_ok=exist_ok),
+        )
+
+    @function_tool(needs_approval=True)
+    def workspace_copy_file(
+        source: str,
+        destination: str,
+        overwrite: bool = False,
+        create_parents: bool = False,
+    ) -> str:
+        """Copy one regular file inside the configured workspace.
+
+        This changes the workspace and is not retry-safe. Source symlinks are
+        rejected. Expose it only after write approval.
+        """
+
+        return _respond(
+            "workspace_copy_file",
+            "workspace_write",
+            lambda: workspace.copy_file(
+                source,
+                destination,
+                overwrite=overwrite,
+                create_parents=create_parents,
+            ),
+        )
+
+    @function_tool(needs_approval=True)
+    def workspace_move_path(
+        source: str,
+        destination: str,
+        overwrite: bool = False,
+        create_parents: bool = False,
+    ) -> str:
+        """Move one file or directory inside the configured workspace.
+
+        This changes paths and can overwrite a destination when explicitly enabled.
+        It requires approval and is not retry-safe.
+        """
+
+        return _respond(
+            "workspace_move_path",
+            "workspace_write",
+            lambda: workspace.move_path(
+                source,
+                destination,
+                overwrite=overwrite,
+                create_parents=create_parents,
+            ),
+        )
+
+    @function_tool
+    def zip_list_entries(path: str, max_entries: int = 200) -> str:
+        """List bounded metadata for entries in a workspace ZIP archive.
+
+        This is read-only and retry-safe. Archive content is not extracted.
+        """
+
+        return _respond(
+            "zip_list_entries",
+            "safe_read",
+            lambda: archives.list_entries(path, max_entries=max_entries),
+        )
+
+    @function_tool(needs_approval=True)
+    def zip_create(paths: list[str], destination: str, overwrite: bool = False) -> str:
+        """Create a ZIP archive from workspace files and directories.
+
+        This changes the workspace and is not retry-safe. Symlinks and inputs above
+        the configured size limit are rejected. Expose it only after write approval.
+        """
+
+        return _respond(
+            "zip_create",
+            "workspace_write",
+            lambda: archives.create(paths, destination, overwrite=overwrite),
+        )
+
+    @function_tool(needs_approval=True)
+    def zip_extract(path: str, destination: str, overwrite: bool = False) -> str:
+        """Extract a workspace ZIP archive into a workspace directory.
+
+        This changes the workspace and requires approval. Path traversal, archive
+        symlinks, non-empty destinations, and oversized output are rejected.
+        """
+
+        return _respond(
+            "zip_extract",
+            "workspace_write",
+            lambda: archives.extract(path, destination, overwrite=overwrite),
+        )
+
+    @function_tool(needs_approval=True)
+    def workspace_delete_path(path: str, recursive: bool = False) -> str:
+        """Delete a file, symlink, empty directory, or explicitly recursive directory.
+
+        This is destructive and not retry-safe. Expose it only after delete approval.
+        Paths outside the workspace and the workspace root are always rejected.
+        """
+
+        return _respond(
+            "workspace_delete_path",
+            "workspace_write",
+            lambda: workspace.delete_path(path, recursive=recursive),
+        )
+
+    @function_tool(needs_approval=True)
+    def run_local_command(
+        program: str,
+        args: list[str],
+        cwd: str = ".",
+        timeout_seconds: int = 30,
+    ) -> str:
+        """Run one host-allowlisted program without a shell.
+
+        This can change the workspace and is not generally retry-safe. Expose it only
+        after execution approval. Use a configured program alias and separate args;
+        shell syntax is not interpreted. The host must provide OS-level isolation.
+        """
+
+        return _respond(
+            "run_local_command",
+            "workspace_execution",
+            lambda: command_runner.run(program, args, cwd=cwd, timeout_seconds=timeout_seconds),
+        )
+
+    return FunctionToolBundle(
+        safe_read=(
+            workspace_list,
+            workspace_read_text,
+            workspace_stat,
+            workspace_find,
+            workspace_hash_file,
+            workspace_disk_usage,
+            fetch_https_text,
+            host_system_info,
+            host_current_time,
+            host_environment_get,
+            command_policy_info,
+            zip_list_entries,
+        ),
+        workspace_write=(
+            workspace_write_text,
+            workspace_create_directory,
+            workspace_copy_file,
+            workspace_move_path,
+            zip_create,
+            zip_extract,
+            workspace_delete_path,
+        ),
+        workspace_execution=(run_local_command,),
+    )
+
+
+def _respond(tool: str, effect: str, action: Callable[[], Any]) -> str:
+    try:
+        return ToolResponse.success(tool, effect, action()).to_json()
+    except FoundationToolError as error:
+        return ToolResponse.failure(tool, effect, error).to_json()
+    except Exception:
+        error = FoundationToolError(
+            "INTERNAL_ERROR", "The tool failed without exposing internal details."
+        )
+        return ToolResponse.failure(tool, effect, error).to_json()

function_tools/responses.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from .errors import FoundationToolError
+
+
+@dataclass(frozen=True)
+class ToolFailure:
+    code: str
+    message: str
+    retryable: bool = False
+
+
+@dataclass(frozen=True)
+class ToolResponse:
+    ok: bool
+    tool: str
+    effect: str
+    data: Any = None
+    error: ToolFailure | None = None
+
+    @classmethod
+    def success(cls, tool: str, effect: str, data: Any) -> ToolResponse:
+        return cls(ok=True, tool=tool, effect=effect, data=data)
+
+    @classmethod
+    def failure(cls, tool: str, effect: str, error: FoundationToolError) -> ToolResponse:
+        return cls(
+            ok=False,
+            tool=tool,
+            effect=effect,
+            error=ToolFailure(error.code, error.message, error.retryable),
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False, separators=(",", ":"))