hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/live_state.py

@@ -0,0 +1,188 @@
+"""What is actually live on this install, for onboarding and help text.
+
+The truth rule: the product never claims anything that isn't live on that
+install. Onboarding's welcome and integrations text is generated from this
+snapshot, never from a fixed list of things the product might connect to
+(tests/unit/test_onboarding_live_state.py enforces it).
+
+Sources (no network):
+- models: live providers in the registry (keys present, on the allowed list
+  for a Hyper-deployed install), with tools vs chat-only from signed
+  qualification records only;
+- integrations: Telegram (bot token and chat id set), Gmail and Calendar
+  (Google credentials present: hyperclaw.api_utils.gmail_configured);
+- available to connect: Telegram, only when the install profile allows it
+  (managed config ``"telegram": true``: team and client installs) and it is
+  not connected yet;
+- memory: the customer's database when DATABASE_URL is set, else local files.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class LiveModel:
+    label: str
+    model: str
+    tools: bool
+
+
+@dataclass
+class LiveState:
+    hyper_deployed: bool = False
+    models: list = field(default_factory=list)          # LiveModel
+    integrations: list = field(default_factory=list)    # names, e.g. "Telegram"
+    available: list = field(default_factory=list)       # can be connected here (profile)
+    memory: str = "local"                               # local | database
+    allowed: list = field(default_factory=list)         # allowed-list names (Hyper-deployed)
+
+    @property
+    def tools(self) -> bool:
+        return any(m.tools for m in self.models)
+
+
+def _models() -> list:
+    from hyperclaw.managed_config import is_allowed
+    from hyperclaw.model_policy import model_label
+    from hyperclaw.providers import registry
+    out = []
+    try:
+        reg = registry()
+    except Exception:  # noqa: BLE001 -- no config yet: nothing is live
+        return out
+    for prov in reg.providers.values():
+        if not prov.live or "chat" not in prov.capabilities:
+            continue
+        model = prov.model_for()
+        if not model or not is_allowed(prov.name, model):
+            continue
+        out.append(LiveModel(model_label(prov, model), model,
+                             "tool_use" in prov.effective_capabilities(model)))
+    out.sort(key=lambda m: 0 if m.label.startswith("HyperSpeed") else 1)
+    return out
+
+
+def _integrations() -> list:
+    env = os.environ
+    out = []
+    if env.get("TELEGRAM_BOT_TOKEN", "").strip() and env.get("TELEGRAM_CHAT_ID", "").strip():
+        out.append("Telegram")
+    try:
+        from hyperclaw.api_utils import gmail_configured
+        from hyperclaw.userconfig import root
+        r = root()
+        gmail = gmail_configured() or (r / "workspace" / "secrets" / "gmail_token.json").exists() \
+            or (r / "secrets" / "gmail_token.json").exists()
+    except Exception:  # noqa: BLE001
+        gmail = False
+    workspace_reads = []
+    try:  # the Google Workspace sign-in (hyperclaw/google_workspace/auth.py)
+        from hyperclaw.google_workspace import auth as gauth
+        if gauth.connected():
+            granted = set(gauth.granted_scopes())
+            gmail = gmail or (gauth.GMAIL_READ in granted and gauth.CALENDAR_READ in granted)
+            workspace_reads = [label for scope, label in (
+                (gauth.DRIVE_READ, "Drive"), (gauth.DOCS_READ, "Docs"),
+                (gauth.SHEETS_READ, "Sheets"), (gauth.SLIDES_READ, "Slides"),
+                (gauth.MEET_READ, "Meet")) if scope in granted]
+    except Exception:  # noqa: BLE001
+        workspace_reads = []
+    if gmail:
+        out.append("Gmail and Calendar")
+    if workspace_reads:
+        out.append("Google " + ", ".join(workspace_reads[:-1])
+                   + (" and " if len(workspace_reads) > 1 else "") + workspace_reads[-1]
+                   + " (read)")
+    return out
+
+
+def _available(connected: list) -> list:
+    """Integrations this install's profile lets the owner connect now."""
+    try:
+        from hyperclaw.managed_config import telegram_allowed
+        tg = telegram_allowed()
+    except Exception:  # noqa: BLE001 -- unreadable profile: offer nothing
+        tg = False
+    return ["Telegram"] if tg and "Telegram" not in connected else []
+
+
+def snapshot() -> LiveState:
+    from hyperclaw.deployment import is_hyper
+    from hyperclaw.model_policy import allowed_display
+    hyper = is_hyper()
+    connected = _integrations()
+    return LiveState(
+        hyper_deployed=hyper,
+        models=_models(),
+        integrations=connected,
+        available=_available(connected),
+        memory="database" if os.environ.get("DATABASE_URL", "").strip() and not hyper
+        else "local",
+        allowed=allowed_display() if hyper else [],
+    )
+
+
+# ───────────────────────── text ─────────────────────────
+
+PRODUCT = "HyperAgents"
+TOOLS_OFF = ("Tools are off: until a model passes {p}' tool qualification it can only "
+             "chat. It can't read or send email, open your files or act in other apps.")
+
+
+def welcome_lines(state: LiveState) -> list:
+    """The welcome, generated from what is live. Plain text (no markup)."""
+    lines = [f"Welcome to {PRODUCT}.", ""]
+    lines.append(f"{PRODUCT} is an AI assistant you talk to here in the terminal.")
+    lines.append("")
+    lines.append("On this install right now:")
+    if state.models:
+        for m in state.models:
+            mode = "tools" if m.tools else "chat-only"
+            lines.append(f"  • Model: {m.label} ({m.model}), {mode}")
+    else:
+        lines.append("  • Model: none set up yet (setup adds one next)")
+    if not state.tools:
+        lines.append("  • " + TOOLS_OFF.format(p=PRODUCT))
+    if state.integrations:
+        lines.append("  • Connected: " + ", ".join(state.integrations))
+    else:
+        lines.append("  • Connected: nothing yet")
+    lines.append("  • Memory: " + ("your database" if state.memory == "database"
+                                   else "kept on this computer"))
+    return lines
+
+
+def steps(state: LiveState) -> list:
+    """The setup steps this install will actually go through."""
+    if state.hyper_deployed:
+        return ["Name your assistant", "Your name", "Your Hyper access key"]
+    return ["Name your assistant", "Your name",
+            "The model: HyperSpeed V2 (recommended) or your own provider",
+            "Optional: a database for memory across sessions"]
+
+
+def explain_lines(state: LiveState) -> list:
+    """What the assistant can do on this install, said plainly."""
+    if state.tools:
+        names = ", ".join(state.integrations) if state.integrations else "nothing yet"
+        return ["I can chat with you and use the tools this install has enabled.",
+                f"Connected services: {names}."]
+    return ["For now I can chat: answer questions, and draft, rewrite or summarize "
+            "what you paste in.",
+            "I can't act in your email, files or other apps until a model that has passed "
+            f"{PRODUCT}' tool qualification is set up."]
+
+
+def integrations_lines(state: LiveState) -> list:
+    if not state.integrations:
+        lines = ["No integrations are connected on this install yet."]
+    else:
+        lines = ["Connected on this install: " + ", ".join(state.integrations) + "."]
+    if state.available:
+        lines.append("Available to connect on this install: " + ", ".join(state.available) + ".")
+    if not state.tools and "Gmail and Calendar" in state.integrations:
+        lines.append("Gmail and Calendar need tools, which are off on this install.")
+    return lines
+

