hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/unattended.py

@@ -0,0 +1,60 @@
+"""Unattended mode: one switch for everything HyperClaw does on its own.
+
+``HYPERCLAW_UNATTENDED=1`` turns on the scheduled jobs (heartbeat, morning
+brief, memory consolidation, ...) and Telegram polling. Anything else,
+including ``true``, ``yes``, ``0`` or an empty/unset value, leaves them OFF.
+Off is the default (Vaughn's rc3 ruling, 2026-10-09: internal team only,
+overnight and unattended tasks switched off).
+
+The interactive terminal (``hyperclaw``, ``python -m hyperclaw tui``) and
+request-driven API endpoints do not depend on this flag.
+
+When a background entry point starts with the flag off it logs ONE line
+(``OFF_LINE``) and does nothing: the server keeps serving, a stand-alone
+poller exits with status 0 so launchd (``KeepAlive.SuccessfulExit=false``)
+does not restart it.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+ENV = "HYPERCLAW_UNATTENDED"
+
+OFF_LINE = ("Unattended mode is off: scheduled jobs and Telegram polling are not "
+            "started. To turn them on, set HYPERCLAW_UNATTENDED=1 (only the exact "
+            "value 1 enables it).")
+
+
+def enabled() -> bool:
+    """True only when HYPERCLAW_UNATTENDED is exactly ``1``."""
+    return os.environ.get(ENV, "") == "1"
+
+
+_said = False   # one line per process, however many entry points ask
+
+
+def log_off(logger: logging.Logger | None = None, what: str = "") -> bool:
+    """Log the 'unattended mode is off' line, once per process. Returns
+    whether it logged now."""
+    global _said
+    if _said:
+        return False
+    _said = True
+    line = f"{OFF_LINE} ({what})" if what else OFF_LINE
+    (logger or logging.getLogger("hyperclaw.unattended")).warning(line)
+    return True
+
+
+def exit_if_off(logger: logging.Logger | None = None, what: str = "") -> None:
+    """For stand-alone pollers/daemons: when the flag is off, log the line and
+    exit 0 (a clean exit, so a KeepAlive/on-failure supervisor does not
+    restart it)."""
+    if enabled():
+        return
+    if logging.getLogger().handlers or (logger is not None and logger.handlers):
+        log_off(logger, what)
+    else:  # logging not configured yet: still say it, once, on stderr
+        print(OFF_LINE + (f" ({what})" if what else ""), file=sys.stderr)
+    raise SystemExit(0)

hyperclaw/updates/__init__.py

@@ -0,0 +1,54 @@
+"""HyperClaw terminal updates (docs/UPDATES.md).
+
+Entry points call :func:`on_startup` once. It never raises, never blocks on
+the network, and does nothing when ``HYPERCLAW_NO_UPDATE_CHECK=1``.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+
+log = logging.getLogger("hyperclaw.updates")
+
+INTERACTIVE = ("cli", "tui")
+_done = False
+
+
+def startup_lines(surface: str = "cli") -> list:
+    """What the startup notice would show (cache + unread owner notices)."""
+    from hyperclaw.updates import check, notices
+    from hyperclaw.updates.paths import opted_out
+    if opted_out():
+        return []
+    lines = []
+    if surface in INTERACTIVE:
+        lines += [f"[update] {t}" for t in notices.unread(mark_read=True)]
+    n = check.notice_text()
+    if n:
+        lines.append(n)
+    return lines
+
+
+def on_startup(surface: str = "cli", *, out=None) -> None:
+    """Startup hook: show the cached notice, refresh a stale cache in the
+    background and, on long-running surfaces, start the managed scheduler
+    (only when its gate passes). Once per process."""
+    global _done
+    if _done:
+        return
+    _done = True
+    try:
+        from hyperclaw.updates import check, managed
+        from hyperclaw.updates.paths import opted_out
+        if opted_out():
+            return
+        for line in startup_lines(surface):
+            if surface in INTERACTIVE:
+                print(line, file=out or sys.stderr)
+            else:
+                log.warning(line)
+        check.maybe_refresh_in_background()
+        if surface not in INTERACTIVE:
+            managed.start_scheduler()
+    except Exception as e:  # never let the updater break startup
+        log.debug("update startup hook: %s", e)

