Merge pull request #5 from Floe-Labs/feat/hosted-enforcement

feat: wire hosted.py to the live credit-remaining endpoint

Author: achris7

README.md

@@ -153,9 +153,32 @@ Floe moves enforcement server-side against a real credit line:
 - **Cross-vendor** — one budget over LLM tokens *and* paid (x402) tool calls.
 - **Team budgets + analytics** — shared ceilings, per-agent isolation, spend history.
 
-Set `FLOE_API_KEY` and floe-guard exposes a hook to delegate enforcement to
-hosted Floe (see [`src/floe_guard/hosted.py`](src/floe_guard/hosted.py) — wiring
-the live endpoint is in progress; the local guard is fully functional today).
+Set `FLOE_API_KEY` (your agent key, `floe_<hex>`) and floe-guard can read your
+agent's **server-side remaining budget** from the live Floe endpoint:
+
+```python
+from floe_guard import hosted_enforcement_available, hosted_remaining_usd
+
+if hosted_enforcement_available():       # True when FLOE_API_KEY is set
+    remaining = hosted_remaining_usd()   # USD left, read from Floe's server
+```
+
+`hosted_remaining_usd()` GETs `/v1/agents/credit-remaining` and returns the USD
+remaining — the minimum of your auto-borrow headroom and your session spend
+remaining. It raises `HostedEnforcementError` on a bad/missing key (401), a
+closed or suspended agent (403), an unprovisioned agent (404), or a network
+failure.
+
+Env vars:
+
+- `FLOE_API_KEY` — your agent key. Required for the read.
+- `FLOE_API_BASE_URL` — override the API host (defaults to
+  `https://credit-api.floelabs.xyz`).
+
+Honest scope: this call only **reads** the remaining budget. The un-bypassable,
+cross-vendor *enforcement* is the hosted Floe product running server-side — not
+this client. Use the number to inform a local ceiling; the server stays the
+source of truth.
 
 → **[dev-dashboard.floelabs.xyz](https://dev-dashboard.floelabs.xyz)** ·
 **[floelabs.xyz](https://floelabs.xyz)**

src/floe_guard/__init__.py

@@ -16,10 +16,12 @@
 from .errors import (
     BudgetExceeded,
     FloeGuardError,
+    HostedEnforcementError,
     UnpriceableModelError,
     UnpriceableModelWarning,
 )
 from .guard import BudgetGuard
+from .hosted import hosted_enforcement_available, hosted_remaining_usd
 from .pricing import ManualPrice, PricedModel, price_tokens, resolve_price
 
 __version__ = "0.1.0"
@@ -28,10 +30,13 @@
     "BudgetGuard",
     "BudgetExceeded",
     "FloeGuardError",
+    "HostedEnforcementError",
     "UnpriceableModelError",
     "UnpriceableModelWarning",
     "ManualPrice",
     "PricedModel",
     "price_tokens",
     "resolve_price",
+    "hosted_enforcement_available",
+    "hosted_remaining_usd",
 ]

src/floe_guard/errors.py

@@ -43,6 +43,16 @@ def __init__(self, model: str) -> None:
         )
 
 
+class HostedEnforcementError(FloeGuardError):
+    """Raised when a read against the hosted Floe budget endpoint fails.
+
+    Covers a missing API key, a non-200 response (401 bad/missing key, 403 agent
+    closed/suspended, 404 agent not provisioned), a network/timeout failure, or a
+    malformed response body. The message states plainly what went wrong — this
+    client only *reads* server-side remaining budget; it does not enforce.
+    """
+
+
 class UnpriceableModelWarning(UserWarning):
     """Warned (loudly) whenever an unpriceable model is seen.
 

src/floe_guard/hosted.py

@@ -1,40 +1,166 @@
-"""Hosted Floe upgrade hook (stub — not wired to a live endpoint).
+"""Hosted Floe upgrade hook — reads server-side remaining budget.
 
 The local :class:`~floe_guard.BudgetGuard` is *estimate-based*: it prices tokens
 from a vendored cost map in your own process. A determined agent (or a bug) can
 run around it, and it only sees the one vendor you instrumented.
 
-Hosted Floe is the upgrade: enforcement moves server-side against a real credit
+Hosted Floe is the upgrade: enforcement lives server-side against a real credit
 line, so the ceiling is **un-bypassable** and spans **every vendor** (LLM tokens
 *and* paid x402 tool calls) under one budget, with team budgets and analytics.
 
-This module is intentionally a no-op stub. When ``FLOE_API_KEY`` is set,
-:func:`hosted_enforcement_available` reports it so callers can branch toward the
-hosted path. Wiring the actual delegation is tracked below — we do NOT ship a
-fabricated endpoint.
+This module is the read side of that upgrade. When ``FLOE_API_KEY`` is set,
+:func:`hosted_enforcement_available` reports it and :func:`hosted_remaining_usd`
+queries the live Floe endpoint for the agent's remaining server-side budget.
+
+Honest framing: this client only **reads** the remaining budget. The actual
+un-bypassable, cross-vendor *enforcement* is performed server-side by hosted Floe
+— not by this code. Use the returned number to inform a local ceiling; the
+server is the source of truth.
 
     Upgrade: https://dev-dashboard.floelabs.xyz  ·  https://floelabs.xyz
 """
 
 from __future__ import annotations
 
+import json
 import os
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .errors import HostedEnforcementError
 
 FLOE_API_KEY_ENV = "FLOE_API_KEY"
