hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/terminal_provider.py

@@ -0,0 +1,323 @@
+"""Resolve terminal credentials without changing the environment or saved settings."""
+from __future__ import annotations
+
+import os
+from typing import Mapping
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TerminalConfigurationError(ValueError):
+    """An actionable configuration problem that must be caught before an API call."""
+
+
+class TerminalProvider(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    kind: str = "openai_compat"     # "anthropic" (Messages API) or "openai_compat"
+    api_key: str = Field(repr=False)
+    model: str
+    base_url: str | None = None
+    label: str = ""                 # banner label of the matching registry provider
+
+    @property
+    def display_label(self) -> str:
+        if self.label:
+            return self.label
+        # Customer providers only: Hyper models always carry their own label.
+        try:
+            from hyperclaw.provider_setup import OWN_KINDS
+            name = OWN_KINDS.get(self.name, self.name)
+        except Exception:  # noqa: BLE001 -- a label must never break startup
+            name = self.name
+        return f"your own provider ({name})"
+
+
+def _is_hyper_endpoint(prefix: str, base_url: str, env: Mapping[str, str]) -> bool:
+    """True when the resolved OpenAI-compatible group is Hyper's own model:
+    the HYPERSPEED_* group, or any group pointing at the HyperSpeed endpoint."""
+    from hyperclaw import hyperspeed
+    if prefix == "HYPERSPEED":
+        return True
+    hyper_urls = {hyperspeed.DEFAULT_BASE_URL.rstrip("/"),
+                  (env.get(hyperspeed.BASE_URL_ENV, "") or "").strip().rstrip("/")} - {""}
+    return base_url.strip().rstrip("/") in hyper_urls
+
+
+def _hyper_label(base_url: str) -> str:
+    from hyperclaw import hyperspeed
+    if base_url.strip().rstrip("/") != hyperspeed.DEFAULT_BASE_URL.rstrip("/"):
+        return f"{hyperspeed.LABEL} (custom endpoint)"
+    return hyperspeed.LABEL
+
+
+def _validated_url(base_url: str) -> str:
+    try:
+        parsed = urlsplit(base_url)
+        valid = (parsed.scheme in ("http", "https") and parsed.hostname
+                 and not parsed.username and not parsed.password)
+        parsed.port  # Validate malformed ports before constructing an SDK client.
+    except ValueError:
+        valid = False
+    if not valid:
+        raise TerminalConfigurationError(
+            "The configured model URL must be an HTTP(S) URL without embedded credentials."
+        )
+    return base_url.rstrip("/")
+
+
+def resolve_terminal_provider(env: Mapping[str, str] | None = None) -> TerminalProvider:
+    env = os.environ if env is None else env
+
+    def value(name: str) -> str:
+        return env.get(name, "").strip()
+
+    # Keep each endpoint paired with its own credentials. An OpenAI key must
+    # never be combined with a different provider's URL as a field fallback.
+    openai_url = value("OPENAI_BASE_URL") or value("OPENAI_API_BASE")
+    hyperspeed_url = value("HYPERSPEED_BASE_URL")
+    name = value("LLM_PROVIDER")
+    if not name:
+        prefix = "OPENAI" if openai_url or not hyperspeed_url else "HYPERSPEED"
+        compatible_ready = (
+            (openai_url or hyperspeed_url) and value(f"{prefix}_API_KEY")
+            and (value(f"{prefix}_MODEL") or value("HYPERCLAW_MODEL"))
+        )
+        name = "openai_compat" if compatible_ready else "anthropic"
+
+    if name == "bedrock":
+        # Bedrock (a customer's own AWS provider, chat-only until qualified)
+        # is started by `hyperclaw start` itself, never through this resolver.
+        raise TerminalConfigurationError(
+            "Bedrock is not an endpoint this resolver can select. If an earlier "
+            "Hyperspeed outage selected Bedrock, restart with "
+            "LLM_PROVIDER=openai_compat hyperclaw start using your existing endpoint "
+            "and key. Saved settings have not been changed."
+        )
+
+    if name == "openai_compat":
+        prefix = "OPENAI" if openai_url or not hyperspeed_url else "HYPERSPEED"
+        base_url = openai_url if prefix == "OPENAI" else hyperspeed_url
+        api_key = value(f"{prefix}_API_KEY")
+        model = value(f"{prefix}_MODEL") or value("HYPERCLAW_MODEL")
+        if not base_url or not api_key or not model:
+            raise TerminalConfigurationError(
+                f"Configure {prefix}_BASE_URL, {prefix}_API_KEY and {prefix}_MODEL "
+                "for the same endpoint (OPENAI_API_BASE is also accepted). "
+                "Existing credentials have not been changed."
+            )
+        checked_url = _validated_url(base_url)
+        label = _hyper_label(checked_url) if _is_hyper_endpoint(prefix, checked_url, env) else ""
+        return TerminalProvider(name=name, kind="openai_compat", api_key=api_key, model=model,
+                                base_url=checked_url, label=label)
+
+    if name not in ("anthropic", "anthropic_compat"):
+        raise TerminalConfigurationError(
+            "Unsupported LLM_PROVIDER. Select openai_compat, anthropic or anthropic_compat."
+        )
+    api_key = value("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise TerminalConfigurationError("ANTHROPIC_API_KEY is not set for the selected provider.")
+    base_url = value("ANTHROPIC_BASE_URL")
+    if name == "anthropic_compat" and not base_url:
+        raise TerminalConfigurationError("ANTHROPIC_BASE_URL is required for anthropic_compat.")
+    return TerminalProvider(
+        name=name, kind="anthropic", api_key=api_key, model=value("HYPERCLAW_MODEL") or "claude-sonnet-4-6",
+        base_url=_validated_url(base_url) if base_url else None,
+    )
+
+
+# ───────────────────── terminal route (provider + tool gating) ─────────────────────
+#
+# Two contracts meet here:
+#   * terminal recovery (MR !1): an explicit LLM_PROVIDER is always honored,
+#     credentials are never mixed across endpoint groups, endpoints are
+#     validated before a client exists, Bedrock is refused with recovery text,
+#     and nothing rewrites saved settings.
+#   * truth guard (release 1.2.1/1.2.2/1.2.3): the terminal gets tools ONLY
+#     from a provider that declares ``tool_use`` in models.yaml AND holds a
+#     Hyper-signed qualification record; anything else runs chat-only, and
+#     nothing configured means refuse to run (fail closed). A Hyper install
+#     uses Hyper's providers only.
+
+
+def _same_url(a: str, b: str) -> bool:
+    return (a or "").strip().rstrip("/") == (b or "").strip().rstrip("/")
+
+
+def _declared_mode(registry, config: TerminalProvider) -> str:
+    """Tool gating for an explicitly selected provider: find the live
+    models.yaml provider that uses these exact credentials/endpoint and use
+    its declared capabilities. No match fails closed to chat-only."""
+    for prov in getattr(registry, "providers", {}).values():
+        if not prov.live or not prov.api_key or prov.api_key != config.api_key:
+            continue
+        if config.kind == "anthropic":
+            if prov.kind != "anthropic":
+                continue
+        else:
+            if prov.kind not in ("openai_compat", "openai"):
+                continue
+            if prov.base_url:
+                if not _same_url(prov.base_url, config.base_url or ""):
+                    continue
+            elif not (prov.kind == "openai"
+                      and urlsplit(config.base_url or "").hostname == "api.openai.com"):
+                continue
+        # Declared AND qualified (spec §11): tool_use is earned by a
+        # Hyper-signed qualification record, never by declaration alone.
+        caps = prov.effective_capabilities(config.model)
+        if "tool_use" in caps:
+            return "tools"
+        if "chat" in caps:
+            return "chat_only"
+    return "chat_only"
+
+
+def _registry_config(prov, model: str, env: Mapping[str, str]) -> TerminalProvider:
+    """TerminalProvider for a registry provider + model."""
+    kind = "anthropic" if prov.kind == "anthropic" else "openai_compat"
+    base_url = prov.base_url or None
+    if kind == "anthropic" and env.get("ANTHROPIC_BASE_URL", "").strip():
+        base_url = env.get("ANTHROPIC_BASE_URL", "").strip()
+    try:
+        from hyperclaw.model_policy import model_label
+        label = model_label(prov, model)
+    except Exception:  # noqa: BLE001 -- a label must never break routing
+        label = getattr(prov, "display_label", "") or ""
+    return TerminalProvider(
+        name=prov.name, kind=kind, api_key=prov.api_key, model=model,
+        base_url=_validated_url(base_url) if base_url else None,
+        label=label,
+    )
+
+
+REGISTRY_ONLY = ("xai", "openai")
+
+
+def _named_registry_route(registry, env: Mapping[str, str], hyper: bool):
+    """LLM_PROVIDER=xai / openai: those providers have no raw-env group in
+    resolve_terminal_provider, so they come from the registry (key from
+    .env, tools only once qualified). None when LLM_PROVIDER names another."""
+    name = env.get("LLM_PROVIDER", "").strip().lower()
+    if hyper or name not in REGISTRY_ONLY:
+        return None
+    prov = getattr(registry, "providers", {}).get(name)
+    if prov is None or not prov.live:
+        key = getattr(prov, "api_key_env", "") or f"{name.upper()}_API_KEY"
+        raise TerminalConfigurationError(
+            f"LLM_PROVIDER={name} is selected but {key} is not set. "
+            "Existing settings have not been changed.")
+    model = prov.model_for()
+    caps = prov.effective_capabilities(model)
+    return ("tools" if "tool_use" in caps else "chat_only"), \
+        _registry_config(prov, model, env), model
+
+
+def select_terminal_route(registry, env: Mapping[str, str] | None = None) -> tuple:
+    """Return ``(mode, TerminalProvider, model)`` for the terminal.
+
+    mode is "tools" or "chat_only"; ``(None, None, None)`` means nothing usable
+    is configured (caller must refuse to run). Raises
+    TerminalConfigurationError for an actionable configuration problem.
+
+    * A model chosen with /model this session (hyperclaw.model_catalog)
+      wins; its mode comes from its own declared + qualified capabilities.
+    * Hyper install (hyperclaw.deployment): registry only, LLM_PROVIDER and
+      raw env groups ignored; nothing live means (None, None, None).
+    * LLM_PROVIDER set: honored via resolve_terminal_provider(); tools only
+      if the matching models.yaml provider declares tool_use AND it is
+      qualified (Provider.effective_capabilities).
+    * LLM_PROVIDER=hyperspeed (written by onboarding): the registry's
+      HyperSpeed V2 provider; no Hyper access key raises a plain
+      missing-key error (never a switch to another provider).
+    * LLM_PROVIDER unset: truth_guard.route_chat() over the registry (tool-
+      capable provider first). If the registry finds nothing, a complete
+      OPENAI_*/HYPERSPEED_* group (incl. the legacy OPENAI_API_BASE alias) is
+      still accepted, chat-only unless declared otherwise.
+    """
+    from hyperclaw.deployment import is_hyper
+    from hyperclaw.truth_guard import route_chat
+
+    env = os.environ if env is None else env
+    hyper = is_hyper()
+    # /model (docs/MODEL-SWITCHING.md): a model chosen in this session wins.
+    # Tools only if that exact provider+model is declared AND qualified.
+    from hyperclaw.model_catalog import TERMINAL, selected_route
+    chosen = selected_route(registry, TERMINAL)
+    if chosen is not None:
+        prov, model = chosen
+        caps = prov.effective_capabilities(model)
+        mode = "tools" if "tool_use" in caps else "chat_only"
+        return mode, _registry_config(prov, model, env), model
+    # LLM_PROVIDER naming a registry-only provider (xai, openai) on a
+    # standard install: that provider, from the registry.
+    named = _named_registry_route(registry, env, hyper)
+    if named is not None:
+        return named
+    # A Hyper-deployed install runs on Hyper's providers only (spec §11):
+    # LLM_PROVIDER and raw OPENAI_*/ANTHROPIC_* keys are ignored there.
+    if hyper or not env.get("LLM_PROVIDER", "").strip():
+        mode, prov, model = route_chat(registry)
+        if mode is not None:
+            return mode, _registry_config(prov, model, env), model
+        if hyper:
+            return (None, None, None)
+        try:
+            config = resolve_terminal_provider(env)
+        except TerminalConfigurationError:
+            return (None, None, None)
+        return _declared_mode(registry, config), config, config.model
+
+    if env.get("LLM_PROVIDER", "").strip().lower() == HYPERSPEED:
+        return _hyperspeed_route(registry)
+
+    config = resolve_terminal_provider(env)
+    return _declared_mode(registry, config), config, config.model
+
+
+HYPERSPEED = "hyperspeed"
+HYPER_KEY_COMMAND = "hyperclaw provider hyper-key"
+SWITCH_TO_OWN_COMMAND = "hyperclaw provider remove hyperspeed"
+
+
+def hyper_key_missing_message(registry) -> str:
+    """What the terminal says when HyperSpeed V2 is selected
+    (LLM_PROVIDER=hyperspeed) but no Hyper access key is configured. Names
+    the fix, and an own provider that is already configured, without ever
+    switching to it."""
+    lines = [
+        "HyperSpeed V2 is selected (LLM_PROVIDER=hyperspeed in your .env), but your "
+        "Hyper access key is missing.",
+        f"Add it with:  {HYPER_KEY_COMMAND}",
+    ]
+    own = [p for p in getattr(registry, "providers", {}).values()
+           if getattr(p, "live", False) and getattr(p, "origin", "") != "hyper"]
+    if own:
+        labels = ", ".join(sorted({getattr(p, "display_label", "") or p.name for p in own}))
+        lines.append(
+            f"You also have {labels} configured. To use it instead of HyperSpeed V2, run:  "
+            f"{SWITCH_TO_OWN_COMMAND}  (this clears HyperSpeed V2 as your default; "
+            f"{HYPER_KEY_COMMAND} sets it back).")
+    lines.append("Nothing has been changed.")
+    return "\n".join(lines)
+
+
+def _hyperspeed_route(registry) -> tuple:
+    """LLM_PROVIDER=hyperspeed (what onboarding writes for HyperSpeed V2):
+    the registry's HyperSpeed V2 provider, tools only once qualified. No key
+    is an actionable error, never a silent switch to another provider."""
+    prov = getattr(registry, "providers", {}).get(HYPERSPEED)
+    if prov is None or not prov.live:
+        raise TerminalConfigurationError(hyper_key_missing_message(registry))
+    model = prov.model_for()
+    caps = prov.effective_capabilities(model)
+    mode = "tools" if "tool_use" in caps else "chat_only"
+    config = TerminalProvider(
+        name=prov.name, kind="openai_compat", api_key=prov.api_key, model=model,
+        base_url=_validated_url(prov.base_url) if prov.base_url else None,
+        label=getattr(prov, "display_label", "") or "",
+    )
+    return mode, config, model

hyperclaw/tools/__init__.py

@@ -0,0 +1 @@
+"""HyperClaw tool standard (TOOL-INVENTORY-2026-10-02 §3; docs/TOOL-STANDARD.md)."""