hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/updates/managed.py

@@ -0,0 +1,161 @@
+"""Managed push for Hyper-deployed installs (docs/UPDATES.md, "Managed push").
+
+Unattended apply happens only when ALL hold: HYPERCLAW_DEPLOYMENT=hyper,
+channel ``managed`` (explicit opt-in), HYPERCLAW_UNATTENDED=1, and the update
+check is not opted out. It runs inside the configured quiet hour (local time),
+at most once per local day, through the same signed-only upgrade path, and
+the owner is notified of the outcome.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import logging
+import os
+import threading
+from typing import Callable, Optional, Tuple
+
+from hyperclaw.updates import notices
+from hyperclaw.updates.paths import opted_out, read_json, updates_dir, write_json
+
+log = logging.getLogger("hyperclaw.updates")
+
+CHANNEL_ENV = "HYPERCLAW_UPDATE_CHANNEL"
+QUIET_HOUR_ENV = "HYPERCLAW_UPDATE_QUIET_HOUR"
+MANAGED = "managed"
+NOTIFY = "notify"
+DEFAULT_QUIET_HOUR = 3
+
+
+def _config_updates() -> dict:
+    try:
+        from hyperclaw.userconfig import load_config
+        u = load_config().get("updates")
+        return u if isinstance(u, dict) else {}
+    except Exception:
+        return {}
+
+
+def channel() -> str:
+    v = os.environ.get(CHANNEL_ENV, "").strip().lower() or \
+        str(_config_updates().get("channel", "")).strip().lower()
+    return MANAGED if v == MANAGED else NOTIFY
+
+
+def quiet_hour() -> int:
+    raw = os.environ.get(QUIET_HOUR_ENV, "").strip()
+    if not raw:
+        raw = str(_config_updates().get("quiet_hour", "")).strip()
+    try:
+        h = int(raw)
+        return h if 0 <= h <= 23 else DEFAULT_QUIET_HOUR
+    except ValueError:
+        return DEFAULT_QUIET_HOUR
+
+
+def gate() -> Tuple[bool, str]:
+    """(allowed, reason) for an UNATTENDED apply."""
+    from hyperclaw import unattended
+    from hyperclaw.deployment import is_hyper
+    if opted_out():
+        return False, "update checks are opted out (HYPERCLAW_NO_UPDATE_CHECK)"
+    if not is_hyper():
+        return False, "not a Hyper-deployed install (HYPERCLAW_DEPLOYMENT=hyper)"
+    if channel() != MANAGED:
+        return False, f"managed channel not opted in ({CHANNEL_ENV}=managed)"
+    if not unattended.enabled():
+        return False, "unattended mode is off (HYPERCLAW_UNATTENDED=1)"
+    return True, "ok"
+
+
+def in_quiet_window(now_local: _dt.datetime, hour: Optional[int] = None) -> bool:
+    return now_local.hour == (quiet_hour() if hour is None else hour)
+
+
+def next_quiet_time(now_local: _dt.datetime, hour: Optional[int] = None) -> _dt.datetime:
+    """Start of the next quiet window at or after ``now_local`` (now if inside it)."""
+    h = quiet_hour() if hour is None else hour
+    start = now_local.replace(hour=h, minute=0, second=0, microsecond=0)
+    if now_local.hour == h:
+        return now_local
+    if start <= now_local:
+        start += _dt.timedelta(days=1)
+    return start
+
+
+def _state_path():
+    return updates_dir() / "managed-tick.json"
+
+
+def tick(now_local: Optional[_dt.datetime] = None, *,
+         upgrade_fn: Optional[Callable] = None,
+         notify_fn: Callable[[str], None] = notices.notify) -> str:
+    """One managed-channel check. Returns a short status word."""
+    ok, reason = gate()
+    if not ok:
+        log.info("managed update: not applying (%s)", reason)
+        return "gated"
+    now_local = now_local or _dt.datetime.now().astimezone()
+    if not in_quiet_window(now_local):
+        return "not-due"
+    day = now_local.date().isoformat()
+    st = read_json(_state_path(), {})
+    if st.get("last_attempt_day") == day:
+        return "already-ran"
+    st["last_attempt_day"] = day
+    write_json(_state_path(), st)
+
+    if upgrade_fn is None:
+        from hyperclaw.updates.upgrade import upgrade as upgrade_fn
+    lines = []
+    res = upgrade_fn(yes=True, source="managed", out=lines.append)
+    st["last_result"] = {"day": day, "status": res.status, "message": res.message}
+    write_json(_state_path(), st)
+    if res.status == "up-to-date":
+        return res.status
+    if res.status == "upgraded":
+        notify_fn(f"HyperClaw was updated {res.before} -> {res.after} at the quiet hour "
+                  f"(managed channel). Restart HyperClaw services to run it; "
+                  f"'hyperclaw upgrade --rollback' restores {res.before}.")
+    else:
+        notify_fn(f"HyperClaw managed update did not apply ({res.status}): {res.message}")
+    return res.status
+
+
+_thread: Optional[threading.Thread] = None
+
+
+def _loop(stop: threading.Event, sleep_cap: float = 900.0) -> None:
+    while not stop.is_set():
+        try:
+            now = _dt.datetime.now().astimezone()
+            if in_quiet_window(now):
+                tick(now)
+                now = _dt.datetime.now().astimezone()
+            nxt = next_quiet_time(now + _dt.timedelta(minutes=1))
+            wait = max(30.0, min(sleep_cap, (nxt - now).total_seconds()))
+        except Exception:
+            log.exception("managed update scheduler")
+            wait = sleep_cap
+        stop.wait(wait)
+
+
+def start_scheduler(stop: Optional[threading.Event] = None) -> Optional[threading.Thread]:
+    """Start the daemon scheduler once per process, only when the gate passes."""
+    global _thread
+    ok, reason = gate()
+    if not ok:
+        return None
+    if _thread is not None and _thread.is_alive():
+        return _thread
+    _thread = threading.Thread(target=_loop, args=(stop or threading.Event(),),
+                               name="hyperclaw-managed-updates", daemon=True)
+    _thread.start()
+    log.info("managed updates: on (quiet hour %02d:00 local)", quiet_hour())
+    return _thread
+
+
+def describe() -> str:
+    ok, reason = gate()
+    if ok:
+        return f"managed channel: ON, applies at {quiet_hour():02d}:00 local"
+    return f"managed channel: off ({reason})"

hyperclaw/updates/manifest.py

@@ -0,0 +1,138 @@
+"""Hyper-signed release manifests (docs/UPDATES.md, "Trust model").
+
+Envelope::
+
+    {"manifest": {"type": "hyperclaw-release-manifest", "package": "hyperagents",
+                  "version": "1.2.4", "wheel": "hyperagents-1.2.4-py3-none-any.whl",
+                  "sha256": "<hex>", "size": 123, "release_notes": "...",
+                  "min_upgrade_from": "1.2.3rc3", "issued_at": "...Z",
+                  "key_id": "hyper-<16 hex>"},
+     "signature": "<base64 Ed25519 over canonical(manifest)>"}
+
+Keys, canonical form and key ids are shared with ``hyperclaw.qualification``
+(public keys shipped in ``hyperclaw/qualification_keys``; private key in the
+maintainer keychain). The ``type`` field keeps a qualification record from
+ever passing as a release manifest.
+"""
+from __future__ import annotations
+
+import base64
+import datetime as _dt
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Optional
+
+from hyperclaw import qualification as _q
+from hyperclaw.updates import versioning
+
+TYPE = "hyperclaw-release-manifest"
+from hyperclaw.distribution import DIST_NAME as PACKAGE  # "hyperagents" (wheel prefix + index project)
+FIELDS_REQUIRED = ("type", "package", "version", "wheel", "sha256", "size",
+                   "release_notes", "min_upgrade_from", "issued_at", "key_id")
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+
+
+class ManifestError(Exception):
+    """The manifest is unsigned, malformed or does not verify. Never install."""
+
+
+def manifest_filename(version: str) -> str:
+    return f"{PACKAGE}-{versioning.normalize(version)}.manifest.json"
+
+
+def wheel_version(filename: str) -> Optional[str]:
+    """Version field of a wheel filename (``name-ver-...-....whl``)."""
+    name = Path(filename).name
+    if not name.endswith(".whl"):
+        return None
+    parts = name[:-4].split("-")
+    if len(parts) < 5:
+        return None
+    return parts[1]
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def make_manifest(*, version: str, wheel: str, sha256: str, size: int,
+                  release_notes: str, min_upgrade_from: str) -> dict:
+    return {"type": TYPE, "package": PACKAGE, "version": versioning.normalize(version),
+            "wheel": wheel, "sha256": sha256.lower(), "size": int(size),
+            "release_notes": release_notes,
+            "min_upgrade_from": versioning.normalize(min_upgrade_from),
+            "issued_at": _dt.datetime.now(_dt.timezone.utc).replace(microsecond=0)
+            .isoformat().replace("+00:00", "Z")}
+
+
+def sign_manifest(manifest: dict, private_raw: bytes) -> dict:
+    m = dict(manifest)
+    m["key_id"] = _q.key_id_for(_q._public_raw(private_raw))
+    sig = _q._private_key(private_raw).sign(_q.canonical(m))
+    return {"manifest": m, "signature": base64.b64encode(sig).decode("ascii")}
+
+
+def verify_manifest(env, *, expect_version: Optional[str] = None) -> dict:
+    """Return the verified manifest dict or raise ManifestError(reason)."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    if not isinstance(env, dict) or not isinstance(env.get("manifest"), dict):
+        raise ManifestError("unsigned or malformed manifest")
+    m, sig = env["manifest"], env.get("signature")
+    if not isinstance(sig, str) or not sig:
+        raise ManifestError("manifest is unsigned")
+    missing = [f for f in FIELDS_REQUIRED if m.get(f) in (None, "")]
+    if missing:
+        raise ManifestError(f"manifest missing fields: {', '.join(missing)}")
+    raw = _q.trusted_keys().get(m.get("key_id"))
+    if raw is None:
+        raise ManifestError("manifest signed by an unknown key")
+    try:
+        Ed25519PublicKey.from_public_bytes(raw).verify(
+            base64.b64decode(sig, validate=True), _q.canonical(m))
+    except (InvalidSignature, ValueError, TypeError):
+        raise ManifestError("manifest signature does not verify")
+    if m["type"] != TYPE or m["package"] != PACKAGE:
+        raise ManifestError("not a HyperClaw release manifest")
+    v = versioning.parse(m["version"])
+    if v is None or v.local:
+        raise ManifestError("manifest version is invalid")
+    if versioning.parse(m["min_upgrade_from"]) is None:
+        raise ManifestError("manifest min_upgrade_from is invalid")
+    if not isinstance(m["sha256"], str) or not _HEX64.match(m["sha256"]):
+        raise ManifestError("manifest sha256 is invalid")
+    if not isinstance(m["size"], int) or m["size"] <= 0:
+        raise ManifestError("manifest size is invalid")
+    wv = wheel_version(m["wheel"])
+    if ("/" in m["wheel"] or "\\" in m["wheel"] or not m["wheel"].startswith(PACKAGE + "-")
+            or versioning.parse(wv) != v):
+        raise ManifestError("manifest wheel filename does not match its version")
+    if expect_version is not None and versioning.parse(expect_version) != v:
+        raise ManifestError(f"manifest is for {m['version']}, not {expect_version}")
+    return m
+
+
+def load_and_verify(path: Path, *, expect_version: Optional[str] = None) -> dict:
+    try:
+        env = json.loads(Path(path).read_text(encoding="utf-8"))
+    except Exception as e:
+        raise ManifestError(f"cannot read manifest: {type(e).__name__}")
+    return verify_manifest(env, expect_version=expect_version)
+
+
+def verify_wheel_file(path: Path, manifest: dict) -> None:
+    """Raise ManifestError unless the file is exactly the signed wheel."""
+    p = Path(path)
+    if not p.is_file():
+        raise ManifestError("wheel file missing")
+    if p.stat().st_size != manifest["size"]:
+        raise ManifestError("wheel size does not match the signed manifest")
+    if sha256_file(p) != manifest["sha256"]:
+        raise ManifestError("wheel sha256 does not match the signed manifest")

