agents-function-tools 0.3.0__tar.gz → 0.4.0__tar.gz

{agents_function_tools-0.3.0 → agents_function_tools-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agents-function-tools
-Version: 0.3.0
+Version: 0.4.0
 Summary: Portable, policy-friendly system function tools for AI applications.
 License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
@@ -26,14 +26,14 @@ python -m pip install agents-function-tools
 
 ## Included tools
 
-| Category | Tools | Tool group |
+| Category | Tools | Recommended selector |
 |---|---|---|
-| Workspace read | List, read UTF-8, inspect metadata, glob-style find, hash files, disk usage | `read` |
-| Workspace write | Write text, create directories, copy a regular file, move a path, delete a path | `write` |
-| ZIP | List archive entries; create and extract bounded ZIP archives | `read` / `write` |
-| Network | Fetch bounded HTTPS text from configured hosts | `read` |
-| Host | Non-sensitive system info, UTC time, explicitly allowlisted environment variables | `read` |
-| Commands | Describe configured aliases; run one allowlisted executable with `shell=False` | `read` / `execute` |
+| Workspace read | List, read UTF-8, inspect metadata, glob-style find, hash files, disk usage | `files.read` |
+| Workspace write | Write text, create directories, copy a regular file, move a path, delete a path | `files.write` |
+| ZIP | List archive entries; create and extract bounded ZIP archives | `files.read` / `files.write` |
+| Network | Fetch bounded HTTPS text; optionally build search URLs, resolve configured hosts, and probe configured TCP ports | `network.read` |
+| Host | Non-sensitive system info, UTC time, explicitly allowlisted environment variables | `host.inspect` |
+| Processes and commands | Describe configured aliases; optionally inspect allowlisted process names; run one allowlisted executable with `shell=False` | `process.inspect` / `process.execute` |
 
 Every tool returns the same JSON envelope with `ok`, `tool`, `effect`, `data`, and `error` fields. Paths are always relative to a configured workspace root.
 
@@ -46,7 +46,7 @@ Every tool returns the same JSON envelope with `ok`, `tool`, `effect`, `data`, a
 - Every workspace mutation and local command requires the SDK approval gate in addition to the orchestration approval policy. File copy accepts regular, non-symlink source files only.
 - ZIP creation rejects symlinks; ZIP extraction rejects path traversal and symlink entries before writing files.
 - HTTPS fetching requires an exact host allowlist, rejects redirects, URL credentials, and non-default ports, accepts only text-like content types, and blocks resolved private or loopback addresses. No host is enabled by default. Deployment still needs an egress proxy or firewall: application-layer DNS checks do not replace network isolation.
-- Host diagnostics intentionally exclude user identities, process lists, network configuration, installed software, and environment variables except for names explicitly configured by the host.
+- Host diagnostics intentionally exclude user identities, network configuration, installed software, and environment variables except for names explicitly configured by the host. Process diagnostics are separate, disabled by default, and return only configured process names, PIDs, states, and start times.
 - Command execution accepts an argument array, never a shell string. Programs must be mapped by the host application, execution has a timeout, and output is truncated.
 - The local command runner is not an OS security sandbox. Production deployment must run the service or runner inside the company-approved container/sandbox with no production secrets and restricted network access.
 - Approval remains the orchestration layer's responsibility. Only attach `tools.write` or `tools.execute` after the matching approval policy has been validated.
@@ -67,11 +67,15 @@ tools = create_tools(Path("./workspace"))
 agent = Agent(
     name="Workspace assistant",
     instructions="Use workspace tools when needed.",
-    tools=list(tools.read),
+    tools=list(tools.files.read),
 )
 ```
 
-`tools.read` is read-only. `tools.write` and `tools.execute` require approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.
+Use the narrowest domain selector: `tools.files`, `tools.network`, `tools.host`, or `tools.process`. The v0.3-style `tools.read`, `tools.write`, and `tools.execute` selectors remain available for compatibility, but combine more capabilities. Every `*.write` and `*.execute` tool requires approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.
+
+## Design specs
+
+- [v0.4 tool expansion spec](docs/v0.4-tool-expansion-spec.md)
 
 For configured commands, HTTPS hosts, or readable environment variables, use `ToolConfig`:
 
@@ -91,6 +95,25 @@ tools = create_tools(
 )
 ```
 
+Network diagnostics and process inspection are disabled until explicitly configured:
+
+```python
+from function_tools import ToolConfig, create_tools
+
+tools = create_tools(
+    ToolConfig(
+        workspace_root="./workspace",
+        http_allowed_hosts=frozenset({"api.example.internal"}),
+        search_engines={"bing": "https://www.bing.com/search"},
+        network_allowed_ports=frozenset({443}),
+        process_name_allowlist=frozenset({"python.exe"}),
+    )
+)
+
+network_tools = tools.network.read
+process_tools = tools.process.inspect
+```
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE).

