hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/tools/egress.py

@@ -0,0 +1,210 @@
+"""
+Read-only egress rules (Vaughn's gate C-364: "a tool marked read-only must
+never send data").
+
+GET/HEAD alone is not enough: data can leave in a query string or through a
+link preview. So:
+
+- A read-only fetch may only target a URL that appears VERBATIM in what the
+  user wrote or in content the user gave it (a pasted message or an attached
+  document, which arrive inside the user's own message). Any other URL — one
+  the model built, or one it found inside an email, web page or file it read
+  — goes to the approval queue.
+- An auto-tier fetch never reaches a loopback, private, link-local or other
+  non-public address without the owner's approval.
+- Every Telegram message goes out with link previews off and every Slack post
+  with unfurls off (the payload fragments below; see tests/unit/
+  test_approval_egress.py for the repo-wide check).
+"""
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+from typing import Iterable, List, Optional, Set
+from urllib.parse import urlsplit, urlunsplit
+
+# ───────────────────────── messaging payload fragments ─────────────────────────
+# Telegram Bot API 7.0+: link_preview_options replaces disable_web_page_preview.
+TELEGRAM_NO_PREVIEW = {"link_preview_options": {"is_disabled": True}}
+# Slack chat.postMessage and incoming webhooks.
+SLACK_NO_UNFURL = {"unfurl_links": False, "unfurl_media": False}
+
+
+def telegram_payload(payload: dict) -> dict:
+    """`payload` with link previews off (a new dict)."""
+    out = dict(payload)
+    out.update(TELEGRAM_NO_PREVIEW)
+    return out
+
+
+def slack_payload(payload: dict) -> dict:
+    """`payload` with link and media unfurls off (a new dict)."""
+    out = dict(payload)
+    out.update(SLACK_NO_UNFURL)
+    return out
+
+
+# ───────────────────────── methods ─────────────────────────
+READ_METHODS = frozenset({"GET", "HEAD"})
+
+# Arguments of read-effect tools that name a URL the tool will fetch or hand
+# to a service. Their values are checked against provenance.
+URL_ARGS = frozenset({"url", "urls", "link", "href", "image_url", "src", "source_url"})
+
+# ───────────────────────── URL provenance ─────────────────────────
+_URL_RE = re.compile(r"""https?://[^\s<>"'`\])}]+""", re.IGNORECASE)
+_BARE_RE = re.compile(r"""(?<![@\w.-])(?:[a-z0-9-]+\.)+[a-z]{2,}(?::\d+)?(?:/[^\s<>"'`\])}]*)?""",
+                      re.IGNORECASE)
+_TRAIL = ".,;:!?"
+
+
+def _strip_trailing(u: str) -> str:
+    while u and u[-1] in _TRAIL:
+        u = u[:-1]
+    return u
+
+
+def normalize_url(url: str) -> Optional[str]:
+    """Canonical form for comparison: lower-case scheme and host, default port
+    dropped, empty path -> '/', fragment dropped (it is never sent). The query
+    string is kept exactly: a different query is a different URL."""
+    try:
+        parts = urlsplit(str(url).strip())
+    except ValueError:
+        return None
+    scheme = (parts.scheme or "").lower()
+    if scheme not in ("http", "https") or not parts.hostname:
+        return None
+    host = parts.hostname.lower()
+    if ":" in host:  # IPv6 literal
+        host = f"[{host}]"
+    try:
+        port = parts.port
+    except ValueError:
+        return None
+    if port and not ((scheme == "http" and port == 80) or (scheme == "https" and port == 443)):
+        host = f"{host}:{port}"
+    if parts.username or parts.password:
+        host = f"{parts.username or ''}{':' + parts.password if parts.password else ''}@{host}"
+    return urlunsplit((scheme, host, parts.path or "/", parts.query, ""))
+
+
+def _schemeless(norm: str) -> str:
+    return norm.split("://", 1)[1]
+
+
+def provenance_urls(texts: Iterable[str]) -> Set[str]:
+    """Every URL in the user's own words / user-given content, normalised.
+    A bare 'example.com/page' the user typed matches both http and https."""
+    found: Set[str] = set()
+    for t in texts or ():
+        if not isinstance(t, str) or not t:
+            continue
+        for m in _URL_RE.findall(t):
+            n = normalize_url(_strip_trailing(m))
+            if n:
+                found.add(n)
+        for m in _BARE_RE.findall(t):
+            m = _strip_trailing(m)
+            for scheme in ("https://", "http://"):
+                n = normalize_url(scheme + m)
+                if n:
+                    found.add(n)
+    return found
+
+
+def url_in_provenance(url: str, texts: Iterable[str]) -> bool:
+    """True when `url` (normalised) appears verbatim in `texts`."""
+    n = normalize_url(url)
+    if not n:
+        return False
+    return n in provenance_urls(texts)
+
+
+# ───────────────────────── private / non-public targets ─────────────────────────
+_PRIVATE_SUFFIXES = (".localhost", ".local", ".internal", ".lan", ".home.arpa", ".intranet")
+
+
+def _ip_not_public(ip: ipaddress._BaseAddress) -> bool:
+    if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped:
+        ip = ip.ipv4_mapped
+    return bool(ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved
+                or ip.is_multicast or ip.is_unspecified or not ip.is_global)
+
+
+def resolve_ips(host: str) -> List[str]:
+    """The host's addresses (tests replace this; a lookup failure is [])."""
+    try:
+        return sorted({ai[4][0] for ai in socket.getaddrinfo(host, None)})
+    except (OSError, UnicodeError):
+        return []
+
+
+def is_private_target(url: str, resolve: bool = True) -> bool:
+    """True when `url` points at loopback, a private or link-local range (the
+    cloud metadata address 169.254.169.254 included), or another non-public
+    address. Unparseable URLs count as private (fail closed)."""
+    try:
+        host = urlsplit(str(url).strip()).hostname
+    except ValueError:
+        return True
+    if not host:
+        return True
+    host = host.lower().rstrip(".")
+    if host == "localhost" or host.endswith(_PRIVATE_SUFFIXES) or "." not in host and ":" not in host:
+        # localhost, *.local, and single-label names (resolved on the LAN)
+        try:
+            return _ip_not_public(ipaddress.ip_address(host))
+        except ValueError:
+            return True
+    try:
+        return _ip_not_public(ipaddress.ip_address(host))
+    except ValueError:
+        pass
+    # Integer / hex / octal IPv4 spellings ("2130706433", "0x7f.1") are not
+    # hostnames a public site uses: treat them as private.
+    if re.fullmatch(r"[0-9x.]+", host):
+        return True
+    if not resolve:
+        return False
+    for ip in resolve_ips(host):
+        try:
+            if _ip_not_public(ipaddress.ip_address(ip.split("%", 1)[0])):
+                return True
+        except ValueError:
+            return True
+    return False
+
+
+# ───────────────────────── display ─────────────────────────
+_SECRET_HEADER = re.compile(r"(?i)(authorization|cookie|token|secret|api[-_]?key|password|"
+                            r"passwd|session|signature|credential|private)")
+
+
+def mask_headers(headers) -> dict:
+    """Headers for display: secret-looking values are masked (the approved
+    payload itself keeps the real values; its hash binds them)."""
+    if not isinstance(headers, dict):
+        return {}
+    out = {}
+    for k, v in headers.items():
+        if _SECRET_HEADER.search(str(k)):
+            s = str(v)
+            out[str(k)] = f"•••• (masked, {len(s)} chars)"
+        else:
+            out[str(k)] = v
+    return out
+
+
+def urls_in_args(args: dict) -> List[str]:
+    """The URL values among a tool call's URL arguments."""
+    out: List[str] = []
+    for k, v in (args or {}).items():
+        if k not in URL_ARGS:
+            continue
+        vals = v if isinstance(v, (list, tuple)) else [v]
+        for x in vals:
+            if isinstance(x, str) and x.strip():
+                out.append(x.strip())
+    return out