+FLOE_API_BASE_URL_ENV = "FLOE_API_BASE_URL"
+DEFAULT_BASE_URL = "https://credit-api.floelabs.xyz"
+CREDIT_REMAINING_PATH = "/v1/agents/credit-remaining"
+
+# USDC has 6 implied decimals; raw integer strings divide by this to get USD.
+_USDC_DECIMALS = 1_000_000
 
 
 def hosted_enforcement_available() -> bool:
     """True if a Floe API key is present in the environment.
 
-    Presence of a key is the signal that a caller *could* delegate enforcement to
-    hosted Floe. It does not itself perform any network call.
+    Presence of a key is the signal that a caller *could* read the hosted budget.
+    It does not itself perform any network call.
     """
     return bool(os.environ.get(FLOE_API_KEY_ENV, "").strip())
 
 
-# TODO(hosted-upgrade): when FLOE_API_KEY is set, delegate enforcement to hosted
-# Floe instead of (or alongside) the local estimate. The hosted path debits a
-# real, server-side credit line — un-bypassable and cross-vendor — so the budget
-# holds even if the local process is bypassed. This requires the public hosted
-# budget API to be finalized; until then this stays a documented no-op rather
-# than a fabricated endpoint. See README "Upgrade to hosted Floe".
+def hosted_remaining_usd(
+    api_key: str | None = None,
+    *,
+    base_url: str | None = None,
+    timeout: float = 10.0,
+) -> float:
+    """Read the agent's remaining server-side budget from hosted Floe, in USD.
+
+    GETs ``/v1/agents/credit-remaining`` with ``Authorization: Bearer <key>`` and
+    returns the remaining budget as a USD float. "Remaining" is the **minimum** of
+    ``headroomToAutoBorrow`` and (when present) ``sessionSpendRemaining`` — both
+    are raw USDC strings (6 decimals) divided by 1e6.
+
+    This is a *read* only. Enforcement still happens server-side in Floe.
+
+    Args:
+        api_key: agent key (``floe_<hex>``). Defaults to ``FLOE_API_KEY`` env var.
+        base_url: API base. Defaults to ``FLOE_API_BASE_URL`` env var, else the
+            production host.
+        timeout: socket timeout in seconds.
+
+    Raises:
+        HostedEnforcementError: missing key, non-200 (401/403/404 surfaced with
+            the server's ``error`` field), network/timeout, or malformed JSON.
+    """
+    key = (api_key or os.environ.get(FLOE_API_KEY_ENV, "")).strip()
+    if not key:
+        raise HostedEnforcementError(
+            f"No Floe API key: pass api_key= or set {FLOE_API_KEY_ENV}."
+        )
+
+    env_base = os.environ.get(FLOE_API_BASE_URL_ENV, "").strip()
+    base = ((base_url or "").strip() or env_base or DEFAULT_BASE_URL).rstrip("/")
+    parsed = urllib.parse.urlparse(base)
+    if parsed.scheme != "https" or not parsed.netloc:
+        # The request carries the Floe agent key as a bearer token — never send it
+        # over a non-https or malformed URL where it could leak to an arbitrary host.
+        raise HostedEnforcementError(
+            f"Refusing to send the Floe API key to {base!r}: "
+            "the base URL must be an https:// URL with a host."
+        )
+    url = f"{base}{CREDIT_REMAINING_PATH}"
+
+    request = urllib.request.Request(
+        url,
+        method="GET",
+        headers={"Authorization": f"Bearer {key}", "Accept": "application/json"},
+    )
+
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = response.read()
+    except urllib.error.HTTPError as exc:
+        raise HostedEnforcementError(_describe_http_error(exc)) from exc
+    except (urllib.error.URLError, TimeoutError, OSError, ValueError) as exc:
+        raise HostedEnforcementError(
+            f"Could not reach hosted Floe at {url}: {exc}"
+        ) from exc
+
+    try:
+        payload = json.loads(body)
+    except (ValueError, TypeError) as exc:
+        raise HostedEnforcementError(
+            f"Malformed JSON from hosted Floe at {url}: {exc}"
+        ) from exc
+
+    return _remaining_usd_from_payload(payload, url)
+
+
+def _remaining_usd_from_payload(payload: object, url: str) -> float:
+    if not isinstance(payload, dict):
+        raise HostedEnforcementError(
+            f"Unexpected response shape from hosted Floe at {url}: expected an object."
+        )
+
+    headroom = _usd_from_raw(payload.get("headroomToAutoBorrow"), "headroomToAutoBorrow", url)
+
+    session_raw = payload.get("sessionSpendRemaining")
+    if session_raw is None:
+        return headroom
+
+    session = _usd_from_raw(session_raw, "sessionSpendRemaining", url)
+    return min(headroom, session)
+
+
+def _usd_from_raw(value: object, field: str, url: str) -> float:
+    try:
+        return int(str(value)) / _USDC_DECIMALS
+    except (ValueError, TypeError) as exc:
+        raise HostedEnforcementError(
+            f"Invalid {field!r} ({value!r}) from hosted Floe at {url}: {exc}"
+        ) from exc
+
+
+def _describe_http_error(exc: urllib.error.HTTPError) -> str:
+    server_error = _server_error_field(exc)
+    detail = f" ({server_error})" if server_error else ""
+    if exc.code == 401:
+        return f"Hosted Floe rejected the API key (401 unauthorized){detail}."
+    if exc.code == 403:
+        return f"Hosted Floe agent is closed or suspended (403 forbidden){detail}."
+    if exc.code == 404:
+        return f"Hosted Floe agent has no credit limit / not provisioned (404){detail}."
+    return f"Hosted Floe returned HTTP {exc.code}{detail}."
+
+
+def _server_error_field(exc: urllib.error.HTTPError) -> str | None:
+    try:
+        data = json.loads(exc.read())
+    except Exception:
+        return None
+    if isinstance(data, dict):
+        value = data.get("error")
+        if isinstance(value, str):
+            return value
+    return None