{agents_function_tools-0.3.0 → agents_function_tools-0.4.0}/README.md

@@ -10,14 +10,14 @@ python -m pip install agents-function-tools
 
 ## Included tools
 
-| Category | Tools | Tool group |
+| Category | Tools | Recommended selector |
 |---|---|---|
-| Workspace read | List, read UTF-8, inspect metadata, glob-style find, hash files, disk usage | `read` |
-| Workspace write | Write text, create directories, copy a regular file, move a path, delete a path | `write` |
-| ZIP | List archive entries; create and extract bounded ZIP archives | `read` / `write` |
-| Network | Fetch bounded HTTPS text from configured hosts | `read` |
-| Host | Non-sensitive system info, UTC time, explicitly allowlisted environment variables | `read` |
-| Commands | Describe configured aliases; run one allowlisted executable with `shell=False` | `read` / `execute` |
+| Workspace read | List, read UTF-8, inspect metadata, glob-style find, hash files, disk usage | `files.read` |
+| Workspace write | Write text, create directories, copy a regular file, move a path, delete a path | `files.write` |
+| ZIP | List archive entries; create and extract bounded ZIP archives | `files.read` / `files.write` |
+| Network | Fetch bounded HTTPS text; optionally build search URLs, resolve configured hosts, and probe configured TCP ports | `network.read` |
+| Host | Non-sensitive system info, UTC time, explicitly allowlisted environment variables | `host.inspect` |
+| Processes and commands | Describe configured aliases; optionally inspect allowlisted process names; run one allowlisted executable with `shell=False` | `process.inspect` / `process.execute` |
 
 Every tool returns the same JSON envelope with `ok`, `tool`, `effect`, `data`, and `error` fields. Paths are always relative to a configured workspace root.
 
@@ -30,7 +30,7 @@ Every tool returns the same JSON envelope with `ok`, `tool`, `effect`, `data`, a
 - Every workspace mutation and local command requires the SDK approval gate in addition to the orchestration approval policy. File copy accepts regular, non-symlink source files only.
 - ZIP creation rejects symlinks; ZIP extraction rejects path traversal and symlink entries before writing files.
 - HTTPS fetching requires an exact host allowlist, rejects redirects, URL credentials, and non-default ports, accepts only text-like content types, and blocks resolved private or loopback addresses. No host is enabled by default. Deployment still needs an egress proxy or firewall: application-layer DNS checks do not replace network isolation.
-- Host diagnostics intentionally exclude user identities, process lists, network configuration, installed software, and environment variables except for names explicitly configured by the host.
+- Host diagnostics intentionally exclude user identities, network configuration, installed software, and environment variables except for names explicitly configured by the host. Process diagnostics are separate, disabled by default, and return only configured process names, PIDs, states, and start times.
 - Command execution accepts an argument array, never a shell string. Programs must be mapped by the host application, execution has a timeout, and output is truncated.
 - The local command runner is not an OS security sandbox. Production deployment must run the service or runner inside the company-approved container/sandbox with no production secrets and restricted network access.
 - Approval remains the orchestration layer's responsibility. Only attach `tools.write` or `tools.execute` after the matching approval policy has been validated.