hyperclaw/tools/envelope.py

@@ -0,0 +1,188 @@
+"""
+The structured result envelope (tool standard S2).
+
+Every tool result the model sees is exactly this object, serialised as
+compact JSON in the tool-result content:
+
+    {"status": "not_found", "retryable": false,
+     "message": "File ~/notes/invoice-9912.txt does not exist.",
+     "instruction": "Does not exist. Do not retry or search for it. ...",
+     "data": null, "receipt_id": null}
+
+`instruction` comes from a fixed table keyed by status (and, for a few
+statuses, a fixed reason), so the model is always told what to do next and
+never has to infer it from free text.
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Status(str, Enum):
+    OK = "ok"
+    NOT_FOUND = "not_found"
+    PERMISSION_DENIED = "permission_denied"
+    FAILED = "failed"
+    INVALID_ARGS = "invalid_args"
+    NEEDS_APPROVAL = "needs_approval"      # ledger hold (wave 2); approval queue (wave 3)
+    DUPLICATE = "duplicate"                # effect ledger (wave 2)
+    UNCERTAIN = "uncertain"
+    BUDGET_EXHAUSTED = "budget_exhausted"
+
+
+# Reasons that select a more specific fixed instruction for a status.
+REASON_NOT_CONFIGURED = "not_configured"
+REASON_SURFACE = "surface"
+REASON_UNKNOWN_TOOL = "unknown_tool"
+REASON_RETRYABLE = "retryable"
+# Wave 2 (effect ledger, retry budgets).
+REASON_CONFIRM = "confirm"                    # needs_approval: held by the ledger
+REASON_RESOURCE_MISSING = "resource_missing"  # budget_exhausted: resource was not_found
+REASON_RETRY_BUDGET = "retry_budget"          # budget_exhausted: retries used up
+REASON_TURN_CAP = "turn_cap"                  # budget_exhausted: tool-call cap for the turn
+
+INSTRUCTIONS = {
+    (Status.OK, None): "",
+    (Status.NOT_FOUND, None):
+        "Does not exist. Do not retry or search for it. Tell the user it was not found "
+        "and ask where it is.",
+    (Status.NOT_FOUND, REASON_UNKNOWN_TOOL):
+        "This tool does not exist. Do not call it again. Tell the user you cannot do this here.",
+    (Status.PERMISSION_DENIED, None):
+        "Access was denied. Do not retry or work around it with another tool. Tell the user "
+        "you could not do it and why.",
+    (Status.PERMISSION_DENIED, REASON_NOT_CONFIGURED):
+        "This is not set up on this installation. Do not retry. Tell the user it is not set "
+        "up and what needs to be connected.",
+    (Status.PERMISSION_DENIED, REASON_SURFACE):
+        "This tool is not available in this conversation and was NOT run. Do not retry or "
+        "use another tool to do the same thing. Tell the user you cannot do this here.",
+    (Status.FAILED, None):
+        "It failed and nothing was done. Do not retry. Tell the user it failed and give the "
+        "reason from message.",
+    (Status.FAILED, REASON_RETRYABLE):
+        "It failed with a temporary error. You may retry once; if it fails again, tell the "
+        "user it failed and why.",
+    (Status.INVALID_ARGS, None):
+        "The arguments were invalid and nothing ran. Fix the arguments named in message and "
+        "call the tool once more. If you do not have the information, ask the user.",
+    (Status.NEEDS_APPROVAL, None):
+        "Not done yet: it is waiting for the user's approval. Tell the user exactly what is "
+        "queued. Never say it was done.",
+    (Status.NEEDS_APPROVAL, REASON_CONFIRM):
+        "It was NOT done and nothing is queued. Tell the user what you were about to do and "
+        "why it was held (see message), and ask them. Do not call it again in this reply.",
+    (Status.DUPLICATE, None):
+        "This was already done earlier and was not repeated. Tell the user it was already "
+        "done. Do not call it again.",
+    (Status.UNCERTAIN, None):
+        "It may or may not have happened. Do not retry. Tell the user the outcome is "
+        "uncertain and offer to check.",
+    (Status.BUDGET_EXHAUSTED, None):
+        "The runtime refused another attempt; it was NOT run. Do not call it again. Tell the "
+        "user what you tried and what did not work.",
+    (Status.BUDGET_EXHAUSTED, REASON_RESOURCE_MISSING):
+        "Stop. Tell the user what you tried and that it was not found.",
+    (Status.BUDGET_EXHAUSTED, REASON_RETRY_BUDGET):
+        "It already failed and its retry budget is used up; it was NOT run. Do not call it "
+        "again. Tell the user what failed and why.",
+    (Status.BUDGET_EXHAUSTED, REASON_TURN_CAP):
+        "The tool-call limit for this message was reached; it was NOT run. Stop calling "
+        "tools. Tell the user what you did and what did not run.",
+}
+
+# Default retryable flag per status. FAILED is per tool (see make()).
+RETRYABLE = {
+    Status.OK: False,
+    Status.NOT_FOUND: False,
+    Status.PERMISSION_DENIED: False,
+    Status.FAILED: False,
+    Status.INVALID_ARGS: True,   # once, with corrected arguments
+    Status.NEEDS_APPROVAL: False,
+    Status.DUPLICATE: False,
+    Status.UNCERTAIN: False,
+    Status.BUDGET_EXHAUSTED: False,
+}
+
+ENVELOPE_KEYS = ("status", "retryable", "message", "instruction", "data", "receipt_id")
+
+
+class ToolResult(BaseModel):
+    """The only thing a tool returns to the model."""
+    model_config = ConfigDict(extra="forbid", use_enum_values=True)
+
+    status: Status
+    retryable: bool
+    message: str
+    instruction: str
+    data: Any = None
+    receipt_id: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.status == Status.OK.value
+
+    def to_dict(self) -> dict:
+        return {k: getattr(self, k) for k in ENVELOPE_KEYS}
+
+    def to_content(self, limit: int = 10000) -> str:
+        """Compact JSON for the tool-result content, at most ~`limit` chars.
+        Over-long `data` is clipped (the JSON stays valid)."""
+        d = self.to_dict()
+        s = _dumps(d)
+        if len(s) <= limit:
+            return s
+        data = d["data"]
+        text = data if isinstance(data, str) else _dumps(data)
+        room = max(0, limit - (len(s) - len(_dumps(text))) - 60)
+        d["data"] = text[:room] + f"... [clipped: {len(text) - room} more characters]"
+        s = _dumps(d)
+        if len(s) > limit:  # a huge message: clip it too
+            d["message"] = d["message"][:500]
+            d["data"] = (d["data"] or "")[: max(0, limit - 1000)]
+            s = _dumps(d)
+        return s
+
+
+def _dumps(obj) -> str:
+    return json.dumps(obj, ensure_ascii=False, separators=(",", ":"), default=str)
+
+
+def new_receipt_id() -> str:
+    return f"rcpt_{uuid.uuid4().hex[:16]}"
+
+
+def make(status: Status, message: str = "", *, data: Any = None,
+         receipt_id: Optional[str] = None, reason: Optional[str] = None,
+         retryable: Optional[bool] = None) -> ToolResult:
+    status = Status(status)
+    if reason == REASON_RETRYABLE and status == Status.FAILED and retryable is None:
+        retryable = True
+    instruction = INSTRUCTIONS.get((status, reason)) or INSTRUCTIONS[(status, None)]
+    if retryable is None:
+        retryable = RETRYABLE[status]
+    if status == Status.FAILED and retryable:
+        instruction = INSTRUCTIONS[(Status.FAILED, REASON_RETRYABLE)]
+    return ToolResult(status=status, retryable=bool(retryable), message=message or "",
+                      instruction=instruction, data=data, receipt_id=receipt_id)
+
+
+def parse_content(content) -> Optional[dict]:
+    """The envelope dict if `content` is a serialised envelope, else None."""
+    if isinstance(content, list):  # Anthropic content blocks
+        content = "".join(b.get("text", "") if isinstance(b, dict) else str(b) for b in content)
+    if not isinstance(content, str) or not content.startswith("{"):
+        return None
+    try:
+        d = json.loads(content)
+    except (ValueError, TypeError):
+        return None
+    if isinstance(d, dict) and set(ENVELOPE_KEYS) <= set(d) and d.get("status") in {
+            s.value for s in Status}:
+        return d
+    return None