hyperclaw/updates/notices.py

@@ -0,0 +1,86 @@
+"""Owner notices: managed-update outcomes waiting to be shown.
+
+Appended to ``updates/notices.jsonl``; the next interactive start shows the
+unread ones once. Optionally also sent to the owner on Telegram.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import logging
+import os
+import urllib.request
+from typing import Callable, List, Optional
+
+from hyperclaw.updates.paths import read_json, updates_dir, write_json
+
+log = logging.getLogger("hyperclaw.updates")
+
+
+def _path():
+    return updates_dir() / "notices.jsonl"
+
+
+def _cursor_path():
+    return updates_dir() / "notices.read.json"
+
+
+def owner_chat_id() -> Optional[str]:
+    """The owner chat: TELEGRAM_OWNER_CHAT_ID (written by owner pairing),
+    else HYPERCLAW_OWNER_CHAT_ID, else the first TELEGRAM_CHAT_ID."""
+    cid = (os.environ.get("TELEGRAM_OWNER_CHAT_ID", "").strip()
+           or os.environ.get("HYPERCLAW_OWNER_CHAT_ID", "").strip())
+    if not cid:
+        cid = os.environ.get("TELEGRAM_CHAT_ID", "").split(",")[0].strip()
+    return cid or None
+
+
+def telegram_send(text: str) -> bool:
+    """Send to the owner chat if a bot token + chat are configured. The token
+    is part of the URL, so neither the URL nor the exception is logged."""
+    token = os.environ.get("TELEGRAM_BOT_TOKEN", "").strip()
+    chat = owner_chat_id()
+    if not token or not chat:
+        return False
+    body = json.dumps({"chat_id": chat, "text": text,
+                       "link_preview_options": {"is_disabled": True}}).encode()
+    try:
+        req = urllib.request.Request(f"https://api.telegram.org/bot{token}/sendMessage",
+                                     data=body, method="POST",
+                                     headers={"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=10) as r:  # noqa: S310
+            return 200 <= r.status < 300
+    except Exception:
+        log.warning("update notice: Telegram send failed (notice kept for next start)")
+        return False
+
+
+def notify(text: str, *, sender: Optional[Callable[[str], bool]] = telegram_send) -> None:
+    p = _path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    row = {"at": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"), "text": text}
+    with open(p, "a", encoding="utf-8") as f:
+        f.write(json.dumps(row) + "\n")
+    log.warning("update notice: %s", text)
+    if sender is not None:
+        try:
+            sender(text)
+        except Exception:
+            pass
+
+
+def unread(mark_read: bool = True) -> List[str]:
+    p = _path()
+    if not p.exists():
+        return []
+    lines = p.read_text(encoding="utf-8").splitlines()
+    seen = int(read_json(_cursor_path(), {}).get("lines", 0))
+    out = []
+    for line in lines[seen:]:
+        try:
+            out.append(json.loads(line)["text"])
+        except Exception:
+            continue
+    if mark_read and len(lines) != seen:
+        write_json(_cursor_path(), {"lines": len(lines)})
+    return out

hyperclaw/updates/paths.py

@@ -0,0 +1,53 @@
+"""Where the updater keeps its files: ``$HYPERCLAW_ROOT/updates/`` only.
+Config and ``.env`` are never written by anything in this package."""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+OPT_OUT_ENV = "HYPERCLAW_NO_UPDATE_CHECK"
+
+
+def opted_out() -> bool:
+    return os.environ.get(OPT_OUT_ENV, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def updates_dir() -> Path:
+    from hyperclaw.userconfig import root
+    return root() / "updates"
+
+
+def releases_dir() -> Path:
+    return updates_dir() / "releases"
+
+
+def read_json(path: Path, default):
+    try:
+        return json.loads(Path(path).read_text(encoding="utf-8"))
+    except Exception:
+        return default
+
+
+def write_json(path: Path, data) -> None:
+    """Atomic write (a daemon thread may be cut off at process exit)."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=path.name, suffix=".tmp", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+            f.write("\n")
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def current_version() -> str:
+    from hyperclaw import __version__
+    return __version__