hyperclaw/managed_config.py

@@ -0,0 +1,245 @@
+"""Managed config: the settings Hyper sets for an install (docs/MODEL-POLICY.md).
+
+A small JSON file that the app only ever READS. There is no command, prompt or
+settings screen that writes it, so a user cannot change it through the app.
+Hyper's deployment tooling places it; on a Hyper-deployed install it lives in
+a system location the user's account normally cannot write.
+
+Location (first that is set wins):
+  1. ``HYPERCLAW_MANAGED_CONFIG`` (a path; set by Hyper's deployment, e.g. in
+     the launchd plist)
+  2. macOS: ``/Library/Application Support/HyperClaw/managed.json``
+     Linux and others: ``/etc/hyperclaw/managed.json``
+
+Format (schema 1)::
+
+    {
+      "schema": 1,
+      "allowed_models": ["hyperspeed/hospitality", "anthropic/claude-sonnet-5-5",
+                         "xai/grok-4.7"],
+      "hyper_issued_keys": ["anthropic", "xai"],
+      "model_names": {"anthropic/claude-sonnet-5-5": "Claude Sonnet 5.5"},
+      "telegram": true
+    }
+
+- ``allowed_models``: per-customer allowed-model list for a Hyper-deployed
+  install. Entries are ``<provider>/<model id>`` or ``<provider>/*`` (every
+  model of that provider). A model not on the list cannot be selected or
+  routed to. Missing, empty or unreadable: the default list, HyperSpeed V2
+  only. Standard installs are not restricted by it.
+- ``hyper_issued_keys``: providers whose key on this install Hyper issued.
+  Their models are labelled "<model name>, via Hyper"; every other
+  third-party key is "your own provider".
+- ``model_names``: optional display names, ``<provider>/<model id>`` -> name.
+- ``telegram``: install profile. ``true`` only on installs where Hyper has
+  set up the Telegram channel to run (team and client profiles: their own
+  bot, unattended mode on for the main service). Only then does onboarding
+  offer to connect it and does live state list it as available to connect.
+  Missing, not exactly ``true``, or no file: not offered (standard installs).
+- ``default_model``: optional, one entry of ``allowed_models`` that is the
+  install's default route (team profile: Claude Opus 5.5). Without it the
+  normal slot order applies (HyperSpeed V2 first).
+
+No managed file: a team install's Hyper-signed team profile
+(``hyperclaw.teamsetup.profile``, placed by ``hyperclaw onboard --team``) supplies
+these fields. It is verified on every read; one that doesn't verify is
+ignored and the defaults apply.
+
+When the gateway catalog is live it will carry the allowed list; until then
+this file is the source.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+log = logging.getLogger("hyperclaw.managed_config")
+
+ENV = "HYPERCLAW_MANAGED_CONFIG"
+SCHEMA = 1
+MAC_PATH = "/Library/Application Support/HyperClaw/managed.json"
+UNIX_PATH = "/etc/hyperclaw/managed.json"
+
+_ENTRY = re.compile(r"^[a-z0-9_]{1,40}/(\*|[A-Za-z0-9._:-][A-Za-z0-9._:/-]{0,127})$")
+_PROVIDER = re.compile(r"^[a-z0-9_]{1,40}$")
+_logged: set = set()
+
+
+def path() -> Path:
+    explicit = os.environ.get(ENV, "").strip()
+    if explicit:
+        return Path(explicit).expanduser()
+    return Path(MAC_PATH if sys.platform == "darwin" else UNIX_PATH)
+
+
+def _warn_once(msg: str) -> None:
+    if msg not in _logged:
+        _logged.add(msg)
+        log.warning(msg)
+
+
+def load() -> dict:
+    """The validated managed config, or {} when there is none (or it is
+    unreadable; then the defaults apply, which are the strictest)."""
+    p = path()
+    try:
+        if not p.is_file():
+            return _team_profile()
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except Exception as e:  # noqa: BLE001 -- never fatal: defaults apply
+        _warn_once(f"managed config {p} unreadable ({type(e).__name__}); defaults apply")
+        return {}
+    if not isinstance(data, dict):
+        _warn_once(f"managed config {p} is not a JSON object; defaults apply")
+        return {}
+    out: dict = {}
+    allowed = data.get("allowed_models")
+    if isinstance(allowed, list):
+        good = [e.strip() for e in allowed if isinstance(e, str) and _ENTRY.match(e.strip())]
+        if len(good) != len(allowed):
+            _warn_once(f"managed config {p}: invalid allowed_models entries dropped")
+        out["allowed_models"] = list(dict.fromkeys(good))
+    issued = data.get("hyper_issued_keys")
+    if isinstance(issued, list):
+        out["hyper_issued_keys"] = sorted({x for x in issued
+                                           if isinstance(x, str) and _PROVIDER.match(x)})
+    if "telegram" in data:
+        if not isinstance(data["telegram"], bool):
+            _warn_once(f"managed config {p}: telegram must be true or false; not offered")
+        out["telegram"] = data["telegram"] is True
+    default = data.get("default_model")
+    if isinstance(default, str) and _ENTRY.match(default.strip()) \
+            and default.strip() in out.get("allowed_models", []):
+        out["default_model"] = default.strip()
+    names = data.get("model_names")
+    if isinstance(names, dict):
+        out["model_names"] = {k: re.sub(r"[\x00-\x1f\x7f]", "", v)[:60].strip()
+                              for k, v in names.items()
+                              if isinstance(k, str) and _ENTRY.match(k)
+                              and isinstance(v, str) and v.strip()}
+    return out
+
+
+def raw() -> tuple:
+    """(data, readable) for readers of keys this module doesn't validate
+    (``restricted_clients``, ``restricted_clients_required``,
+    ``google_calendar_write``): the system managed file when present, else
+    the verified team profile. (None, True): neither exists. (None, False):
+    a file exists but can't be read or doesn't verify (callers fail safe)."""
+    p = path()
+    try:
+        if p.is_file():
+            data = json.loads(p.read_text(encoding="utf-8"))
+            return (data, True) if isinstance(data, dict) else (None, False)
+    except Exception:
+        return None, False
+    try:
+        from hyperclaw.teamsetup import profile
+        if not profile.path().exists():
+            return None, True
+        view = profile.managed_view()
+        return (view, True) if view else (None, False)
+    except Exception:
+        return None, False
+
+
+def source_key() -> str:
+    """Changes whenever the managed settings in force may have changed (for caches)."""
+    parts = []
+    for p in (path(), _team_profile_path()):
+        try:
+            parts.append(f"{p}:{p.stat().st_mtime_ns}")
+        except (OSError, TypeError):
+            parts.append(f"{p}:-")
+    return "|".join(parts)
+
+
+def _team_profile_path():
+    try:
+        from hyperclaw.teamsetup import profile
+        return profile.path()
+    except Exception:
+        return None
+
+
+def _team_profile() -> dict:
+    """The verified team profile's fields, or {} (hyperclaw.teamsetup.profile)."""
+    try:
+        from hyperclaw.teamsetup.profile import managed_view
+        return managed_view()
+    except Exception as e:  # noqa: BLE001 -- never fatal: defaults apply
+        _warn_once(f"team profile unreadable ({type(e).__name__}); defaults apply")
+        return {}
+
+
+# ───────────────────────── allowed-model list ─────────────────────────
+
+def default_allowed() -> list:
+    """Hyper-deployed default: HyperSpeed V2 only."""
+    from hyperclaw import hyperspeed
+    return [f"{hyperspeed.PROVIDER_NAME}/{hyperspeed.model()}"]
+
+
+def allowed_models() -> Optional[list]:
+    """The allowed list in force, or None when the install is not restricted
+    (standard installs)."""
+    from hyperclaw.deployment import is_hyper
+    if not is_hyper():
+        return None
+    return load().get("allowed_models") or default_allowed()
+
+
+def is_allowed(provider: str, model: str) -> bool:
+    allowed = allowed_models()
+    if allowed is None:
+        return True
+    return f"{provider}/{model}" in allowed or f"{provider}/*" in allowed
+
+
+def provider_allowed(provider: str) -> bool:
+    """True when any model of this provider is on the list (or no list)."""
+    allowed = allowed_models()
+    if allowed is None:
+        return True
+    return any(e.split("/", 1)[0] == provider for e in allowed)
+
+
+def default_model() -> str:
+    """'<provider>/<model id>' the install routes to by default, or ''.
+    Only on a Hyper-deployed install, and only when it is on the list."""
+    from hyperclaw.deployment import is_hyper
+    if not is_hyper():
+        return ""
+    d = load().get("default_model") or ""
+    return d if d and "*" not in d and is_allowed(*d.split("/", 1)) else ""
+
+
+def allowed_for(provider: str) -> list:
+    """Explicit model ids on the list for this provider ('*' included as-is)."""
+    allowed = allowed_models() or []
+    return [e.split("/", 1)[1] for e in allowed if e.split("/", 1)[0] == provider]
+
+
+# ───────────────────────── key origin + names ─────────────────────────
+
+def hyper_issued(provider: str) -> bool:
+    """True when Hyper issued this provider's key on this install."""
+    return provider in (load().get("hyper_issued_keys") or [])
+
+
+def model_name(provider: str, model: str) -> str:
+    return (load().get("model_names") or {}).get(f"{provider}/{model}", "")
+
+
+# ───────────────────────── install profile ─────────────────────────
+
+def telegram_allowed() -> bool:
+    """True only when the managed config says the Telegram channel can run on
+    this install (``"telegram": true``; team and client profiles). Standard
+    installs without it are never offered Telegram in onboarding."""
+    return load().get("telegram") is True