@@ -51,11 +51,15 @@ tools = create_tools(Path("./workspace"))
 agent = Agent(
     name="Workspace assistant",
     instructions="Use workspace tools when needed.",
-    tools=list(tools.read),
+    tools=list(tools.files.read),
 )
 ```
 
-`tools.read` is read-only. `tools.write` and `tools.execute` require approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.
+Use the narrowest domain selector: `tools.files`, `tools.network`, `tools.host`, or `tools.process`. The v0.3-style `tools.read`, `tools.write`, and `tools.execute` selectors remain available for compatibility, but combine more capabilities. Every `*.write` and `*.execute` tool requires approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.
+
+## Design specs
+
+- [v0.4 tool expansion spec](docs/v0.4-tool-expansion-spec.md)
 
 For configured commands, HTTPS hosts, or readable environment variables, use `ToolConfig`:
 
@@ -75,6 +79,25 @@ tools = create_tools(
 )
 ```
 
+Network diagnostics and process inspection are disabled until explicitly configured:
+
+```python
+from function_tools import ToolConfig, create_tools
+
+tools = create_tools(
+    ToolConfig(
+        workspace_root="./workspace",
+        http_allowed_hosts=frozenset({"api.example.internal"}),
+        search_engines={"bing": "https://www.bing.com/search"},
+        network_allowed_ports=frozenset({443}),
+        process_name_allowlist=frozenset({"python.exe"}),
+    )
+)
+
+network_tools = tools.network.read
+process_tools = tools.process.inspect
+```
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE).