hyperclaw/updates/release.py

@@ -0,0 +1,146 @@
+"""Maintainer command: sign a release manifest for a built wheel.
+
+    python -m hyperclaw.updates.release sign WHEEL --notes NOTES.md \\
+        --min-upgrade-from 1.2.3rc3 [--out DIR]
+    python -m hyperclaw.updates.release verify MANIFEST [--wheel WHEEL]
+
+The private key is read from the macOS keychain (the same item as
+qualification signing, ``hc-qual-signing-key``) and is never printed or
+logged. Mock inputs are refused, and so is a key that is not one of the
+package's shipped trusted keys (the result could never verify on a client).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import zipfile
+from email.parser import Parser
+from pathlib import Path
+
+from hyperclaw.updates import manifest as _m
+from hyperclaw.updates import versioning
+
+_PLACEHOLDER = re.compile(r"\b(mock|tbd|lorem|placeholder)\b", re.IGNORECASE)
+
+
+class Refused(Exception):
+    pass
+
+
+def inspect_wheel(path: Path) -> str:
+    """Return the wheel's version after checking it is a real HyperClaw wheel."""
+    p = Path(path)
+    if not p.is_file() or p.suffix != ".whl":
+        raise Refused(f"not a wheel file: {p.name}")
+    fv = _m.wheel_version(p.name)
+    if not p.name.startswith(_m.PACKAGE + "-") or fv is None:
+        raise Refused(f"not a {_m.PACKAGE} wheel: {p.name}")
+    try:
+        with zipfile.ZipFile(p) as z:
+            names = z.namelist()
+            meta = [n for n in names if n.endswith(".dist-info/METADATA")]
+            rec = [n for n in names if n.endswith(".dist-info/RECORD")]
+            if len(meta) != 1 or len(rec) != 1:
+                raise Refused("wheel has no single dist-info METADATA/RECORD (not a built wheel)")
+            md = Parser().parsestr(z.read(meta[0]).decode("utf-8", "replace"))
+            if not any(n.startswith("hyperclaw/") for n in names):
+                raise Refused("wheel does not contain the hyperclaw package")
+    except zipfile.BadZipFile:
+        raise Refused("wheel is not a valid zip archive")
+    name = (md.get("Name") or "").strip().lower().replace("_", "-")
+    version = (md.get("Version") or "").strip()
+    if name != _m.PACKAGE:
+        raise Refused(f"wheel metadata names {name!r}, not {_m.PACKAGE!r}")
+    v = versioning.parse(version)
+    if v is None:
+        raise Refused(f"wheel version {version!r} is not a valid version")
+    if v.local or "mock" in version.lower() or "mock" in p.name.lower():
+        raise Refused(f"wheel version {version!r} is a local/mock build")
+    if versioning.parse(fv) != v:
+        raise Refused(f"filename version {fv} does not match metadata version {version}")
+    return str(v)
+
+
+def build_signed(wheel: Path, notes: str, min_upgrade_from: str, private_raw: bytes) -> dict:
+    version = inspect_wheel(wheel)
+    notes = (notes or "").strip()
+    if len(notes) < 10 or _PLACEHOLDER.search(notes):
+        raise Refused("release notes are empty or placeholder text")
+    mn = versioning.parse(min_upgrade_from)
+    if mn is None or mn.local or mn > versioning.parse(version):
+        raise Refused(f"--min-upgrade-from {min_upgrade_from!r} is invalid for {version}")
+    m = _m.make_manifest(version=version, wheel=Path(wheel).name,
+                         sha256=_m.sha256_file(Path(wheel)), size=Path(wheel).stat().st_size,
+                         release_notes=notes, min_upgrade_from=str(mn))
+    env = _m.sign_manifest(m, private_raw)
+    try:
+        _m.verify_manifest(env, expect_version=version)
+    except _m.ManifestError as e:
+        raise Refused(f"signed manifest does not verify with the shipped keys ({e})")
+    _m.verify_wheel_file(Path(wheel), env["manifest"])
+    return env
+
+
+def _keychain_key() -> bytes:
+    from hyperclaw.qualification import keychain_private_key
+    return keychain_private_key()
+
+
+def sign_main(argv=None, *, private_key_loader=_keychain_key) -> int:
+    ap = argparse.ArgumentParser(prog="python -m hyperclaw.updates.release sign",
+                                 description="Write a Hyper-signed release manifest for a "
+                                             "built wheel (maintainers only).")
+    ap.add_argument("wheel", type=Path)
+    ap.add_argument("--notes", type=Path, required=True, help="release notes file")
+    ap.add_argument("--min-upgrade-from", required=True)
+    ap.add_argument("--out", type=Path, default=Path("dist"))
+    a = ap.parse_args(argv)
+    try:
+        notes = a.notes.read_text(encoding="utf-8")
+        inspect_wheel(a.wheel)               # refuse before touching the keychain
+        env = build_signed(a.wheel, notes, a.min_upgrade_from, private_key_loader())
+    except Refused as e:
+        print(f"refused: {e}", file=sys.stderr)
+        return 2
+    except OSError as e:
+        print(f"refused: {e.__class__.__name__}: {e.filename}", file=sys.stderr)
+        return 2
+    m = env["manifest"]
+    a.out.mkdir(parents=True, exist_ok=True)
+    out = a.out / _m.manifest_filename(m["version"])
+    out.write_text(json.dumps(env, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(f"signed {m['wheel']} sha256 {m['sha256']} -> {out} (key {m['key_id']})")
+    return 0
+
+
+def verify_main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="python -m hyperclaw.updates.release verify")
+    ap.add_argument("manifest", type=Path)
+    ap.add_argument("--wheel", type=Path)
+    a = ap.parse_args(argv)
+    try:
+        m = _m.load_and_verify(a.manifest)
+        if a.wheel:
+            _m.verify_wheel_file(a.wheel, m)
+    except _m.ManifestError as e:
+        print(f"INVALID: {e}", file=sys.stderr)
+        return 1
+    print(f"VALID {m['version']} {m['wheel']} (key {m['key_id']})"
+          + (" + wheel sha256 matches" if a.wheel else ""))
+    return 0
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv[:1] == ["sign"]:
+        return sign_main(argv[1:])
+    if argv[:1] == ["verify"]:
+        return verify_main(argv[1:])
+    print(__doc__, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())