hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/tools/classify.py

@@ -0,0 +1,266 @@
+"""
+Map a legacy tool's free-text result onto the S2 envelope.
+
+The 87 wave-1 tools still return strings. This module turns each string into
+a status by looking at fixed PREFIXES of the result (never at words anywhere
+in it: a file whose text contains "not found" is still a successful read).
+Tools whose outcome matters most get an explicit mapping (TOOL_RULES); every
+other tool uses `generic`.
+
+Send tools: a timeout is `uncertain` (the message may have gone out), never
+`failed`, and never retried (spec rule 5).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from .envelope import (REASON_CONFIRM, REASON_NOT_CONFIGURED, REASON_UNKNOWN_TOOL, Status,
+                       ToolResult, make, new_receipt_id)
+
+# Effects whose outcome after a timeout is unknown.
+SIDE_EFFECTS = ("write", "send", "spend", "delete", "system")
+
+_TIMEOUT = re.compile(r"\btime[d ]?\s?out\b|\btimeout\b|ReadTimeout|ConnectTimeout", re.I)
+_NOT_CONFIGURED_PHRASE = re.compile(
+    r"not configured|\bnot available$|auth unavailable|not connected"
+    r"|no recipient specified|no imessage recipient|needs google oauth|missing credentials",
+    re.I)
+_SET_VAR = re.compile(r"^Set [A-Z][A-Z0-9_]{2,}\b")  # "Set SLACK_WEBHOOK_URL environment variable"
+
+
+def _not_configured(text: str) -> bool:
+    t = text.strip()
+    first = t.splitlines()[0] if t else ""
+    return len(t) < 300 and bool(_NOT_CONFIGURED_PHRASE.search(first) or _SET_VAR.match(first))
+_NOT_FOUND_PREFIX = ("not found:", "text not found", "image not found", "file not found",
+                     "attachment not found", "no such file")
+_PERM = re.compile(r"\[errno 13\]|\[errno 1\]|permission denied|operation not permitted"
+                   r"|not authorized|not authorised|\b401\b|\b403\b", re.I)
+_ENOENT = re.compile(r"\[errno 2\]|no such file or directory", re.I)
+_FAIL_PREFIX = ("error", "tool error", "gmail error", "telegram error", "telegram send",
+                "imessage send", "email send", "forward failed", "draft failed", "failed",
+                "database error", "elevenlabs error", "open failed", "send failed",
+                "couldn't", "could not", "unable to", "traceback", "unknown action",
+                "messages database")
+
+
+def _text(raw: Any) -> str:
+    if raw is None:
+        return ""
+    if isinstance(raw, str):
+        return raw
+    try:
+        return json.dumps(raw, default=str)
+    except (TypeError, ValueError):
+        return str(raw)
+
+
+def _data(text: str) -> Any:
+    """Tool output as data: parsed JSON when the tool returned JSON."""
+    t = text.strip()
+    if t[:1] in ("{", "[") and t[-1:] in ("}", "]"):
+        try:
+            return json.loads(t)
+        except ValueError:
+            pass
+    return text
+
+
+def ok(spec, text: str, *, receipt: Optional[str] = None, message: str = "") -> ToolResult:
+    side_effect = spec.effect != "read"
+    return make(Status.OK, message or f"{spec.name} completed.", data=_data(text),
+                receipt_id=(receipt or new_receipt_id()) if side_effect else None)
+
+
+def failed(spec, text: str, *, retryable: Optional[bool] = None) -> ToolResult:
+    """A failure: `uncertain` for side-effecting tools that timed out."""
+    if _TIMEOUT.search(text):
+        if spec.effect in SIDE_EFFECTS:
+            return make(Status.UNCERTAIN, f"{spec.name} timed out; the outcome is unknown. {text}")
+        return make(Status.FAILED, text, retryable=True if retryable is None else retryable)
+    if _PERM.search(text):
+        return make(Status.PERMISSION_DENIED, text)
+    if _ENOENT.search(text):
+        return make(Status.NOT_FOUND, text)
+    return make(Status.FAILED, text, retryable=retryable)
+
+
+def generic(spec, text: str, args: dict) -> ToolResult:
+    t = text.strip()
+    low = t.lower()
+    if low.startswith("unknown tool"):
+        return make(Status.NOT_FOUND, t, reason=REASON_UNKNOWN_TOOL)
+    if low.startswith(_NOT_FOUND_PREFIX):
+        return make(Status.NOT_FOUND, t)
+    if low.startswith("permission denied"):   # e.g. a write outside the workspace
+        return make(Status.PERMISSION_DENIED, t)
+    if _not_configured(t):
+        return make(Status.PERMISSION_DENIED, t, reason=REASON_NOT_CONFIGURED)
+    if low.startswith(_FAIL_PREFIX) or (len(t) < 200 and low == "timed out"):
+        return failed(spec, t)
+    return ok(spec, text)
+
+
+# ───────────────────────── explicit per-tool mappings ─────────────────────────
+
+def _path_readable(args: dict) -> bool:
+    try:
+        p = Path(str(args.get("path", ""))).expanduser()
+        return p.is_file() and os.access(p, os.R_OK)
+    except Exception:
+        return False
+
+
+def read_file(spec, text, args):
+    if text.startswith("Not found: "):
+        return make(Status.NOT_FOUND, f"File {args.get('path', '')} does not exist.")
+    if text.startswith("Error: ") and (not _path_readable(args) or "codec can't decode" in text):
+        return failed(spec, text)
+    return ok(spec, text, message=f"Read {args.get('path', '')}.")
+
+
+def edit_file(spec, text, args):
+    path = args.get("path", "")
+    if text.startswith("Not found: "):
+        return make(Status.NOT_FOUND, f"File {path} does not exist; nothing was changed.")
+    if text.strip() == "Text not found":
+        return make(Status.NOT_FOUND, f"The text to replace was not found in {path}; the file "
+                                      f"was NOT changed.")
+    if text.strip() == "Edited":
+        return ok(spec, text, message=f"Edited {path}.")
+    return failed(spec, text)
+
+
+def write_file(spec, text, args):
+    if text.startswith("Written "):
+        return ok(spec, text, message=f"{text} to {args.get('path', '')}.")
+    return failed(spec, text)
+
+
+_RECEIPT = r"\[id:([^\]\s]+)\]"
+
+
+def _send(success_prefixes, receipt_re=None, require_receipt=None):
+    """Send-tool rule. require_receipt(text) -> True when that success needs
+    a provider id (bench 20.3): without one it is `failed`, never `ok`."""
+    def rule(spec, text, args):
+        t = text.strip()
+        low = t.lower()
+        if any(low.startswith(p.lower()) for p in success_prefixes):
+            receipt = None
+            if receipt_re:
+                m = re.search(receipt_re, t)
+                receipt = m.group(1) if m else None
+            if receipt is None and require_receipt is not None and require_receipt(t):
+                return make(Status.FAILED,
+                            f"{spec.name}: the provider returned no delivery receipt (message "
+                            f"id), so it is NOT confirmed sent. Raw result: {t[:200]}")
+            return ok(spec, t, receipt=receipt, message=t)
+        if low.startswith(("file not found", "not found:")):
+            return make(Status.NOT_FOUND, t)
+        if _not_configured(t):
+            return make(Status.PERMISSION_DENIED, t, reason=REASON_NOT_CONFIGURED)
+        return failed(spec, t)
+    return rule
+
+
+def email_mark(spec, text, args):
+    if "'error'" in text or '"error"' in text or text.startswith("Error"):
+        return failed(spec, text)
+    return ok(spec, text, message=f"Updated message {args.get('message_id', '')}.")
+
+
+def _applescript_read(spec, text, args):
+    t = text.strip()
+    if t.startswith("Error") or "execution error" in t:
+        return failed(spec, t)
+    return generic(spec, text, args)
+
+
+def calendar_read(spec, text, args):
+    """Unreachable is `failed`, never an empty `ok` (spec §7 calendar honesty)."""
+    t = text.strip()
+    if not t or t == "Done" or t.startswith("Error") or "execution error" in t:
+        return make(Status.FAILED, t or "Calendar returned nothing; it may be unreachable.")
+    return ok(spec, text)
+
+
+def calendar_create(spec, text, args):
+    t = text.strip()
+    if t == "Event created":
+        return ok(spec, t, message=f"Created event '{args.get('title', '')}'.")
+    return failed(spec, t or "Calendar did not confirm the event.")
+
+
+def email_search(spec, text, args):
+    return _applescript_read(spec, text, args)
+
+
+_HTTP_STATUS = re.compile(r"^Status: (\d{3})")
+
+
+def web_fetch(spec, text, args):
+    m = _HTTP_STATUS.match(text)
+    if not m:
+        return generic(spec, text, args)
+    code = int(m.group(1))
+    if code in (404, 410):
+        return make(Status.NOT_FOUND, f"{args.get('url', '')} returned HTTP {code}.")
+    if code in (401, 403):
+        return make(Status.PERMISSION_DENIED, f"{args.get('url', '')} returned HTTP {code}.")
+    if code >= 500 or code == 429:
+        return make(Status.FAILED, f"{args.get('url', '')} returned HTTP {code}.", retryable=True)
+    if code >= 400:
+        return make(Status.FAILED, f"{args.get('url', '')} returned HTTP {code}.")
+    return ok(spec, text)
+
+
+def memory_forget(spec, text, args):
+    """Exact forget (rc3): one deletion named back, or nothing deleted."""
+    t = text.strip()
+    if t.startswith("Deleted memory "):
+        return make(Status.OK, t, data=t)
+    if t.startswith("Ambiguous:"):
+        return make(Status.NEEDS_APPROVAL, t, reason=REASON_CONFIRM)
+    if t.startswith("Memory not found"):
+        return make(Status.NOT_FOUND, t)
+    if t.startswith("Provide memory_id"):
+        return make(Status.INVALID_ARGS, t)
+    return generic(spec, text, args)
+
+
+TOOL_RULES: dict = {
+    "read_file": read_file,
+    "edit_file": edit_file,
+    "write_file": write_file,
+    # Provider-confirmed receipts required where the provider gives an id (bench 20.3).
+    "telegram": _send(("Message sent", "Sent "), receipt_re=_RECEIPT,
+                      require_receipt=lambda t: True),
+    "imessage": _send(("iMessage sent", "Sent ")),      # AppleScript: no provider id exists
+    "slack": _send(("Message sent",)),                  # incoming webhook: body "ok", no id
+    "discord": _send(("Message sent",), receipt_re=_RECEIPT, require_receipt=lambda t: True),
+    "send_file": _send(("Queued ", "Sent ", "Emailed ", "Opened "), receipt_re=_RECEIPT,
+                       require_receipt=lambda t: "via Telegram" in t or t.startswith("Emailed ")),
+    "email_send": _send(("Sent to",), receipt_re=_RECEIPT, require_receipt=lambda t: True),
+    "email_forward": _send(("Forwarded to",)),
+    "email_draft": _send(("Draft created",)),
+    "email_mark": email_mark,
+    "email_read": _applescript_read,
+    "email_search": email_search,
+    "calendar_read": calendar_read,
+    "calendar_create": calendar_create,
+    "web_fetch": web_fetch,
+    "memory_forget": memory_forget,
+}
+
+
+def classify(spec, raw: Any, args: Optional[dict] = None) -> ToolResult:
+    if isinstance(raw, ToolResult):
+        return raw
+    text = _text(raw)
+    rule: Callable = TOOL_RULES.get(spec.name, generic)
+    return rule(spec, text, args or {})