hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/qualification.py

@@ -0,0 +1,341 @@
+"""Tool-use qualification records — signed by Hyper (spec §11 + cross-cutting
+rule 3; CEO rulings 2026-10-03).
+
+A provider earns ``tool_use`` only by passing the qualification suite — the
+same rule for HyperSpeed V2 and for a customer's own provider. models.yaml
+may *declare* tool_use; it is *granted* only when a **Hyper-signed** record
+for that exact provider + model exists and says QUALIFIED. Otherwise the
+model is chat-only. There is no grace period: a model without a valid signed
+record has no tools.
+
+Record file (one per provider+model, e.g. ``anthropic--claude-sonnet-5-5.json``)::
+
+    {"record": {"provider": "anthropic", "model": "claude-sonnet-5-5",
+                "verdict": "QUALIFIED",          # or NOT_QUALIFIED
+                "suite_version": "...", "benchmark_run_id": "...",
+                "harness": "<harness sha/version>",
+                "hyperclaw_version": "1.2.3rc2",
+                "issued_at": "2026-10-03T20:00:00Z",
+                "expires_at": "2027-10-03T00:00:00Z",   # optional
+                "key_id": "<issuer key id>"},
+     "signature": "<base64 Ed25519 signature over canonical(record)>"}
+
+``canonical(record)`` is ``json.dumps(record, sort_keys=True,
+separators=(",", ":"), ensure_ascii=False).encode("utf-8")``. The signature
+is detached from the payload: it covers the record object only.
+
+Verification uses Hyper's public key(s) shipped in the package
+(``hyperclaw/qualification_keys/<key_id>.pub``, base64 raw Ed25519 key),
+selected by the record's ``key_id``. Unsigned, bad-signature, unknown-key,
+malformed or expired records are IGNORED (logged once) and the model stays
+chat-only.
+
+Locations: the package (``hyperclaw/qualification_records/``, which Hyper
+ships when a model passes) and the install (``$HYPERCLAW_ROOT/qualification/``,
+default ``~/.hyperclaw/qualification/``). Both must verify. A Hyper-deployed
+install honours packaged records only. The provider and model *inside* the
+signed record must match; the filename alone proves nothing.
+
+Signing (maintainers only): ``hyperclaw-sign-qualification`` /
+``python -m hyperclaw.qualification sign`` reads the private key from the
+macOS keychain (generic password, service ``hc-qual-signing-key``, account
+``hyper``) and writes a signed record from a benchmark ``results-v2.json``.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import datetime as _dt
+import hashlib
+import json
+import logging
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+log = logging.getLogger("hyperclaw.qualification")
+
+QUALIFIED = "QUALIFIED"
+NOT_QUALIFIED = "NOT_QUALIFIED"
+VERDICTS = (QUALIFIED, NOT_QUALIFIED)
+RECORD_FIELDS_REQUIRED = ("provider", "model", "verdict", "suite_version",
+                          "benchmark_run_id", "harness", "hyperclaw_version",
+                          "issued_at", "key_id")
+
+_PKG = Path(__file__).resolve().parent
+PACKAGED_DIR = _PKG / "qualification_records"
+KEYS_DIR = _PKG / "qualification_keys"
+
+KEYCHAIN_SERVICE = "hc-qual-signing-key"
+KEYCHAIN_ACCOUNT = "hyper"
+
+# Extra trusted public keys {key_id: raw 32-byte key}. Empty in production;
+# the unit tests add a throwaway test key here (never the production key).
+EXTRA_TRUSTED_KEYS: dict = {}
+
+_logged: set = set()
+
+
+# ───────────────────────── helpers ─────────────────────────
+
+def _slug(model: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]+", "_", model or "").strip("_") or "default"
+
+
+def record_filename(provider: str, model: str) -> str:
+    return f"{_slug(provider)}--{_slug(model)}.json"
+
+
+def user_dir() -> Path:
+    from hyperclaw.userconfig import root
+    return root() / "qualification"
+
+
+def _dirs() -> list:
+    from hyperclaw.deployment import is_hyper
+    return [PACKAGED_DIR] if is_hyper() else [PACKAGED_DIR, user_dir()]
+
+
+def canonical(record: dict) -> bytes:
+    return json.dumps(record, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False).encode("utf-8")
+
+
+def key_id_for(public_raw: bytes) -> str:
+    """Key id = 'hyper-' + first 16 hex chars of sha256(raw public key)."""
+    return "hyper-" + hashlib.sha256(public_raw).hexdigest()[:16]
+
+
+def _now() -> _dt.datetime:
+    return _dt.datetime.now(_dt.timezone.utc)
+
+
+def _parse_ts(s: str) -> _dt.datetime:
+    t = _dt.datetime.fromisoformat(str(s).replace("Z", "+00:00"))
+    return t if t.tzinfo else t.replace(tzinfo=_dt.timezone.utc)
+
+
+def _log_once(path: Path, reason: str) -> None:
+    k = (str(path), reason)
+    if k not in _logged:
+        _logged.add(k)
+        log.warning("qualification record ignored (%s): %s — model stays chat-only",
+                    reason, path)
+
+
+def trusted_keys() -> dict:
+    """{key_id: raw public key bytes} from the package (+ EXTRA_TRUSTED_KEYS)."""
+    keys: dict = {}
+    try:
+        for p in sorted(KEYS_DIR.glob("*.pub")):
+            try:
+                raw = base64.b64decode(p.read_text(encoding="utf-8").strip(), validate=True)
+            except Exception:
+                continue
+            if len(raw) == 32 and key_id_for(raw) == p.stem:
+                keys[p.stem] = raw
+    except Exception:
+        pass
+    keys.update(EXTRA_TRUSTED_KEYS)
+    return keys
+
+
+# ───────────────────────── verification ─────────────────────────
+
+def verify_envelope(env, path: Path = Path("<memory>")) -> Optional[dict]:
+    """Return the verified record, or None (and log once why it was ignored)."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    if not isinstance(env, dict) or not isinstance(env.get("record"), dict):
+        _log_once(path, "unsigned or malformed")
+        return None
+    rec, sig = env["record"], env.get("signature")
+    if not isinstance(sig, str) or not sig:
+        _log_once(path, "unsigned")
+        return None
+    if any(not rec.get(f) for f in RECORD_FIELDS_REQUIRED) or rec.get("verdict") not in VERDICTS:
+        _log_once(path, "missing fields")
+        return None
+    raw = trusted_keys().get(rec.get("key_id"))
+    if raw is None:
+        _log_once(path, "unknown key")
+        return None
+    try:
+        Ed25519PublicKey.from_public_bytes(raw).verify(base64.b64decode(sig, validate=True),
+                                                      canonical(rec))
+    except (InvalidSignature, ValueError, TypeError):
+        _log_once(path, "bad signature")
+        return None
+    if rec.get("expires_at"):
+        try:
+            if _now() >= _parse_ts(rec["expires_at"]):
+                _log_once(path, "expired")
+                return None
+        except Exception:
+            _log_once(path, "bad expires_at")
+            return None
+    return rec
+
+
+def find_record(provider: str, model: str) -> Optional[dict]:
+    """The first *verified* record for this exact provider + model, or None."""
+    if not provider or not model:
+        return None
+    name = record_filename(provider, model)
+    for d in _dirs():
+        p = d / name
+        try:
+            if not p.is_file():
+                continue
+            env = json.loads(p.read_text(encoding="utf-8"))
+        except Exception:
+            _log_once(p, "unreadable")
+            continue
+        rec = verify_envelope(env, p)
+        if rec and rec.get("provider") == provider and rec.get("model") == model:
+            return rec
+        if rec:
+            _log_once(p, "provider/model mismatch")
+    return None
+
+
+def is_qualified(provider: str, model: str) -> bool:
+    rec = find_record(provider, model)
+    return bool(rec) and rec.get("verdict") == QUALIFIED
+
+
+def status_label(provider: str, model: str) -> str:
+    """'tools (qualified)' or 'chat-only (not qualified for tools)'."""
+    return ("tools (qualified)" if is_qualified(provider, model)
+            else "chat-only (not qualified for tools)")
+
+
+# ───────────────────────── signing ─────────────────────────
+
+def _private_key(private_raw: bytes):
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    return Ed25519PrivateKey.from_private_bytes(private_raw)
+
+
+def _public_raw(private_raw: bytes) -> bytes:
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+    return _private_key(private_raw).public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+
+
+def sign_record(record: dict, private_raw: bytes) -> dict:
+    """Return the signed envelope. ``key_id`` is set from the key."""
+    rec = dict(record)
+    rec["key_id"] = key_id_for(_public_raw(private_raw))
+    if rec.get("verdict") not in VERDICTS:
+        raise ValueError(f"verdict must be one of {VERDICTS}")
+    sig = _private_key(private_raw).sign(canonical(rec))
+    return {"record": rec, "signature": base64.b64encode(sig).decode("ascii")}
+
+
+def make_record(provider: str, model: str, verdict: str, *, suite_version: str,
+                benchmark_run_id: str, harness: str, expires_at: Optional[str] = None,
+                hyperclaw_version: Optional[str] = None) -> dict:
+    if hyperclaw_version is None:
+        from hyperclaw import __version__ as hyperclaw_version
+    rec = {"provider": provider, "model": model, "verdict": verdict,
+           "suite_version": suite_version, "benchmark_run_id": benchmark_run_id,
+           "harness": harness, "hyperclaw_version": hyperclaw_version,
+           "issued_at": _now().replace(microsecond=0).isoformat().replace("+00:00", "Z")}
+    if expires_at:
+        rec["expires_at"] = expires_at
+    return rec
+
+
+def write_envelope(env: dict, directory: Path) -> Path:
+    directory.mkdir(parents=True, exist_ok=True)
+    rec = env["record"]
+    p = directory / record_filename(rec["provider"], rec["model"])
+    p.write_text(json.dumps(env, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return p
+
+
+def verdict_from_results(results: dict) -> str:
+    """QUALIFIED only if the results file's qualification verdict says so."""
+    q = results.get("qualification") if isinstance(results, dict) else None
+    if (isinstance(q, dict) and q.get("qualified") is True
+            and str(q.get("line", "")).startswith(QUALIFIED) and not q.get("reasons")):
+        return QUALIFIED
+    return NOT_QUALIFIED
+
+
+def keychain_private_key() -> bytes:
+    """Read the signing key from the macOS keychain. Never printed or logged."""
+    out = subprocess.run(["security", "find-generic-password", "-s", KEYCHAIN_SERVICE,
+                          "-a", KEYCHAIN_ACCOUNT, "-w"],
+                         capture_output=True, text=True, check=False)
+    if out.returncode != 0 or not out.stdout.strip():
+        raise SystemExit(f"signing key not found in keychain (service {KEYCHAIN_SERVICE!r}, "
+                         f"account {KEYCHAIN_ACCOUNT!r})")
+    raw = base64.b64decode(out.stdout.strip())
+    if len(raw) != 32:
+        raise SystemExit("keychain item is not a raw Ed25519 private key")
+    return raw
+
+
+def sign_main(argv=None, *, private_key_loader=keychain_private_key) -> int:
+    ap = argparse.ArgumentParser(
+        prog="hyperclaw-sign-qualification",
+        description="Write a Hyper-signed qualification record from a benchmark "
+                    "results-v2.json (maintainers only; key from the macOS keychain).")
+    ap.add_argument("results", type=Path, help="benchmark results-v2.json")
+    ap.add_argument("--provider", required=True, help="HyperClaw provider id, e.g. anthropic")
+    ap.add_argument("--model", required=True, help="exact model id HyperClaw sends")
+    ap.add_argument("--suite-version", help="default: results.suite_version")
+    ap.add_argument("--harness", help="harness sha/version; default: results.harness_sha "
+                                      "or results.source_commit")
+    ap.add_argument("--expires-at", help="optional ISO-8601 expiry")
+    ap.add_argument("--out", type=Path, default=PACKAGED_DIR,
+                    help=f"output directory (default: the package, {PACKAGED_DIR})")
+    a = ap.parse_args(argv)
+
+    results = json.loads(a.results.read_text(encoding="utf-8"))
+    model_info = results.get("model") if isinstance(results.get("model"), dict) else {}
+    if model_info.get("production") is False:
+        print("refused: results come from a non-production (mock) run", file=sys.stderr)
+        return 2
+    run_id = str(results.get("run_id") or "").strip()
+    suite = a.suite_version or str(results.get("suite_version") or "").strip()
+    harness = a.harness or str(results.get("harness_sha") or results.get("source_commit")
+                               or "").strip()
+    missing = [n for n, v in (("run_id", run_id), ("--suite-version", suite),
+                              ("--harness", harness)) if not v]
+    if missing:
+        print(f"refused: missing {', '.join(missing)}", file=sys.stderr)
+        return 2
+    verdict = verdict_from_results(results)
+    rec = make_record(a.provider, a.model, verdict, suite_version=suite,
+                      benchmark_run_id=run_id, harness=harness, expires_at=a.expires_at)
+    env = sign_record(rec, private_key_loader())
+    if verify_envelope(env) is None:
+        print("refused: signing key is not one of the package's trusted keys", file=sys.stderr)
+        return 3
+    p = write_envelope(env, a.out)
+    print(f"{verdict}: {a.provider}/{a.model} -> {p} (key {env['record']['key_id']})")
+    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"] and len(argv) == 2:
+        p = Path(argv[1])
+        rec = verify_envelope(json.loads(p.read_text(encoding="utf-8")), p)
+        print("VALID " + rec["verdict"] if rec else "IGNORED (see warning)")
+        return 0 if rec else 1
+    print("usage: python -m hyperclaw.qualification sign RESULTS --provider P --model M ...\n"
+          "       python -m hyperclaw.qualification verify RECORD.json", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    logging.basicConfig()
+    raise SystemExit(main())

hyperclaw/qualification_keys/hyper-d292fd127cef5a3e.pub

@@ -0,0 +1 @@
+HAMPPhfeVAwcXSgTBJDz4gLJ5x8KUP5weURs4WDR9ig=

hyperclaw/qualification_records/anthropic--claude-sonnet-5-5.json

@@ -0,0 +1,14 @@
+{
+  "record": {
+    "benchmark_run_id": "20261013-205229-hc1.2.3rc4.post2-anthropic-claude-sonnet-5-5",
+    "harness": "anthropic-qual-2026-10-03b",
+    "hyperclaw_version": "1.2.3rc4.post2",
+    "issued_at": "2026-10-14T03:54:09Z",
+    "key_id": "hyper-d292fd127cef5a3e",
+    "model": "claude-sonnet-5-5",
+    "provider": "anthropic",
+    "suite_version": "hc-qual-13@235d29339fd8",
+    "verdict": "QUALIFIED"
+  },
+  "signature": "LoBWMZtwy1R1ieowq/OfPqHLqL/ZdvtkZW98iT509JIYrDeEFOpZ/nhOnbpZGdTzehu9tXgGBiG1pqGDnXSbAw=="
+}

hyperclaw/reasoning_display.py

@@ -0,0 +1,35 @@
+"""Whether raw model reasoning may be shown to a person.
+
+Vaughn P1 (2026-10-07): raw reasoning can leak internal instruction wording,
+so until a reasoning filter lands it is OFF by default on every surface (the
+Telegram 💭 preview, the dashboard reasoning stream) and FORCED OFF on a
+Hyper-deployed install (HYPERCLAW_DEPLOYMENT=hyper). An owner on a standard
+install may opt in explicitly:
+
+    HYPERCLAW_SHOW_REASONING=1        every surface
+    TELEGRAM_SHOW_THINKING=1          Telegram preview only (older setting)
+
+Reasoning is still CLASSIFIED (hyperclaw.oai_stream) so it never becomes the
+answer; this only decides whether it is displayed.
+"""
+import os
+
+_TRUE = ("1", "true", "yes", "on")
+
+
+def _flag(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in _TRUE
+
+
+def show_reasoning(surface: str = "") -> bool:
+    from hyperclaw.deployment import is_hyper
+    try:
+        if is_hyper():
+            return False
+    except Exception:
+        return False          # deployment unknown: fail closed
+    if _flag("HYPERCLAW_SHOW_REASONING"):
+        return True
+    if surface == "telegram" and _flag("TELEGRAM_SHOW_THINKING"):
+        return True
+    return False