{agents_function_tools-0.3.0 → agents_function_tools-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agents-function-tools"
-version = "0.3.0"
+version = "0.4.0"
 description = "Portable, policy-friendly system function tools for AI applications."
 readme = "README.md"
 requires-python = ">=3.10"

{agents_function_tools-0.3.0 → agents_function_tools-0.4.0}/src/agents_function_tools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agents-function-tools
-Version: 0.3.0
+Version: 0.4.0
 Summary: Portable, policy-friendly system function tools for AI applications.
 License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
@@ -26,14 +26,14 @@ python -m pip install agents-function-tools
 
 ## Included tools
 
-| Category | Tools | Tool group |
+| Category | Tools | Recommended selector |
 |---|---|---|
-| Workspace read | List, read UTF-8, inspect metadata, glob-style find, hash files, disk usage | `read` |
-| Workspace write | Write text, create directories, copy a regular file, move a path, delete a path | `write` |
-| ZIP | List archive entries; create and extract bounded ZIP archives | `read` / `write` |
-| Network | Fetch bounded HTTPS text from configured hosts | `read` |
-| Host | Non-sensitive system info, UTC time, explicitly allowlisted environment variables | `read` |
-| Commands | Describe configured aliases; run one allowlisted executable with `shell=False` | `read` / `execute` |
+| Workspace read | List, read UTF-8, inspect metadata, glob-style find, hash files, disk usage | `files.read` |
+| Workspace write | Write text, create directories, copy a regular file, move a path, delete a path | `files.write` |
+| ZIP | List archive entries; create and extract bounded ZIP archives | `files.read` / `files.write` |
+| Network | Fetch bounded HTTPS text; optionally build search URLs, resolve configured hosts, and probe configured TCP ports | `network.read` |
+| Host | Non-sensitive system info, UTC time, explicitly allowlisted environment variables | `host.inspect` |
+| Processes and commands | Describe configured aliases; optionally inspect allowlisted process names; run one allowlisted executable with `shell=False` | `process.inspect` / `process.execute` |
 
 Every tool returns the same JSON envelope with `ok`, `tool`, `effect`, `data`, and `error` fields. Paths are always relative to a configured workspace root.
 
@@ -46,7 +46,7 @@ Every tool returns the same JSON envelope with `ok`, `tool`, `effect`, `data`, a
 - Every workspace mutation and local command requires the SDK approval gate in addition to the orchestration approval policy. File copy accepts regular, non-symlink source files only.
 - ZIP creation rejects symlinks; ZIP extraction rejects path traversal and symlink entries before writing files.
 - HTTPS fetching requires an exact host allowlist, rejects redirects, URL credentials, and non-default ports, accepts only text-like content types, and blocks resolved private or loopback addresses. No host is enabled by default. Deployment still needs an egress proxy or firewall: application-layer DNS checks do not replace network isolation.
-- Host diagnostics intentionally exclude user identities, process lists, network configuration, installed software, and environment variables except for names explicitly configured by the host.
+- Host diagnostics intentionally exclude user identities, network configuration, installed software, and environment variables except for names explicitly configured by the host. Process diagnostics are separate, disabled by default, and return only configured process names, PIDs, states, and start times.
 - Command execution accepts an argument array, never a shell string. Programs must be mapped by the host application, execution has a timeout, and output is truncated.
 - The local command runner is not an OS security sandbox. Production deployment must run the service or runner inside the company-approved container/sandbox with no production secrets and restricted network access.
 - Approval remains the orchestration layer's responsibility. Only attach `tools.write` or `tools.execute` after the matching approval policy has been validated.
@@ -67,11 +67,15 @@ tools = create_tools(Path("./workspace"))
 agent = Agent(
     name="Workspace assistant",
     instructions="Use workspace tools when needed.",
-    tools=list(tools.read),
+    tools=list(tools.files.read),
 )
 ```
 
-`tools.read` is read-only. `tools.write` and `tools.execute` require approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.
+Use the narrowest domain selector: `tools.files`, `tools.network`, `tools.host`, or `tools.process`. The v0.3-style `tools.read`, `tools.write`, and `tools.execute` selectors remain available for compatibility, but combine more capabilities. Every `*.write` and `*.execute` tool requires approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.
+
+## Design specs
+
+- [v0.4 tool expansion spec](docs/v0.4-tool-expansion-spec.md)
 
 For configured commands, HTTPS hosts, or readable environment variables, use `ToolConfig`:
 
@@ -91,6 +95,25 @@ tools = create_tools(
 )
 ```
 
+Network diagnostics and process inspection are disabled until explicitly configured:
+
+```python
+from function_tools import ToolConfig, create_tools
+
+tools = create_tools(
+    ToolConfig(
+        workspace_root="./workspace",
+        http_allowed_hosts=frozenset({"api.example.internal"}),
+        search_engines={"bing": "https://www.bing.com/search"},
+        network_allowed_ports=frozenset({443}),
+        process_name_allowlist=frozenset({"python.exe"}),
+    )
+)
+
+network_tools = tools.network.read
+process_tools = tools.process.inspect
+```
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE).

{agents_function_tools-0.3.0 → agents_function_tools-0.4.0}/src/agents_function_tools.egg-info/SOURCES.txt

@@ -12,12 +12,15 @@ src/function_tools/command.py
 src/function_tools/errors.py
 src/function_tools/host.py
 src/function_tools/http.py
+src/function_tools/network.py
 src/function_tools/openai_tools.py
+src/function_tools/process.py
 src/function_tools/responses.py
 src/function_tools/workspace.py
 tests/test_archive.py
 tests/test_command.py
 tests/test_host_and_http.py
+tests/test_network_and_process.py
 tests/test_openai_tools.py
 tests/test_public_api.py
 tests/test_workspace.py

agents_function_tools-0.4.0/src/function_tools/__init__.py

