hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/tools/args.py

@@ -0,0 +1,212 @@
+"""
+Tool arguments: one Pydantic model per tool (tool standard S1/S4).
+
+The model is the single source of truth: the JSON schema advertised to the
+model is generated FROM it (`input_schema`), and the arguments the model
+sends back are validated AGAINST it (`validate`). `extra="forbid"`, so an
+argument the tool does not take is an error the model can read and correct,
+never silently dropped.
+
+Wave 1 builds the models from the existing hand-written schemas in
+hyperclaw.tui.TOOLS (`model_from_schema`) so the 87 tools keep their
+current inputs; a tool can later define its model by hand instead.
+"""
+from __future__ import annotations
+
+import functools
+import json
+from typing import Any, Dict, List, Literal, Optional, Tuple
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, create_model
+
+_TYPES = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "boolean": bool,
+    "object": Dict[str, Any],
+}
+
+# Examples used in validation messages, by argument name, then by type.
+_NAME_EXAMPLES = {
+    "path": "~/.hyperclaw/workspace/notes/x.txt",
+    "image_path": "~/.hyperclaw/workspace/photo.png",
+    "save_path": "~/.hyperclaw/workspace/out.png",
+    "url": "https://example.com/page",
+    "query": "weather in Lisbon",
+    "to": "name@example.com",
+    "message": "On my way.",
+    "content": "text to save",
+    "command": "ls ~/Downloads",
+    "subject": "Meeting notes",
+    "body": "Hi, ...",
+    "title": "Team sync",
+    "start": "2026-10-05 10:00",
+    "end": "2026-10-05 11:00",
+    "message_id": "18c2f0a1b2c3d4e5",
+    "plan_id": "plan_1a2b3c",
+    "task_id": "task_1",
+    "domain": "example.com",
+    "location": "Lisbon",
+    "symbol": "AAPL",
+}
+_TYPE_EXAMPLES = {
+    "string": '"text"', "integer": "5", "number": "1.5", "boolean": "true",
+    "array": '["a", "b"]', "object": '{"key": "value"}',
+}
+
+
+class ToolArgs(BaseModel):
+    """Base for every tool's argument model."""
+    # coerce_numbers_to_str: a phone number sent as 5550100 is still a string arg.
+    model_config = ConfigDict(extra="forbid", coerce_numbers_to_str=True)
+
+
+def _py_type(prop: dict):
+    if "enum" in prop and prop["enum"]:
+        return Literal[tuple(prop["enum"])]
+    t = prop.get("type", "string")
+    if t == "array":
+        items = prop.get("items") or {}
+        inner = _TYPES.get(items.get("type"), Any) if items else Any
+        return List[inner]
+    return _TYPES.get(t, Any)
+
+
+def model_from_schema(tool_name: str, schema: dict) -> type:
+    """Build the argument model for a tool from its JSON schema."""
+    props = (schema or {}).get("properties", {}) or {}
+    required = set((schema or {}).get("required", []) or [])
+    fields = {}
+    for pname, prop in props.items():
+        typ = _py_type(prop)
+        desc = prop.get("description")
+        if pname in required:
+            fields[pname] = (typ, Field(..., description=desc))
+        else:
+            default = prop.get("default")
+            fields[pname] = (Optional[typ], Field(default, description=desc))
+    cls_name = "".join(p.capitalize() for p in tool_name.split("_")) + "Args"
+    return create_model(cls_name, __base__=ToolArgs, **fields)
+
+
+def _clean(node, in_properties: bool = False):
+    """Make Pydantic's JSON schema read like a hand-written tool schema:
+    no titles, Optional[X] shown as X, no null defaults. (Keys directly under
+    "properties" are argument names, so an argument called "title" stays.)"""
+    if isinstance(node, list):
+        return [_clean(x) for x in node]
+    if not isinstance(node, dict):
+        return node
+    if in_properties:
+        return {k: _clean(v) for k, v in node.items()}
+    out = {}
+    for k, v in node.items():
+        if k == "title":
+            continue
+        out[k] = _clean(v, in_properties=(k == "properties"))
+    any_of = out.get("anyOf")
+    if isinstance(any_of, list):
+        non_null = [x for x in any_of if x != {"type": "null"}]
+        if len(non_null) == 1 and len(non_null) < len(any_of):
+            del out["anyOf"]
+            merged = dict(non_null[0])
+            merged.update(out)
+            out = merged
+    if out.get("default", 0) is None:
+        del out["default"]
+    return out
+
+
+@functools.lru_cache(maxsize=None)
+def _input_schema_json(model: type) -> str:
+    schema = _clean(model.model_json_schema())
+    schema.setdefault("type", "object")
+    schema.setdefault("properties", {})
+    return json.dumps(schema)
+
+
+def input_schema(model: type) -> dict:
+    """The JSON schema advertised to the model, generated from `model`
+    (a fresh copy each call)."""
+    return json.loads(_input_schema_json(model))
+
+
+# ───────────────────────── validation ─────────────────────────
+
+class ArgsError(Exception):
+    """Arguments that cannot be used; str(self) is the model-readable message."""
+
+
+def _field_type(model: type, name: str) -> Tuple[str, Optional[list]]:
+    prop = input_schema(model).get("properties", {}).get(name, {})
+    return prop.get("type", "string"), prop.get("enum")
+
+
+def _example(name: str, typ: str, enum: Optional[list]) -> str:
+    if enum:
+        return json.dumps(enum[0])
+    if typ == "string" and name in _NAME_EXAMPLES:
+        return _NAME_EXAMPLES[name]
+    return _TYPE_EXAMPLES.get(typ, '"text"')
+
+
+def call_example(model: type) -> str:
+    """A minimal valid call shape, e.g. {"path": "..."}."""
+    schema = input_schema(model)
+    req = schema.get("required", []) or []
+    props = schema.get("properties", {})
+    parts = []
+    for name in req:
+        typ = props.get(name, {}).get("type", "string")
+        ex = _example(name, typ, props.get(name, {}).get("enum"))
+        if typ == "string" and not ex.startswith('"'):
+            ex = json.dumps(ex)
+        parts.append(f'"{name}": {ex}')
+    return "{" + ", ".join(parts) + "}"
+
+
+def _describe(model: type, err: dict) -> str:
+    loc = err.get("loc") or ()
+    name = str(loc[0]) if loc else "arguments"
+    sub = "".join(f"[{x}]" if isinstance(x, int) else f".{x}" for x in loc[1:])
+    kind = err.get("type", "")
+    valid = list(input_schema(model).get("properties", {}))
+    if kind == "extra_forbidden":
+        return (f"'{name}' is not an argument of this tool (valid arguments: "
+                f"{', '.join(valid) or 'none'})")
+    typ, enum = _field_type(model, name)
+    ex = _example(name, typ, enum)
+    if kind == "missing":
+        return f"'{name}' is required ({typ}, e.g. {ex})"
+    if enum and kind in ("literal_error", "enum"):
+        return f"'{name}' must be one of: {', '.join(map(str, enum))}"
+    got = err.get("input")
+    got_type = type(got).__name__ if got is not None else "null"
+    shown = json.dumps(got, default=str)
+    if len(shown) > 60:
+        shown = shown[:57] + "..."
+    return f"'{name}{sub}' must be {typ}, got {got_type} {shown} (e.g. {ex})"
+
+
+def validate(model: type, raw: Any) -> dict:
+    """Validate raw tool-call arguments. Returns the arguments the caller
+    actually supplied (coerced), or raises ArgsError with a message that
+    names each bad field, its expected type and an example."""
+    if isinstance(raw, (str, bytes)):
+        try:
+            raw = json.loads(raw) if raw else {}
+        except ValueError as e:
+            raise ArgsError(f"arguments are not valid JSON ({e}). Send one JSON object, "
+                            f"e.g. {call_example(model)}")
+    if raw is None:
+        raw = {}
+    if not isinstance(raw, dict):
+        raise ArgsError(f"arguments must be a JSON object, got {type(raw).__name__}. "
+                        f"e.g. {call_example(model)}")
+    try:
+        inst = model.model_validate(raw)
+    except ValidationError as e:
+        problems = [_describe(model, err) for err in e.errors()[:5]]
+        raise ArgsError("; ".join(problems))
+    return inst.model_dump(exclude_unset=True, exclude_none=True)