hyperclaw/updates/check.py

@@ -0,0 +1,131 @@
+"""Cached, rate-limited, offline-safe version check + the startup notice.
+
+Startup only ever READS the cache. A stale cache is refreshed in a daemon
+thread (short timeouts), so the notice for a new release appears on the next
+start. A version is only advertised once its signed manifest verifies.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import logging
+import threading
+from typing import Optional
+
+from hyperclaw import distribution as _dist
+from hyperclaw.updates import index, versioning
+from hyperclaw.updates.manifest import ManifestError
+from hyperclaw.updates.paths import (current_version, opted_out, read_json, updates_dir,
+                                     write_json)
+
+log = logging.getLogger("hyperclaw.updates")
+
+CHECK_INTERVAL = _dt.timedelta(hours=24)
+FAIL_BACKOFF = _dt.timedelta(hours=6)
+TIMEOUT = 4.0
+
+
+def _now() -> _dt.datetime:
+    return _dt.datetime.now(_dt.timezone.utc)
+
+
+def cache_path():
+    return updates_dir() / "check.json"
+
+
+def load_cache() -> dict:
+    c = read_json(cache_path(), {})
+    return c if isinstance(c, dict) else {}
+
+
+def _ts(s) -> Optional[_dt.datetime]:
+    try:
+        t = _dt.datetime.fromisoformat(str(s))
+        return t if t.tzinfo else t.replace(tzinfo=_dt.timezone.utc)
+    except Exception:
+        return None
+
+
+def is_due(cache: dict, now: Optional[_dt.datetime] = None) -> bool:
+    now = now or _now()
+    last = _ts(cache.get("checked_at"))
+    if last is None:
+        return True
+    wait = FAIL_BACKOFF if cache.get("error") else CHECK_INTERVAL
+    return now - last >= wait or last > now + _dt.timedelta(minutes=5)
+
+
+def refresh(now: Optional[_dt.datetime] = None, *, timeout: float = TIMEOUT,
+            current: Optional[str] = None) -> dict:
+    """Ask the index for the newest release and verify its signed manifest.
+    Never raises; failures are recorded in the cache (and back off)."""
+    now = now or _now()
+    current = current or current_version()
+    cache = load_cache()
+    cache.update({"checked_at": now.isoformat(), "current": current})
+    try:
+        info = index.project_info(timeout=timeout)
+        latest = index.latest_version(info, include_pre=index.include_prereleases(current))
+        cache["latest"] = latest
+        cache.pop("error", None)
+        if latest and versioning.is_newer(latest, current):
+            try:
+                rel = index.release_info(latest, timeout=timeout)
+                m = index.fetch_manifest(latest, rel, timeout=timeout)
+                cache["latest_signed"] = m["version"]
+                cache["min_upgrade_from"] = m["min_upgrade_from"]
+                cache.pop("unsigned", None)
+            except (ManifestError, index.IndexError_) as e:
+                cache["unsigned"] = latest
+                cache.pop("latest_signed", None)
+                log.info("update check: %s is not installable: %s", latest, e)
+        else:
+            cache.pop("latest_signed", None)
+            cache.pop("unsigned", None)
+    except Exception as e:  # offline, DNS, bad JSON, anything: never raise
+        cache["error"] = f"{type(e).__name__}"
+        log.debug("update check failed: %s", e)
+    try:
+        write_json(cache_path(), cache)
+    except Exception:
+        pass
+    return cache
+
+
+def notice_text(cache: Optional[dict] = None, current: Optional[str] = None,
+                legacy: Optional[bool] = None) -> Optional[str]:
+    """The one-line notice, or None. Reads the cache only (no network)."""
+    if opted_out():
+        return None
+    cache = load_cache() if cache is None else cache
+    current = current or current_version()
+    if _dist.is_legacy_install() if legacy is None else legacy:
+        # Old ``hyperclaw`` distribution: the only notice is how to move over.
+        latest = cache.get("latest")
+        if not latest or not versioning.is_newer(latest, current):
+            latest = current
+        return _dist.migration_line(latest)
+    latest = cache.get("latest_signed")
+    if not latest or not versioning.is_newer(latest, current):
+        return None
+    mn = versioning.parse(cache.get("min_upgrade_from") or "0")
+    cur = versioning.parse(current)
+    if mn and cur and cur < mn:
+        return (f"HyperClaw {latest} is available (you have {current}); upgrade to "
+                f"{cache.get('min_upgrade_from')} first. Run 'hyperclaw upgrade'.")
+    return (f"HyperClaw {latest} is available (you have {current}). "
+            f"Run 'hyperclaw upgrade' to see what's new.")
+
+
+_thread: Optional[threading.Thread] = None
+
+
+def maybe_refresh_in_background(now: Optional[_dt.datetime] = None) -> Optional[threading.Thread]:
+    """Start one daemon refresh if the cache is stale. Returns the thread."""
+    global _thread
+    if opted_out() or not is_due(load_cache(), now):
+        return None
+    if _thread is not None and _thread.is_alive():
+        return None
+    _thread = threading.Thread(target=refresh, name="hyperclaw-update-check", daemon=True)
+    _thread.start()
+    return _thread

hyperclaw/updates/index.py

@@ -0,0 +1,178 @@
+"""Talking to the package index (PyPI JSON API) and fetching signed manifests.
+
+Only ``https`` URLs are fetched, plus plain ``http`` to a loopback host (a
+local mirror or the unit tests' fake index). Every call has a timeout and a
+size cap. Nothing here installs anything.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Optional
+
+from hyperclaw.updates import manifest as _m
+from hyperclaw.updates import versioning
+
+DEFAULT_INDEX = "https://pypi.org/pypi"
+INDEX_ENV = "HYPERCLAW_UPDATE_INDEX_URL"
+MANIFEST_URL_ENV = "HYPERCLAW_UPDATE_MANIFEST_URL"
+PRERELEASE_ENV = "HYPERCLAW_UPDATE_PRERELEASE"
+MANIFEST_URL_KEYS = ("release-manifest", "release manifest", "release_manifest")
+
+JSON_CAP = 8 << 20
+WHEEL_CAP = 200 << 20
+_LOOPBACK = {"127.0.0.1", "localhost", "::1"}
+
+
+class IndexError_(Exception):
+    """Index unreachable or answered something unusable."""
+
+
+def index_url() -> str:
+    return (os.environ.get(INDEX_ENV, "").strip() or DEFAULT_INDEX).rstrip("/")
+
+
+def _check_url(url: str) -> str:
+    u = urllib.parse.urlparse(url)
+    if u.scheme == "https" and u.hostname:
+        return url
+    if u.scheme == "http" and (u.hostname or "") in _LOOPBACK:
+        return url
+    raise IndexError_(f"refusing non-https URL ({u.scheme}://{u.hostname})")
+
+
+def _open(url: str, timeout: float):
+    req = urllib.request.Request(_check_url(url), headers={
+        "User-Agent": "hyperclaw-updater", "Accept": "application/json, */*"})
+    return urllib.request.urlopen(req, timeout=timeout)  # noqa: S310 (scheme checked)
+
+
+def fetch_bytes(url: str, *, timeout: float = 10, cap: int = JSON_CAP) -> bytes:
+    try:
+        with _open(url, timeout) as r:
+            data = r.read(cap + 1)
+    except IndexError_:
+        raise
+    except Exception as e:
+        raise IndexError_(f"fetch failed: {type(e).__name__}")
+    if len(data) > cap:
+        raise IndexError_("response too large")
+    return data
+
+
+def fetch_json(url: str, *, timeout: float = 10):
+    try:
+        return json.loads(fetch_bytes(url, timeout=timeout).decode("utf-8"))
+    except IndexError_:
+        raise
+    except Exception:
+        raise IndexError_("index returned invalid JSON")
+
+
+def project_info(*, timeout: float = 10) -> dict:
+    return fetch_json(f"{index_url()}/{_m.PACKAGE}/json", timeout=timeout)
+
+
+def release_info(version: str, *, timeout: float = 10) -> dict:
+    return fetch_json(f"{index_url()}/{_m.PACKAGE}/{versioning.normalize(version)}/json",
+                      timeout=timeout)
+
+
+def include_prereleases(current: str) -> bool:
+    if os.environ.get(PRERELEASE_ENV, "").strip() == "1":
+        return True
+    v = versioning.parse(current)
+    return bool(v and v.is_prerelease)
+
+
+def latest_version(info: dict, *, include_pre: bool) -> Optional[str]:
+    """Highest non-yanked release on the index (prereleases only if asked)."""
+    best = None
+    for ver, files in (info.get("releases") or {}).items():
+        v = versioning.parse(ver)
+        if v is None or v.local or (v.is_prerelease and not include_pre):
+            continue
+        if isinstance(files, list) and files and all(f.get("yanked") for f in files):
+            continue
+        if best is None or v > best:
+            best = v
+    return str(best) if best else None
+
+
+def manifest_url_for(version: str, release_json: Optional[dict]) -> Optional[str]:
+    """The release's manifest URL: env template, else the release's own
+    ``Release-Manifest`` project URL. ``{version}`` is substituted."""
+    tpl = os.environ.get(MANIFEST_URL_ENV, "").strip()
+    if not tpl and isinstance(release_json, dict):
+        urls = (release_json.get("info") or {}).get("project_urls") or {}
+        for k, val in urls.items():
+            if str(k).strip().lower() in MANIFEST_URL_KEYS and val:
+                tpl = str(val)
+                break
+    if not tpl:
+        return None
+    return tpl.replace("{version}", versioning.normalize(version))
+
+
+def fetch_manifest(version: str, release_json: Optional[dict] = None, *,
+                   timeout: float = 10) -> dict:
+    """Fetch and VERIFY the signed manifest for ``version``.
+    Raises ManifestError when there is none or it does not verify."""
+    return fetch_signed(version, release_json, timeout=timeout)[0]
+
+
+def fetch_signed(version: str, release_json: Optional[dict] = None, *,
+                 timeout: float = 10):
+    """(verified manifest, signed envelope) for ``version``; ManifestError otherwise."""
+    url = manifest_url_for(version, release_json)
+    if not url:
+        raise _m.ManifestError(f"release {version} has no signed manifest (unsigned release)")
+    try:
+        env = fetch_json(url, timeout=timeout)
+    except IndexError_ as e:
+        raise _m.ManifestError(f"signed manifest for {version} unavailable ({e})")
+    return _m.verify_manifest(env, expect_version=version), env
+
+
+def wheel_url(release_json: dict, filename: str) -> str:
+    for f in release_json.get("urls") or []:
+        if f.get("filename") == filename:
+            if f.get("yanked"):
+                raise IndexError_(f"{filename} is yanked")
+            return f["url"]
+    raise IndexError_(f"{filename} is not on the index")
+
+
+def download_wheel(url: str, dest_dir: Path, manifest: dict, *, timeout: float = 60) -> Path:
+    """Download into ``dest_dir`` and check size + sha256 against the signed
+    manifest. A mismatching file is deleted and ManifestError raised."""
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / manifest["wheel"]
+    part = dest.with_suffix(".part")
+    h, n = hashlib.sha256(), 0
+    try:
+        with _open(url, timeout) as r, open(part, "wb") as out:
+            while True:
+                chunk = r.read(1 << 16)
+                if not chunk:
+                    break
+                n += len(chunk)
+                if n > min(WHEEL_CAP, manifest["size"]):
+                    raise _m.ManifestError("wheel is larger than the signed manifest says")
+                h.update(chunk)
+                out.write(chunk)
+    except _m.ManifestError:
+        part.unlink(missing_ok=True)
+        raise
+    except Exception as e:
+        part.unlink(missing_ok=True)
+        raise IndexError_(f"wheel download failed: {type(e).__name__}")
+    if n != manifest["size"] or h.hexdigest() != manifest["sha256"]:
+        part.unlink(missing_ok=True)
+        raise _m.ManifestError("wheel sha256 does not match the signed manifest")
+    os.replace(part, dest)
+    return dest

hyperclaw/updates/install.py

@@ -0,0 +1,110 @@
+"""Install-method detection, the pip/pipx call, and the post-install check.
+
+Supported: a pipx install (``.../pipx/venvs/<name>``) and a plain venv. Any
+other interpreter (system Python, container image) is refused with
+instructions; the updater never pip-installs into a system Python.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, List, Optional, Tuple
+
+from hyperclaw.updates import versioning
+
+UNSUPPORTED = (
+    "This HyperClaw is not installed with pipx or in a virtualenv, so "
+    "'hyperclaw upgrade' cannot update it safely.\n"
+    "Reinstall with pipx (recommended):  pipx install hyperagents\n"
+    "or, in a container, rebuild the image with the new version.")
+
+
+class UnsupportedInstall(Exception):
+    pass
+
+
+@dataclass
+class InstallMethod:
+    kind: str                 # "pipx" | "venv"
+    prefix: Path              # the environment HyperClaw runs from
+    pip: List[str]            # command prefix that runs pip in that env
+    name: str = ""            # pipx venv name
+
+    @property
+    def bin_dir(self) -> Path:
+        return self.prefix / ("Scripts" if os.name == "nt" else "bin")
+
+    def hyperclaw_exe(self) -> Path:
+        return self.bin_dir / ("hyperclaw.exe" if os.name == "nt" else "hyperclaw")
+
+
+def _pipx_venvs_roots(env) -> List[Path]:
+    roots = []
+    if env.get("PIPX_HOME"):
+        roots.append(Path(env["PIPX_HOME"]) / "venvs")
+    home = Path(env.get("HOME") or Path.home())
+    roots += [home / ".local" / "pipx" / "venvs", home / ".local" / "share" / "pipx" / "venvs"]
+    return roots
+
+
+def detect(prefix: Optional[str] = None, base_prefix: Optional[str] = None,
+           env=None) -> InstallMethod:
+    env = os.environ if env is None else env
+    pfx = Path(prefix or sys.prefix)
+    base = Path(base_prefix or sys.base_prefix)
+    parent = pfx.parent
+    is_pipx = parent.name == "venvs" and (
+        parent.parent.name == "pipx" or any(parent == r for r in _pipx_venvs_roots(env)))
+    if is_pipx:
+        pipx = shutil.which("pipx", path=env.get("PATH"))
+        if not pipx:
+            raise UnsupportedInstall(
+                "HyperClaw is installed with pipx, but the 'pipx' command is not on PATH. "
+                "Add it to PATH and run 'hyperclaw upgrade' again.")
+        return InstallMethod("pipx", pfx, [pipx, "runpip", pfx.name], name=pfx.name)
+    if pfx.resolve() != base.resolve():
+        py = pfx / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+        return InstallMethod("venv", pfx, [str(py), "-m", "pip"])
+    raise UnsupportedInstall(UNSUPPORTED)
+
+
+Runner = Callable[..., "subprocess.CompletedProcess"]
+
+
+def install(method: InstallMethod, wheel: Path, *, force: bool = False,
+            runner: Runner = subprocess.run) -> Tuple[bool, str]:
+    cmd = list(method.pip) + ["install", "--disable-pip-version-check", "-q"]
+    if force:
+        cmd += ["--force-reinstall", "--no-deps"]
+    cmd.append(str(wheel))
+    try:
+        r = runner(cmd, capture_output=True, text=True, timeout=900, check=False)
+    except Exception as e:
+        return False, f"{type(e).__name__}: {e}"
+    return r.returncode == 0, (r.stdout or "") + (r.stderr or "")
+
+
+_VER = re.compile(r"\bv?(\d+(?:\.\d+)+\S*)")
+
+
+def installed_version(method: InstallMethod, *, runner: Runner = subprocess.run) -> Optional[str]:
+    """Run ``hyperclaw version`` in the target env and parse the version."""
+    try:
+        r = runner([str(method.hyperclaw_exe()), "version"], capture_output=True,
+                   text=True, timeout=120, check=False)
+    except Exception:
+        return None
+    if r.returncode != 0:
+        return None
+    m = _VER.search(re.sub(r"\x1b\[[0-9;]*m", "", r.stdout or ""))
+    return m.group(1) if m else None
+
+
+def verify(method: InstallMethod, expect: str, *, runner: Runner = subprocess.run) -> bool:
+    got = installed_version(method, runner=runner)
+    return bool(got) and versioning.parse(got) == versioning.parse(expect)