@@ -0,0 +1,52 @@
+"""Portable, policy-friendly system function tools for AI applications."""
+
+from .archive import ZipArchive
+from .command import CommandPolicy, LocalCommandRunner
+from .errors import FoundationToolError
+from .host import HostInspector
+from .http import HttpPolicy, HttpTextClient
+from .network import NetworkInspector, NetworkPolicy
+from .openai_tools import (
+    FilesystemToolGroup,
+    FunctionToolBundle,
+    HostToolGroup,
+    NetworkToolGroup,
+    ProcessToolGroup,
+    ToolConfig,
+    create_filesystem_tools,
+    create_function_tools,
+    create_host_tools,
+    create_network_tools,
+    create_process_tools,
+    create_tools,
+)
+from .process import ProcessInspector
+from .workspace import Workspace
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "CommandPolicy",
+    "FoundationToolError",
+    "FilesystemToolGroup",
+    "FunctionToolBundle",
+    "HostInspector",
+    "HostToolGroup",
+    "HttpPolicy",
+    "HttpTextClient",
+    "LocalCommandRunner",
+    "NetworkInspector",
+    "NetworkPolicy",
+    "NetworkToolGroup",
+    "ProcessInspector",
+    "ProcessToolGroup",
+    "ToolConfig",
+    "Workspace",
+    "ZipArchive",
+    "create_filesystem_tools",
+    "create_function_tools",
+    "create_host_tools",
+    "create_network_tools",
+    "create_process_tools",
+    "create_tools",
+]

{agents_function_tools-0.3.0 → agents_function_tools-0.4.0}/src/function_tools/http.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-import ipaddress
-import socket
 import ssl
 from dataclasses import dataclass
 from typing import Any
@@ -10,6 +8,7 @@ from urllib.parse import urlparse
 from urllib.request import HTTPRedirectHandler, HTTPSHandler, Request, build_opener
 
 from .errors import FoundationToolError
+from .network import NetworkPolicy
 
 
 @dataclass(frozen=True)
@@ -36,6 +35,11 @@ class HttpTextClient:
 
     def __init__(self, policy: HttpPolicy) -> None:
         self.policy = policy
+        self._network_policy = NetworkPolicy(
+            allowed_hosts=policy.allowed_hosts,
+            timeout_seconds=policy.timeout_seconds,
+            allow_private_addresses=policy.allow_private_addresses,
+        )
 
     def fetch(self, url: str) -> dict[str, Any]:
         parsed = self._validate_url(url)
@@ -43,7 +47,7 @@ class HttpTextClient:
         request = Request(
             url,
             headers={
-                "User-Agent": "agents-function-tools/0.3.0",
+                "User-Agent": "agents-function-tools",
                 "Accept": "text/plain,text/html,application/json",
             },
         )
@@ -106,31 +110,8 @@ class HttpTextClient:
             raise FoundationToolError(
                 "INVALID_URL", "Only HTTPS default-port URLs without user credentials are allowed."
             )
-        if host not in self.policy.allowed_hosts:
-            allowed = ", ".join(sorted(self.policy.allowed_hosts)) or "none"
-            raise FoundationToolError(
-                "HOST_NOT_ALLOWED", f"Host is not allowed. Allowed hosts: {allowed}."
-            )
+        self._network_policy.validate_host(host)
         return parsed
 
     def _validate_addresses(self, hostname: str) -> None:
-        try:
-            addresses = {
-                item[4][0] for item in socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM)
-            }
-        except socket.gaierror as error:
-            raise FoundationToolError(
-                "DNS_LOOKUP_FAILED", "Allowed host could not be resolved.", retryable=True
-            ) from error
-        if not addresses:
-            raise FoundationToolError(
-                "DNS_LOOKUP_FAILED", "Allowed host has no resolved addresses."
-            )
-        if self.policy.allow_private_addresses:
-            return
-        for address in addresses:
-            ip = ipaddress.ip_address(address)
-            if not ip.is_global:
-                raise FoundationToolError(
-                    "PRIVATE_ADDRESS_BLOCKED", "Resolved address is not public."
-                )
+        self._network_policy.resolve_public_addresses(hostname)