hyperclaw/media_hub.py

@@ -0,0 +1,179 @@
+"""
+Media Hub — unified outbound file delivery across every channel.
+
+deliver_file(path, via, to, caption) is the single entry point:
+    via='here'      -> queue for the current conversation (Telegram or iMessage,
+                       whichever this turn came from) via outbox
+    via='telegram'  -> Telegram sendPhoto/sendVideo/sendAudio/sendDocument
+    via='imessage'  -> Messages.app attachment via AppleScript
+    via='email'     -> Gmail with attachment (integrations_layer.gmail_send)
+    via='open'      -> open the file locally on the Mac (Preview/Word/etc.)
+
+Every sender is direct and synchronous — no daemon dependencies — so this works
+from the TUI, the Telegram bot, the iMessage daemon, and cron jobs alike.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+import httpx
+
+from . import outbox
+
+MAX_TG_BYTES = 49 * 1024 * 1024
+
+
+def _resolve(path: str) -> Path:
+    p = Path(path).expanduser()
+    if not p.exists():
+        raise FileNotFoundError(f"File not found: {p}")
+    return p
+
+
+# ── Telegram ─────────────────────────────────────────────────────────────────
+
+def telegram_send_file(path: str, caption: str = "", chat_id: str = "") -> str:
+    """Send any file over Telegram, picking the right API method by type."""
+    try:
+        p = _resolve(path)
+        _size = p.stat().st_size
+    except OSError as e:
+        return str(e)
+    token = os.environ.get("TELEGRAM_BOT_TOKEN", "")
+    cid = str(chat_id or os.environ.get("TELEGRAM_CHAT_ID", ""))
+    if not token or not cid:
+        return "Telegram not configured (TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID)"
+    if _size > MAX_TG_BYTES:
+        return f"File too large for Telegram ({_size // (1024*1024)}MB > 49MB). Email it instead."
+
+    kind = outbox.kind_of(str(p))
+    method, field = {
+        "photo": ("sendPhoto", "photo"),
+        "video": ("sendVideo", "video"),
+        "audio": ("sendAudio", "audio"),
+        "document": ("sendDocument", "document"),
+    }[kind]
+    data = {"chat_id": cid}
+    if caption:
+        data["caption"] = caption[:1024]
+    from hyperclaw.tools.receipts import redact, telegram_receipt
+    try:
+        with open(p, "rb") as f:
+            with httpx.Client(timeout=120) as client:
+                r = client.post(f"https://api.telegram.org/bot{token}/{method}",
+                                data=data, files={field: (p.name, f)})
+        # Success only with Telegram's receipt: ok=true AND message_id (bench 20.3).
+        mid, why = telegram_receipt(r)
+        if mid:
+            return f"Sent {p.name} via Telegram ({kind}) [id:{mid}]"
+        # Photos with odd dimensions/format can fail — retry as document.
+        if kind == "photo":
+            with open(p, "rb") as f:
+                with httpx.Client(timeout=120) as client:
+                    r2 = client.post(f"https://api.telegram.org/bot{token}/sendDocument",
+                                     data=data, files={"document": (p.name, f)})
+            mid, why = telegram_receipt(r2)
+            if mid:
+                return f"Sent {p.name} via Telegram (document) [id:{mid}]"
+        return f"Telegram send failed: {why}"
+    except Exception as e:
+        return f"Telegram send error: {redact(e)}"
+
+
+# ── iMessage ─────────────────────────────────────────────────────────────────
+
+def imessage_send_file(path: str, recipient: str = "", message: str = "") -> str:
+    """Send a file (and optional text) over iMessage via Messages.app."""
+    try:
+        p = _resolve(path)
+    except OSError as e:
+        return str(e)
+    recipient = recipient or os.environ.get("OWNER_PHONE", "") or os.environ.get("DEFAULT_PHONE", "")
+    if not recipient:
+        return "No iMessage recipient (set OWNER_PHONE)"
+    r_esc = recipient.replace("\\", "\\\\").replace('"', '\\"')
+    m_esc = (message or "").replace("\\", "\\\\").replace('"', '\\"').replace("\n", " ").replace("\r", " ")
+    f_esc = str(p).replace("\\", "\\\\").replace('"', '\\"')
+    text_line = f'send "{m_esc}" to targetBuddy' if message else ""
+    script = f'''
+    tell application "Messages"
+        set targetService to 1st service whose service type = iMessage
+        set targetBuddy to buddy "{r_esc}" of targetService
+        {text_line}
+        send POSIX file "{f_esc}" to targetBuddy
+    end tell
+    '''
+    try:
+        res = subprocess.run(["osascript", "-e", script], capture_output=True, text=True, timeout=60)
+        if res.returncode == 0:
+            return f"Sent {p.name} via iMessage to {recipient}"
+        return f"iMessage send failed: {res.stderr.strip()[:200]}"
+    except Exception as e:
+        return f"iMessage send error: {e}"
+
+
+# ── Email ────────────────────────────────────────────────────────────────────
+
+def email_send_file(path: str, to: str, subject: str = "", body: str = "", cc: str = "") -> str:
+    """Email a file as an attachment via Gmail."""
+    try:
+        p = _resolve(path)
+    except OSError as e:
+        return str(e)
+    try:
+        from .integrations_layer import gmail_send
+        result = gmail_send(
+            to=to,
+            subject=subject or f"File: {p.name}",
+            body=body or f"Attached: {p.name}",
+            cc=cc,
+            attachments=[str(p)],
+        )
+        if isinstance(result, dict) and result.get("status") == "sent" and result.get("id"):
+            return f"Emailed {p.name} to {to} [id:{result['id']}]"
+        if isinstance(result, dict) and result.get("status") == "sent":
+            return "Email send failed: Gmail returned no message id, so delivery is not confirmed"
+        return f"Email send failed: {result}"
+    except Exception as e:
+        return f"Email send error: {e}"
+
+
+# ── Local ────────────────────────────────────────────────────────────────────
+
+def open_file(path: str, app: str = "") -> str:
+    """Open a file locally on the Mac (default app, or a named app)."""
+    try:
+        p = _resolve(path)
+        cmd = ["open", str(p)] if not app else ["open", "-a", app, str(p)]
+        res = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        if res.returncode == 0:
+            return f"Opened {p.name}" + (f" in {app}" if app else "")
+        return f"Open failed: {res.stderr.strip()[:200]}"
+    except subprocess.TimeoutExpired:
+        return "Open failed: timed out after 30s"
+    except OSError as e:
+        return f"Open failed: {e}"
+
+
+# ── Unified entry ────────────────────────────────────────────────────────────
+
+def deliver_file(path: str, via: str = "here", to: str = "", caption: str = "", app: str = "") -> str:
+    """Single entry point for delivering a file anywhere."""
+    via = (via or "here").lower().strip()
+    if via in ("here", "chat", "conversation"):
+        return outbox.queue_file(path, caption=caption)
+    if via == "telegram":
+        return telegram_send_file(path, caption=caption, chat_id=to)
+    if via == "imessage":
+        return imessage_send_file(path, recipient=to, message=caption)
+    if via == "email":
+        if not to:
+            return "Email delivery needs a recipient (to=...)"
+        return email_send_file(path, to=to, body=caption)
+    if via == "open":
+        return open_file(path, app=app or to)
+    return f"Unknown delivery channel: {via} (use here|telegram|imessage|email|open)"