hyperclaw/tools/catalog.py

@@ -0,0 +1,244 @@
+"""
+Registry entries for the 87 wave-1 tools.
+
+Generated from the existing hand-written schemas (hyperclaw.tui.TOOLS) so no
+tool's inputs or logic change; effect / scope / tier are set by hand below
+(TOOL-INVENTORY-2026-10-02 §3a). A tool missing from EFFECT fails closed:
+effect "system", tier "ask", owner scope.
+
+Wave-1 status of the fields:
+- effect, scope, tier: declared for every tool. `never_from_chat` and guest
+  scope are ENFORCED (surfaces). `ask` is ENFORCED from wave 3: the call is
+  queued for the owner's Send / Edit / Cancel (tools/approval.py) and runs
+  only after Send, with exactly the approved payload. Every tool whose
+  effect is not "read" is `ask`, `never_from_chat` (gated on the terminal
+  too) or `never` (refused everywhere).
+- retry_budget, idempotent_on, target_on: ENFORCED from wave 2 by
+  tools/guard.py (effect ledger + per-tool / per-resource budgets).
+"""
+from __future__ import annotations
+
+from typing import Callable, Iterable
+
+from hyperclaw.chat_scope import GUEST_SAFE_TOOLS
+from hyperclaw.google_workspace import tools as _gws
+
+from .args import model_from_schema
+from .registry import PUBLIC, ToolRegistry, ToolSpec
+from .surfaces import NEVER_FROM_CHAT
+
+# ───────────────────────── effect (side-effect class) ─────────────────────────
+_READ = {
+    "read_file", "web_fetch", "web_search", "screenshot", "clipboard_read", "imessage_read",
+    "email_read", "email_search", "calendar_read", "wikipedia", "weather", "news",
+    "stock_price", "translate", "youtube", "reddit", "hackernews", "arxiv", "math",
+    "time_info", "dns_lookup", "whois", "hash", "uuid_generate", "base64_encode",
+    "json_format", "regex_test", "pdf_read", "document_read", "geocode", "currency", "unit_convert",
+    "wayback", "memory_search", "memory_list", "memory_stats", "agent_status",
+    "swarm_roster", "plan_status", "plan_next", "plan_list", "transcripts_list",
+    "learning_stats", "learning_advice",
+    # Team of agents (HC-038): the lead hands work to specialists (their own
+    # sends/writes are gated in their runs), and the Repos specialist's
+    # read-only GitLab review queue.
+    "team_delegate", "gitlab_review_queue",
+}
+_WRITE = {
+    "write_file", "edit_file", "download", "clipboard_write", "memory_store", "qr_code",
+    "calendar_create", "email_draft", "email_mark", "github", "sql_query", "plan_create",
+    "plan_update", "learning_log", "learning_feedback", "agent_watch", "transcribe_audio",
+    "transcribe_video", "document_create",
+    # Not read-only: it saves each reflection as a new row (agents/learning.py
+    # reflect() INSERTs into reflections). Found by the catalog-wide test.
+    "learning_reflect",
+}
+_SEND = {"telegram", "imessage", "send_file", "email_send", "email_forward", "slack",
+         "discord", "http_request",
+         # Not read-only: it uploads the image file's bytes to a model provider's
+         # API (tui.vision), which may be a different provider than the chat's.
+         "vision"}
+# Google Workspace (hyperclaw/google_workspace/tools.py): reads auto, the rest ask.
+_READ |= set(_gws.READ)
+_WRITE |= set(_gws.WRITE)
+_SEND |= set(_gws.SEND)
+_SPEND = {"image_generate"}
+_DELETE = {"memory_forget"}
+_SYSTEM = {"bash", "python_exec", "applescript", "type_text", "key_press", "mouse_click",
+           "open_app", "open_file", "open_url", "record_audio", "notification", "speak",
+           "agent_start", "agent_stop"}
+
+EFFECT = {}
+for _effect, _names in (("read", _READ), ("write", _WRITE), ("send", _SEND),
+                        ("spend", _SPEND), ("delete", _DELETE), ("system", _SYSTEM)):
+    for _n in _names:
+        assert _n not in EFFECT, _n
+        EFFECT[_n] = _effect
+
+# ───────────────────────── tier (cross-cutting rule 4) ─────────────────────────
+# Vaughn's rule: "every send, post or write shows the exact content and waits
+# for Send / Edit / Cancel"; "a tool marked read-only must never send data".
+#
+# ask: EVERY tool that is not read-only: sends, posts, writes (files, memory,
+# clipboard, calendar, email, plans: bench 15.6 "task changes are proposed,
+# not applied"), deletes, spend, and local actions (notifications, speech,
+# background-agent control). The card shows the exact payload.
+# never_from_chat: shell / code execution and desktop or app control
+# (surfaces.NEVER_FROM_CHAT). Removed from every chat surface; on the local
+# terminal they are gated too (tools/approval.py): the card shows the exact
+# command line / script / keystrokes / click / app / file / address.
+# never: refused on every surface, because what it would do cannot be shown
+# up front (NEVER_REASON). Not offered to any model.
+NEVER_REASON: dict = {
+    # agent_start was here until rc5. Watchers now only ever message their
+    # owner, in one fixed one-line format, never open links and never act
+    # (hyperclaw/team/watchers.py), so what they would send CAN be shown up
+    # front: agent_start is an `ask` tool whose card says exactly that.
+}
+NEVER = frozenset(NEVER_REASON)
+ASK = frozenset(n for n, e in EFFECT.items()
+                if e != "read" and n not in NEVER_FROM_CHAT and n not in NEVER)
+
+# ───────────────────────── scope (whose data/device it touches) ─────────────────────────
+SCOPE = {}
+for _n in GUEST_SAFE_TOOLS:
+    SCOPE[_n] = PUBLIC
+for _n in ("read_file", "write_file", "edit_file", "download", "pdf_read", "vision", "qr_code",
+           "document_read", "document_create",
+           "image_generate", "transcribe_audio", "transcribe_video", "transcripts_list",
+           "sql_query"):
+    SCOPE[_n] = "owner.files"
+for _n in ("memory_store", "memory_search", "memory_forget", "memory_list", "memory_stats",
+           "learning_log", "learning_stats", "learning_reflect", "learning_advice",
+           "learning_feedback", "plan_create", "plan_status", "plan_next", "plan_update",
+           "plan_list"):
+    SCOPE[_n] = "owner.memory"
+for _n in ("email_read", "email_send", "email_search", "email_forward", "email_draft",
+           "email_mark"):
+    SCOPE[_n] = "owner.email"
+for _n in ("calendar_read", "calendar_create"):
+    SCOPE[_n] = "owner.calendar"
+for _n in ("telegram", "imessage", "imessage_read", "send_file", "slack", "discord"):
+    SCOPE[_n] = "owner.messages"
+for _n in ("web_fetch", "http_request"):
+    SCOPE[_n] = "owner.network"  # can reach the owner's local network
+SCOPE["github"] = "owner.accounts"
+SCOPE["gitlab_review_queue"] = "owner.accounts"
+SCOPE["team_delegate"] = "owner.team"
+SCOPE.update(_gws.SCOPE)
+# Everything else (desktop, clipboard, audio, agents) defaults to owner.device.
+
+# ───────────────────────── retry budget / idempotency (enforced; wave 2) ─────────────────────────
+_NETWORK_READ = {"web_fetch", "web_search", "email_read", "email_search", "calendar_read",
+                 "wikipedia", "weather", "news", "stock_price", "translate", "youtube",
+                 "reddit", "hackernews", "arxiv", "dns_lookup", "whois", "geocode",
+                 "currency", "wayback", "gitlab_review_queue"} | set(_gws.READ)
+
+IDEMPOTENT_ON = {
+    "write_file": ("path", "content"),
+    "edit_file": ("path", "old_text", "new_text"),
+    "download": ("url", "path"),
+    "clipboard_write": ("text",),
+    "memory_store": ("content", "domain"),
+    "memory_forget": ("memory_id", "query"),
+    "qr_code": ("data", "save_path"),
+    "image_generate": ("prompt", "size", "save_path"),
+    "telegram": ("message", "file"),
+    "imessage": ("recipient", "message", "file"),
+    "send_file": ("path", "via", "to"),
+    "email_send": ("to", "cc", "bcc", "subject", "body", "attachments"),
+    "email_forward": ("message_id", "to"),
+    "email_draft": ("to", "subject", "body"),
+    "email_mark": ("message_id", "mark_read", "archive", "star"),
+    "calendar_create": ("title", "start", "end"),
+    "slack": ("channel", "message"),
+    "discord": ("message",),
+    "http_request": ("method", "url", "body", "json_body"),
+    "github": ("action", "owner", "repo", "title"),
+    "sql_query": ("database", "query"),
+    "plan_create": ("goal",),
+    "document_create": ("format", "title", "notes", "path"),
+    **_gws.IDEMPOTENT_ON,
+}
+
+# The idempotent_on fields that are the effect's TARGET; the remaining fields
+# are its payload. Same target + different payload inside the conflict window
+# is held (needs_approval) for send/spend/delete. A single path field makes
+# the target "file:<resolved path>", shared with bash redirects.
+TARGET_ON = {
+    "write_file": ("path",),
+    "edit_file": ("path",),
+    "download": ("path",),
+    "qr_code": ("save_path",),
+    "image_generate": ("prompt",),
+    "clipboard_write": (),
+    "memory_store": ("domain",),
+    "memory_forget": ("memory_id", "query"),
+    "telegram": (),                       # the owner's own chat
+    "imessage": ("recipient",),
+    "send_file": ("via", "to"),
+    "email_send": ("to", "cc", "bcc"),
+    "email_forward": ("message_id", "to"),
+    "email_draft": ("to", "subject"),
+    "email_mark": ("message_id",),
+    "calendar_create": ("title", "start"),
+    "slack": ("channel",),
+    "discord": (),
+    "http_request": ("method", "url"),
+    "github": ("action", "owner", "repo"),
+    "sql_query": ("database",),
+    "plan_create": (),
+    "document_create": ("path",),
+    **_gws.TARGET_ON,
+}
+for _n, _t in TARGET_ON.items():
+    assert set(_t) <= set(IDEMPOTENT_ON[_n]), _n
+
+# ───────────────────────── descriptions (S1: name the one tool per effect) ─────────────────────────
+DESCRIPTION_OVERRIDES = {
+    "bash": ("Execute a bash command (local terminal only). Never use bash to read, write or "
+             "edit files: use read_file, write_file or edit_file."),
+    "read_file": ("Read contents of a file. To read a file use read_file. If the result is "
+                  "not_found, do not search for the file with other tools; ask the user where "
+                  "it is."),
+    "write_file": ("Write content to a file (creates or overwrites it). To save a file use "
+                   "write_file, once. Never use bash to write files."),
+    "edit_file": ("Edit a file by replacing old text with new text. To change part of a file "
+                  "use edit_file; never use bash for edits."),
+}
+
+
+def _retry_budget(name: str, effect: str) -> int:
+    if effect != "read" or name == "team_delegate":
+        return 0
+    return 1 if name in _NETWORK_READ else 2
+
+
+def build_specs(tools: Iterable[dict], handler: Callable[[str, dict], object]) -> list:
+    specs = []
+    for t in tools:
+        name = t["name"]
+        effect = EFFECT.get(name, "system")
+        if name in NEVER:
+            tier = "never"
+        elif name in NEVER_FROM_CHAT:
+            tier = "never_from_chat"
+        elif name in ASK or name not in EFFECT:
+            tier = "ask"
+        else:
+            tier = "auto"
+        specs.append(ToolSpec(
+            name=name,
+            description=DESCRIPTION_OVERRIDES.get(name, t.get("description", "")),
+            args_model=model_from_schema(name, t.get("input_schema", {})),
+            effect=effect,
+            scope=SCOPE.get(name, "owner.device"),
+            tier=tier,
+            retry_budget=_retry_budget(name, effect),
+            idempotent_on=IDEMPOTENT_ON.get(name, ()),
+            target_on=TARGET_ON.get(name, ()),
+            handler=handler,
+        ))
+    return specs
+
+
+def build_registry(tools: Iterable[dict], handler: Callable[[str, dict], object]) -> ToolRegistry:
+    return ToolRegistry(build_specs(tools, handler))