agents_function_tools-0.4.0/src/function_tools/network.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any
+from urllib.parse import urlencode, urlsplit, urlunsplit
+
+from .errors import FoundationToolError
+
+
+@dataclass(frozen=True)
+class NetworkPolicy:
+    """Host-owned restrictions for outbound network diagnostics."""
+
+    allowed_hosts: frozenset[str] = frozenset()
+    allowed_ports: frozenset[int] = frozenset({443})
+    timeout_seconds: int = 15
+    search_engines: Mapping[str, str] = field(default_factory=dict)
+    allow_private_addresses: bool = False
+
+    def __post_init__(self) -> None:
+        if self.timeout_seconds <= 0:
+            raise FoundationToolError("INVALID_LIMIT", "Network timeout limit must be positive.")
+        object.__setattr__(
+            self,
+            "allowed_hosts",
+            frozenset(self._normalize_host(host) for host in self.allowed_hosts),
+        )
+        object.__setattr__(self, "allowed_ports", frozenset(self.allowed_ports))
+        for port in self.allowed_ports:
+            if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65_535:
+                raise FoundationToolError(
+                    "INVALID_PORT", "Network ports must be between 1 and 65535."
+                )
+        if not isinstance(self.search_engines, Mapping):
+            raise FoundationToolError(
+                "INVALID_SEARCH_ENGINE", "Search engines must be a name-to-URL mapping."
+            )
+        normalized_engines = {
+            self._normalize_engine_name(name): url for name, url in self.search_engines.items()
+        }
+        for name, url in normalized_engines.items():
+            self._validate_engine(name, url)
+        object.__setattr__(self, "search_engines", MappingProxyType(normalized_engines))
+
+    def validate_host(self, hostname: str) -> str:
+        normalized = self._normalize_host(hostname)
+        if normalized not in self.allowed_hosts:
+            allowed = ", ".join(sorted(self.allowed_hosts)) or "none"
+            raise FoundationToolError(
+                "HOST_NOT_ALLOWED", f"Host is not allowed. Allowed hosts: {allowed}."
+            )
+        return normalized
+
+    def resolve_public_addresses(self, hostname: str) -> tuple[str, ...]:
+        try:
+            addresses = {
+                item[4][0] for item in socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM)
+            }
+        except socket.gaierror as error:
+            raise FoundationToolError(
+                "DNS_LOOKUP_FAILED", "Allowed host could not be resolved.", retryable=True
+            ) from error
+        if not addresses:
+            raise FoundationToolError(
+                "DNS_LOOKUP_FAILED", "Allowed host has no resolved addresses."
+            )
+        for address in addresses:
+            try:
+                ip = ipaddress.ip_address(address)
+            except ValueError as error:
+                raise FoundationToolError(
+                    "DNS_LOOKUP_FAILED",
+                    "Allowed host resolved to an invalid address.",
+                    retryable=True,
+                ) from error
+            if not self.allow_private_addresses and not ip.is_global:
+                raise FoundationToolError(
+                    "PRIVATE_ADDRESS_BLOCKED", "Resolved address is not public."
+                )
+        return tuple(sorted(addresses))
+
+    @staticmethod
+    def _normalize_host(hostname: str) -> str:
+        if not isinstance(hostname, str):
+            raise FoundationToolError("INVALID_HOST", "Network hosts must be strings.")
+        normalized = hostname.strip().lower()
+        if (
+            not normalized
+            or len(normalized) > 253
+            or any(character in normalized for character in "/\\@?#:")
+            or any(character.isspace() for character in normalized)
+        ):
+            raise FoundationToolError("INVALID_HOST", "Network hosts must be bare hostnames.")
+        return normalized
+
+    @staticmethod
+    def _normalize_engine_name(name: str) -> str:
+        if not isinstance(name, str):
+            raise FoundationToolError(
+                "INVALID_SEARCH_ENGINE", "Search engine names must be strings."
+            )
+        normalized = name.strip().lower()
+        if not re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,63}", normalized):
+            raise FoundationToolError(
+                "INVALID_SEARCH_ENGINE", "Search engine names must be 1 to 64 characters."
+            )
+        return normalized
+
+    @classmethod
+    def _validate_engine(cls, name: str, url: str) -> None:
+        if not isinstance(url, str):
+            raise FoundationToolError(
+                "INVALID_SEARCH_ENGINE", "Search engine URLs must be strings."
+            )
+        parsed = urlsplit(url)
+        try:
+            port = parsed.port
+        except ValueError as error:
+            raise FoundationToolError(
+                "INVALID_SEARCH_ENGINE", "Search engine URL has an invalid port."
+            ) from error
+        if (
+            parsed.scheme != "https"
+            or not parsed.hostname
+            or port not in {None, 443}
+            or parsed.username
+            or parsed.password
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise FoundationToolError(
+                "INVALID_SEARCH_ENGINE",
+                "Search engine URLs must be HTTPS default-port endpoints without query parameters.",
+            )
+        cls._normalize_host(parsed.hostname)
+
+
+class NetworkInspector:
+    """Bounded read-only diagnostics for explicitly configured public hosts."""
+
+    def __init__(self, policy: NetworkPolicy) -> None:
+        self.policy = policy
+
+    def build_search_url(self, engine: str, query: str) -> dict[str, Any]:
+        if not isinstance(engine, str) or not engine.strip():
+            raise FoundationToolError("INVALID_SEARCH_ENGINE", "Search engine name is required.")
+        if not isinstance(query, str) or not query.strip():
+            raise FoundationToolError("INVALID_SEARCH_QUERY", "Search query is required.")
+        if len(query) > 2_048:
+            raise FoundationToolError(
+                "SEARCH_QUERY_TOO_LONG", "Search query cannot exceed 2048 characters."
+            )
+
+        name = self.policy._normalize_engine_name(engine)
+        base_url = self.policy.search_engines.get(name)
+        if base_url is None:
+            allowed = ", ".join(sorted(self.policy.search_engines)) or "none"
+            raise FoundationToolError(
+                "SEARCH_ENGINE_NOT_ALLOWED",
+                f"Search engine is not allowed. Allowed engines: {allowed}.",
+            )
+        parsed = urlsplit(base_url)
+        url = urlunsplit((parsed.scheme, parsed.netloc, parsed.path, urlencode({"q": query}), ""))
+        return {"engine": name, "query": query, "url": url}
+
+    def dns_lookup(self, hostname: str) -> dict[str, Any]:
+        host = self.policy.validate_host(hostname)
+        return {"host": host, "addresses": list(self.policy.resolve_public_addresses(host))}
+
+    def tcp_probe(self, hostname: str, port: int = 443) -> dict[str, Any]:
+        host = self.policy.validate_host(hostname)
+        if (
+            isinstance(port, bool)
+            or not isinstance(port, int)
+            or port not in self.policy.allowed_ports
+        ):
+            allowed = ", ".join(str(value) for value in sorted(self.policy.allowed_ports)) or "none"
+            raise FoundationToolError(
+                "PORT_NOT_ALLOWED", f"Port is not allowed. Allowed ports: {allowed}."
+            )
+
+        addresses = self.policy.resolve_public_addresses(host)
+        for address in addresses:
+            started = time.monotonic()
+            try:
+                with socket.create_connection((address, port), timeout=self.policy.timeout_seconds):
+                    latency_ms = round((time.monotonic() - started) * 1_000, 3)
+                    return {
+                        "host": host,
+                        "port": port,
+                        "reachable": True,
+                        "address": address,
+                        "latency_ms": latency_ms,
+                    }
+            except OSError:
+                continue
+        return {
+            "host": host,
+            "port": port,
+            "reachable": False,
+            "address": None,
+            "latency_ms": None,
+        }