hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/cost_guard.py

@@ -0,0 +1,1728 @@
+"""
+The cost guard (spec §9): daily and per-task caps on model spend, a spend
+line in answers, and a stop-and-ask at the cap with a summary built from
+evidence.
+
+One choke point. Every model call in the package goes through ``reserve``
+(before the request: check the caps and hold its estimated cost) and
+``record`` (after it: settle to the actual spend), by one of three adapters:
+
+- ``guard_client(client)`` wraps an Anthropic / OpenAI SDK client (sync or
+  async): ``messages.create``, ``messages.stream``, ``beta.messages.*`` and
+  ``chat.completions.create`` (streamed or not) are metered;
+- ``guard_provider_class(cls)`` wraps ``complete``/``stream`` of every
+  ``core.providers.llm.LLMProvider`` subclass (done by the base class);
+- ``metered(provider, model, request)`` is a context manager for the few
+  raw-HTTP calls.
+
+tests/unit/test_cost_guard.py scans the package and fails if a provider
+client or a raw model endpoint call is not behind one of these.
+
+At the cap the guard STOPS: ``preflight`` raises ``CostCapReached`` and no
+further model call runs for that task (per-task cap) or for the rest of the
+day (daily cap). It never picks a cheaper model and carries on. Callers turn
+the exception into a stop-and-ask message (``stop_message``) that says what
+was done (from the turn's tool results and the spend records), what remains,
+the spend against the cap, and asks whether to continue. Raising a cap is the
+user's explicit action (``raise_cap``: ``hyperclaw cost raise`` or ``/cost
+raise`` in the terminal) and is written to the activity log. Unattended and
+guest turns never see internal detail: the owner is notified instead.
+
+Settings (``config.json`` key ``cost_guard`` wins over the environment):
+
+    daily_cap_usd        HYPERCLAW_DAILY_CAP_USD (legacy DAILY_BUDGET_USD)   default 10.00
+    task_cap_usd         HYPERCLAW_TASK_CAP_USD                              default 2.00
+    spend_line_min_usd   HYPERCLAW_SPEND_LINE_MIN_USD                        default 0.01
+    prices               {"<model id>" | "provider:<name>":
+                          {"input_per_1k": USD, "output_per_1k": USD}}
+    max_output_tokens    {"<model id>" | "provider:<name>": tokens}
+                         (the model's real output maximum; see max_output_for)
+    max_reasoning_tokens {"<model id>" | "provider:<name>": tokens}
+                         (reasoning on top of the max output when thinking is
+                         on; HyperSpeed V2 8192; see reasoning_tokens_for)
+    max_output_tokens_per_path
+                         {"<path>": tokens}: the explicit max output every
+                         model call on that path sends (see max_output and
+                         DEFAULT_MAX_OUTPUT_PER_PATH)
+
+Prices: config ``prices`` > models.yaml ``models.<id>.cost_per_1k_*`` >
+the built-in table below (model families) > the built-in provider rate
+(HyperSpeed V2: a placeholder until Hyper sets its internal rate in config)
+> UNKNOWN_PRICE, a conservative rate (never 0).
+
+Spend is persisted per local day in SQLite at
+$HYPERCLAW_COST_DB or $HYPERCLAW_ROOT/ledger/cost.sqlite3, so caps survive
+restarts.
+
+Concurrency (review of !17): the cap check and a reservation of the call's
+estimated cost happen in ONE ``BEGIN IMMEDIATE`` transaction (``reserve``),
+so calls in flight at the same time count against the cap before any of
+them finishes. ``record`` settles the reservation to the actual spend; a
+call that failed before producing anything releases it. If settling fails,
+the reserved amount stays counted (never dropped). An unreadable ledger
+stops the task with a clear reason (scope ``ledger``); it never lets a call
+through unchecked.
+"""
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import functools
+import inspect
+import json
+import logging
+import os
+import sqlite3
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+log = logging.getLogger("hyperclaw.cost_guard")
+
+DEFAULT_DAILY_CAP_USD = 10.0
+DEFAULT_TASK_CAP_USD = 2.0
+DEFAULT_SPEND_LINE_MIN_USD = 0.01
+
+# USD per 1k tokens (input, output). Exact ids from models.yaml win; these are
+# the fallbacks, matched by longest prefix after stripping vendor prefixes.
+BUILTIN_PRICES: Dict[str, Tuple[float, float]] = {
+    "claude-fable": (0.010, 0.050),
+    "claude-opus-5": (0.005, 0.025),
+    "claude-opus": (0.015, 0.075),        # older Opus generations: the high rate
+    "claude-sonnet": (0.003, 0.015),
+    "claude-haiku": (0.001, 0.005),
+    "claude-3-haiku": (0.00025, 0.00125),
+    "gpt-4o-mini": (0.00015, 0.0006),
+    "gpt-4o": (0.0025, 0.010),
+    "llama-3.1-8b": (0.00005, 0.00008),
+}
+# Provider-level rates for models with no entry of their own.
+# HyperSpeed V2: PLACEHOLDER for Hyper's internal rate; a Hyper deployment
+# sets the real figure in config.json cost_guard.prices["provider:hyperspeed"].
+PROVIDER_PRICES: Dict[str, Tuple[float, float]] = {
+    "hyperspeed": (0.002, 0.008),
+}
+# Unknown model: a conservative (high) rate, never 0.
+UNKNOWN_PRICE: Tuple[float, float] = (0.015, 0.075)
+
+TASK = "task"
+DAILY = "daily"
+LEDGER = "ledger"        # the ledger can't be read: stop, never call unchecked
+
+# A call that sets no max output (no max_tokens / max_completion_tokens) is
+# reserved against the model's REAL output maximum, so a long generation can't
+# be under-reserved and let concurrent calls pass the cap (review of !27). The
+# reservation is settled to the actual usage when the call ends.
+#
+# Resolution (``max_output_for``): config ``cost_guard.max_output_tokens``
+# {"<model id>" | "provider:<name>": int} > models.yaml
+# ``models.<id>.max_output_tokens`` > models.yaml
+# ``providers.<name>.max_output_tokens`` (provider registry) > the built-in
+# table below (longest id prefix after stripping vendor prefixes) > the
+# built-in provider limit > UNKNOWN_MAX_OUTPUT_TOKENS (logged once per model).
+BUILTIN_MAX_OUTPUT: Dict[str, int] = {
+    # Anthropic (published output caps)
+    "claude-fable": 128000,
+    "claude-mythos": 128000,
+    "claude-opus-5": 128000,
+    "claude-sonnet-5": 128000,
+    "claude-opus-4-8": 128000,
+    "claude-opus-4-7": 128000,
+    "claude-opus-4-6": 128000,
+    "claude-sonnet-4-6": 128000,
+    "claude-opus-4-5": 64000,
+    "claude-sonnet-4-5": 64000,
+    "claude-haiku-4-5": 64000,
+    "claude-opus-4-1": 32000,
+    "claude-opus-4-0": 32000,
+    "claude-opus-4-2025": 32000,
+    "claude-sonnet-4-0": 64000,
+    "claude-sonnet-4-2025": 64000,
+    "claude-3-7-sonnet": 64000,
+    "claude-3-5-sonnet": 8192,
+    "claude-3-5-haiku": 8192,
+    "claude-3-opus": 4096,
+    "claude-3-haiku": 4096,
+    "claude-opus": 128000,             # other Opus / Sonnet / Haiku ids: the largest cap
+    "claude-sonnet": 128000,
+    "claude-haiku": 64000,
+    # OpenAI
+    "gpt-5": 128000,
+    "gpt-4.1": 32768,
+    "gpt-4o": 16384,
+    "o1": 100000,
+    "o3": 100000,
+    "o4": 100000,
+    # xAI: output is bounded by the context window, no separate published cap;
+    # reserve the same large figure as the biggest known caps.
+    "grok": 128000,
+    # Llama 3.1 8B (ChatJimmy)
+    "llama-3.1-8b": 8192,
+}
+# Provider-level limits for models with no entry of their own.
+# HyperSpeed V2 (vLLM): max output 16384 tokens (max-model-len 65536), as
+# documented by the V2 serving team on 13 Oct; not yet confirmed against a
+# live GET /v1/models. A Hyper deployment can set the exact figure in
+# models.yaml providers.hyperspeed.max_output_tokens or config.json
+# cost_guard.max_output_tokens["provider:hyperspeed"].
+PROVIDER_MAX_OUTPUT: Dict[str, int] = {
+    "hyperspeed": 16384,
+}
+# Reasoning tokens a provider can generate ON TOP of the max output when
+# thinking/reasoning is on for the call. HyperSpeed V2 reasons by default
+# (up to 8192 tokens, same source as above); a call that turns it off
+# (extra_body.chat_template_kwargs.enable_thinking = false) reserves none.
+# models.yaml providers.<name>.max_reasoning_tokens or config.json
+# cost_guard.max_reasoning_tokens {"<model id>" | "provider:<name>": int}
+# override it.
+PROVIDER_REASONING_TOKENS: Dict[str, int] = {
+    "hyperspeed": 8192,
+}
+# Unknown model: a conservative (large) output maximum, never a small guess.
+UNKNOWN_MAX_OUTPUT_TOKENS = 128000
+
+# ── every path sets its own max output (Vaughn, 13 Oct) ──
+# Every model call on every path passes an explicit max output, chosen per
+# path by ``max_output(path, provider, model)``, so no reservation is made
+# against a model's full output maximum (Opus 5.5 with no max would reserve
+# about $3.20, above the $2 per-task cap). The fallback above (reserve
+# against ``max_output_for`` when a call sets no max) stays for safety but is
+# unreachable from shipped paths: tests/unit/test_max_output_every_path.py
+# scans every call site, drives every path with fakes under
+# HYPERCLAW_REQUIRE_MAX_OUTPUT=1 (set for the whole test suite), and fails if
+# any call reaches the fallback.
+#
+# Settings: config.json ``cost_guard.max_output_tokens_per_path``
+# {"<path>": tokens} overrides the defaults below. Whatever is configured,
+# ``max_output`` never returns more than the model's real output maximum, nor
+# more than keeps (the path's input allowance + the max output) at the
+# model's price within the per-task cap.
+DEFAULT_MAX_OUTPUT_PER_PATH: Dict[str, int] = {
+    "terminal": 16000,          # tui.py chat turn on the Messages API (thinking + tools)
+    "terminal_openai": 4096,    # tui.py chat turn on OpenAI-schema providers (V2, OpenAI, xAI)
+    "telegram": 4096,           # solomon.py chat replies (Telegram, terminal chat-only)
+    "bridge": 8000,             # tui_bridge.py tool turns (Telegram owner / guest)
+    "chat": 4096,               # other chat replies (orchestrator, cli_tui, model clients)
+    "agent": 16000,             # agent.py tool loop
+    "specialist": 2048,         # team specialists (hyperclaw/team, one dispatcher)
+    "swarm_agent": 4096,        # legacy swarm agents (hyperclaw/swarm.py), via the dispatcher
+    "router": 4096,             # model_router calls (each model's own max_tokens, capped)
+    "provider": 4096,           # core.providers LLMProvider.complete/stream with no max given
+    "vision": 1024,             # image analysis (terminal vision tool, vision providers)
+    "search": 1024,             # LLM-answered web search (Perplexity)
+    "brief": 1200,              # daily brief (brief/compose.py)
+    "digest": 900,              # watcher digests (digest/summarize.py)
+    "memory": 4096,             # memory consolidation (prometheus.py)
+    "genesis": 2000,            # skills GENESIS discovery (skills.py)
+    "naming": 120,              # name suggestions (naming.py)
+    "connection_check": 1,      # V2 key check (connection_check.py): one token
+    "doctor": 8,                # `hyperclaw doctor` provider pings
+    "listener": 2000,           # legacy telegram_listener.py
+}
+# The largest prompt (in tokens) each path is expected to send. Used to keep
+# (input + max output) within the per-task cap: ``max_output`` caps the output
+# so that this input plus the output, at the model's price, fits the cap.
+INPUT_ALLOWANCE_PER_PATH: Dict[str, int] = {
+    "terminal": 40000, "terminal_openai": 40000, "telegram": 20000, "bridge": 40000,
+    "chat": 20000, "agent": 40000, "specialist": 20000, "swarm_agent": 20000, "router": 20000, "provider": 20000,
+    "vision": 4000, "search": 2000, "brief": 20000, "digest": 20000, "memory": 20000,
+    "genesis": 4000, "naming": 2000, "connection_check": 50, "doctor": 50, "listener": 20000,
+}
+DEFAULT_PATH = "chat"
+# Never cap a path's output below this (or below its own default, when that is
+# smaller) because of a very low per-task cap: an answer still has room.
+MIN_CAPPED_OUTPUT_TOKENS = 256
+REQUIRE_MAX_ENV = "HYPERCLAW_REQUIRE_MAX_OUTPUT"
+
+
+class MissingMaxOutput(RuntimeError):
+    """A metered model call set no max output while HYPERCLAW_REQUIRE_MAX_OUTPUT
+    is on (the test suite). Shipped paths never get here."""
+
+
+# ───────────────────────────── settings ─────────────────────────────
+
+def _cfg() -> dict:
+    try:
+        from hyperclaw.userconfig import load_config
+        c = load_config().get("cost_guard")
+        return c if isinstance(c, dict) else {}
+    except Exception:
+        return {}
+
+
+def _num(v) -> Optional[float]:
+    try:
+        f = float(v)
+    except (TypeError, ValueError):
+        return None
+    return f if f == f and f >= 0 else None   # not NaN, not negative
+
+
+def _setting(key: str, envs: Iterable[str], default: float) -> float:
+    v = _num(_cfg().get(key))
+    if v is not None:
+        return v
+    for e in envs:
+        v = _num(os.environ.get(e))
+        if v is not None:
+            return v
+    return default
+
+
+def daily_cap() -> float:
+    return _setting("daily_cap_usd", ("HYPERCLAW_DAILY_CAP_USD", "DAILY_BUDGET_USD"),
+                    DEFAULT_DAILY_CAP_USD)
+
+
+def task_cap() -> float:
+    return _setting("task_cap_usd", ("HYPERCLAW_TASK_CAP_USD",), DEFAULT_TASK_CAP_USD)
+
+
+def spend_line_min() -> float:
+    return _setting("spend_line_min_usd", ("HYPERCLAW_SPEND_LINE_MIN_USD",),
+                    DEFAULT_SPEND_LINE_MIN_USD)
+
+
+# ───────────────────────────── prices ─────────────────────────────
+
+def _price_entry(v) -> Optional[Tuple[float, float]]:
+    if isinstance(v, dict):
+        i = _num(v.get("input_per_1k", v.get("cost_per_1k_input")))
+        o = _num(v.get("output_per_1k", v.get("cost_per_1k_output")))
+        if i is not None and o is not None:
+            return (i, o)
+    return None
+
+
+_YAML_CACHE: Dict[str, Any] = {}
+
+
+def _yaml_prices() -> Dict[str, Tuple[float, float]]:
+    try:
+        import yaml
+        from hyperclaw.api_utils import find_config
+        p = find_config("models.yaml")
+        if not p.exists():
+            return {}
+        key = (str(p), p.stat().st_mtime_ns)
+        if _YAML_CACHE.get("key") == key:
+            return _YAML_CACHE["prices"]
+        data = yaml.safe_load(p.read_text()) or {}
+    except Exception:
+        return {}
+    out = {}
+    for mid, entry in ((data or {}).get("models") or {}).items():
+        e = _price_entry(entry)
+        if e is not None:
+            out[str(mid)] = e
+    _YAML_CACHE.update(key=key, prices=out)
+    return out
+
+
+def _bare(model: str) -> str:
+    m = (model or "").strip().lower()
+    for pre in ("us.anthropic.", "eu.anthropic.", "apac.anthropic.", "anthropic.", "anthropic/",
+                "openai/", "meta-llama/"):
+        if m.startswith(pre):
+            m = m[len(pre):]
+    return m
+
+
+def price_for(provider: str, model: str) -> Tuple[float, float]:
+    """(input, output) USD per 1k tokens for this provider/model. Never (0, 0)
+    for an unknown model."""
+    cfg = _cfg().get("prices") or {}
+    if isinstance(cfg, dict):
+        for k in (model, f"provider:{provider}"):
+            e = _price_entry(cfg.get(k)) if k else None
+            if e is not None:
+                return e
+    yp = _yaml_prices()
+    if model in yp:
+        return yp[model]
+    bare = _bare(model)
+    best = ""
+    for k in BUILTIN_PRICES:
+        if bare.startswith(k) and len(k) > len(best):
+            best = k
+    if best:
+        return BUILTIN_PRICES[best]
+    if provider in PROVIDER_PRICES:
+        return PROVIDER_PRICES[provider]
+    return UNKNOWN_PRICE
+
+
+# ───────────────────────────── output maxima ─────────────────────────────
+
+def _pos_int(v) -> Optional[int]:
+    if isinstance(v, bool):
+        return None
+    try:
+        n = int(v)
+    except (TypeError, ValueError):
+        return None
+    return n if n > 0 else None
+
+
+def _yaml_limits() -> Tuple[Dict[str, int], Dict[str, int], Dict[str, int]]:
+    """(models.<id>.max_output_tokens, providers.<name>.max_output_tokens,
+    providers.<name>.max_reasoning_tokens) from models.yaml."""
+    try:
+        import yaml
+        from hyperclaw.api_utils import find_config
+        p = find_config("models.yaml")
+        if not p.exists():
+            return {}, {}, {}
+        key = (str(p), p.stat().st_mtime_ns)
+        if _YAML_MAX_CACHE.get("key") == key:
+            return (_YAML_MAX_CACHE["models"], _YAML_MAX_CACHE["providers"],
+                    _YAML_MAX_CACHE["reasoning"])
+        data = yaml.safe_load(p.read_text()) or {}
+    except Exception:
+        return {}, {}, {}
+    models, providers, reasoning = {}, {}, {}
+    for section, out in (("models", models), ("providers", providers)):
+        for name, entry in ((data or {}).get(section) or {}).items():
+            n = _pos_int(entry.get("max_output_tokens")) if isinstance(entry, dict) else None
+            if n is not None:
+                out[str(name)] = n
+    for name, entry in ((data or {}).get("providers") or {}).items():
+        if isinstance(entry, dict) and "max_reasoning_tokens" in entry:
+            v = entry.get("max_reasoning_tokens")
+            n = 0 if v in (0, "0") else _pos_int(v)
+            if n is not None:
+                reasoning[str(name)] = n
+    _YAML_MAX_CACHE.update(key=key, models=models, providers=providers, reasoning=reasoning)
+    return models, providers, reasoning
+
+
+def _yaml_max_outputs() -> Tuple[Dict[str, int], Dict[str, int]]:
+    """(models.<id>.max_output_tokens, providers.<name>.max_output_tokens)."""
+    m, p, _r = _yaml_limits()
+    return m, p
+
+
+def reasoning_tokens_for(provider: str, model: str) -> int:
+    """Reasoning tokens this provider/model can generate on top of the max
+    output when thinking is on for the call (0 when it has no separate
+    reasoning budget)."""
+    cfg = _cfg().get("max_reasoning_tokens") or {}
+    if isinstance(cfg, dict):
+        for k in (model, f"provider:{provider}"):
+            v = cfg.get(k) if k else None
+            if v in (0, "0"):
+                return 0
+            n = _pos_int(v)
+            if n is not None:
+                return n
+    yr = _yaml_limits()[2]
+    if provider in yr:
+        return yr[provider]
+    return PROVIDER_REASONING_TOKENS.get(provider or "", 0)
+
+
+def thinking_on(req: Any) -> bool:
+    """False when the request turns reasoning off (vLLM chat-template switch
+    ``enable_thinking: false``, in the body or in ``extra_body``); else True
+    (V2 reasons by default)."""
+    if not isinstance(req, dict):
+        return True
+    for d in (req, req.get("extra_body") if isinstance(req.get("extra_body"), dict) else {}):
+        ctk = d.get("chat_template_kwargs")
+        if isinstance(ctk, dict) and ctk.get("enable_thinking") is False:
+            return False
+    return True
+
+
+_YAML_MAX_CACHE: Dict[str, Any] = {}
+_UNKNOWN_MAX_LOGGED: set = set()
+_UNKNOWN_MAX_LOCK = threading.Lock()
+
+
+def max_output_for(provider: str, model: str) -> int:
+    """The model's real output maximum in tokens: what one call that sets no
+    max output can generate at most. Unknown → UNKNOWN_MAX_OUTPUT_TOKENS
+    (conservative), logged once per provider/model."""
+    n = _known_max_output(provider, model)
+    if n is not None:
+        return n
+    key = (provider or "", model or "")
+    with _UNKNOWN_MAX_LOCK:
+        first = key not in _UNKNOWN_MAX_LOGGED
+        _UNKNOWN_MAX_LOGGED.add(key)
+    if first:
+        log.warning("cost guard: no known output maximum for model %r (provider %r); "
+                    "reserving the conservative default of %d output tokens for calls "
+                    "that set no max", model or "", provider or "", UNKNOWN_MAX_OUTPUT_TOKENS)
+    return UNKNOWN_MAX_OUTPUT_TOKENS
+
+
+def _known_max_output(provider: str, model: str) -> Optional[int]:
+    """The model's real output maximum if any source knows it, else None."""
+    cfg = _cfg().get("max_output_tokens") or {}
+    if isinstance(cfg, dict):
+        for k in (model, f"provider:{provider}"):
+            n = _pos_int(cfg.get(k)) if k else None
+            if n is not None:
+                return n
+    ym, yp = _yaml_max_outputs()
+    if model in ym:
+        return ym[model]
+    bare = _bare(model)
+    best = ""
+    for k in BUILTIN_MAX_OUTPUT:
+        if bare.startswith(k) and len(k) > len(best):
+            best = k
+    if best:
+        return BUILTIN_MAX_OUTPUT[best]
+    if provider in yp:
+        return yp[provider]
+    if provider in PROVIDER_MAX_OUTPUT:
+        return PROVIDER_MAX_OUTPUT[provider]
+    return None
+
+
+def path_max_output(path: str) -> int:
+    """The configured (or default) max output for ``path``, before capping."""
+    cfg = _cfg().get("max_output_tokens_per_path") or {}
+    if isinstance(cfg, dict):
+        n = _pos_int(cfg.get(path))
+        if n is not None:
+            return n
+    if path in DEFAULT_MAX_OUTPUT_PER_PATH:
+        return DEFAULT_MAX_OUTPUT_PER_PATH[path]
+    log.warning("cost guard: unknown model-call path %r; using the %r max output", path,
+                DEFAULT_PATH)
+    return DEFAULT_MAX_OUTPUT_PER_PATH[DEFAULT_PATH]
+
+
+def max_output(path: str, provider: str = "", model: str = "",
+               requested: Optional[int] = None) -> int:
+    """The explicit max output (max_tokens / max_completion_tokens) for one
+    model call on ``path``: the path's setting (``requested`` replaces it when
+    a caller has its own figure, e.g. a router model's max_tokens), never
+    above the model's real output maximum, and never so large that the path's
+    input allowance plus this output, at the model's price, exceeds the
+    per-task cap. Every shipped model call passes this value."""
+    n = _pos_int(requested) or path_max_output(path)
+    real = _known_max_output(provider, model)
+    if real is not None:
+        n = min(n, real)
+    _pi, po = price_for(provider, model)
+    if po > 0:
+        pin = INPUT_ALLOWANCE_PER_PATH.get(path, INPUT_ALLOWANCE_PER_PATH[DEFAULT_PATH])
+        budget = (task_cap() - (pin / 1000.0) * _pi
+                  - (reasoning_tokens_for(provider, model) / 1000.0) * po)
+        fit = int(budget / po * 1000) if budget > 0 else 0
+        if fit < n:
+            n = max(fit, min(n, MIN_CAPPED_OUTPUT_TOKENS))
+    return max(1, n)
+
+
+def cost_of(provider: str, model: str, input_tokens: int, output_tokens: int) -> float:
+    pi, po = price_for(provider, model)
+    return (max(0, int(input_tokens)) / 1000.0) * pi + (max(0, int(output_tokens)) / 1000.0) * po
+
+
+def estimate_tokens(obj: Any) -> int:
+    """Rough token count (chars / 4) for a request or text when the provider
+    reports no usage. Inline base64 media count as ~1600 tokens each."""
+    def walk(o):
+        if o is None:
+            return 0
+        if isinstance(o, str):
+            return 1600 * 4 if len(o) > 20000 else len(o)
+        if isinstance(o, dict):
+            return sum(walk(v) for v in o.values())
+        if isinstance(o, (list, tuple)):
+            return sum(walk(v) for v in o)
+        return len(str(o))
+    return max(1, walk(obj) // 4)
+
+
+# ───────────────────────────── store ─────────────────────────────
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS spend (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts            REAL    NOT NULL,
+    day           TEXT    NOT NULL,
+    task_id       TEXT,
+    surface       TEXT,
+    provider      TEXT,
+    model         TEXT,
+    input_tokens  INTEGER NOT NULL,
+    output_tokens INTEGER NOT NULL,
+    cost_usd      REAL    NOT NULL,
+    estimated     INTEGER NOT NULL DEFAULT 0,
+    status        TEXT    NOT NULL DEFAULT 'settled'   -- 'reserved' while the call is in flight
+);
+CREATE INDEX IF NOT EXISTS spend_day ON spend (day);
+CREATE INDEX IF NOT EXISTS spend_task ON spend (task_id);
+CREATE TABLE IF NOT EXISTS owner_notices (
+    id        INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts        REAL NOT NULL,
+    day       TEXT NOT NULL,
+    dedupe    TEXT,
+    text      TEXT NOT NULL,
+    delivered INTEGER NOT NULL DEFAULT 0
+);
+CREATE UNIQUE INDEX IF NOT EXISTS owner_notices_dedupe ON owner_notices (dedupe);
+"""
+
+
+def default_path() -> Path:
+    explicit = os.environ.get("HYPERCLAW_COST_DB")
+    if explicit:
+        return Path(explicit).expanduser()
+    root = Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw")).expanduser()
+    return root / "ledger" / "cost.sqlite3"
+
+
+def today() -> str:
+    return time.strftime("%Y-%m-%d", time.localtime())
+
+
+class CostStore:
+    def __init__(self, path: Optional[os.PathLike] = None):
+        self.path = Path(path) if path else default_path()
+        self._lock = threading.Lock()
+        self._ready = False
+
+    def _connect(self) -> sqlite3.Connection:
+        created = False
+        if not self._ready:
+            with self._lock:
+                if not self._ready:
+                    self.path.parent.mkdir(parents=True, exist_ok=True)
+                    try:
+                        os.chmod(self.path.parent, 0o700)
+                    except OSError:
+                        pass
+                    created = not self.path.exists()
+                    con = sqlite3.connect(self.path, timeout=10, isolation_level=None)
+                    try:
+                        con.execute("PRAGMA journal_mode=WAL")
+                        con.executescript(_SCHEMA)
+                        cols = {r[1] for r in con.execute("PRAGMA table_info(spend)")}
+                        if "status" not in cols:   # ledger from before reservations
+                            con.execute("ALTER TABLE spend ADD COLUMN status TEXT NOT NULL "
+                                        "DEFAULT 'settled'")
+                    finally:
+                        con.close()
+                    try:
+                        os.chmod(self.path, 0o600)
+                    except OSError:
+                        pass
+                    self._ready = True
+            if created:
+                # A missing ledger means today's spend restarts at $0: never silently.
+                msg = (f"A new cost ledger was created at {self.path}; spend recorded before "
+                       f"this point (if any) is not counted against today's cap.")
+                log.warning("cost guard: %s", msg)
+                _activity("cost_guard", "cost_ledger", "ok", msg)
+            else:
+                log.info("cost guard: cost ledger opened at %s", self.path)
+        con = sqlite3.connect(self.path, timeout=10, isolation_level=None)
+        con.row_factory = sqlite3.Row
+        return con
+
+    def add(self, *, task_id: Optional[str], surface: str, provider: str, model: str,
+            input_tokens: int, output_tokens: int, cost_usd: float, estimated: bool) -> None:
+        con = self._connect()
+        try:
+            con.execute(
+                "INSERT INTO spend (ts, day, task_id, surface, provider, model, input_tokens, "
+                "output_tokens, cost_usd, estimated) VALUES (?,?,?,?,?,?,?,?,?,?)",
+                (time.time(), today(), task_id, surface, provider, model, int(input_tokens),
+                 int(output_tokens), float(cost_usd), 1 if estimated else 0))
+        finally:
+            con.close()
+
+    def reserve(self, *, task_id: Optional[str], surface: str, provider: str, model: str,
+                cost_usd: float, daily_cap: float, task_cap: float):
+        """Check the caps and reserve ``cost_usd`` in ONE transaction.
+        Returns (scope_or_None, day_spent, task_spent, calls, reservation_id).
+        A scope means the cap is reached and nothing was reserved."""
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            day = today()
+            dspent = float(con.execute("SELECT COALESCE(SUM(cost_usd), 0) FROM spend WHERE day=?",
+                                       (day,)).fetchone()[0])
+            tspent, calls = 0.0, 0
+            if task_id is not None:
+                r = con.execute("SELECT COALESCE(SUM(cost_usd), 0), COUNT(*) FROM spend "
+                                "WHERE task_id=?", (task_id,)).fetchone()
+                tspent, calls = float(r[0]), int(r[1])
+            scope = DAILY if dspent >= daily_cap else (
+                TASK if task_id is not None and tspent >= task_cap else None)
+            if scope is not None:
+                con.execute("ROLLBACK")
+                return scope, dspent, tspent, calls, None
+            cur = con.execute(
+                "INSERT INTO spend (ts, day, task_id, surface, provider, model, input_tokens, "
+                "output_tokens, cost_usd, estimated, status) VALUES (?,?,?,?,?,?,0,0,?,1,'reserved')",
+                (time.time(), day, task_id, surface, provider, model, float(cost_usd)))
+            con.execute("COMMIT")
+            return None, dspent, tspent, calls, cur.lastrowid
+        except BaseException:
+            try:
+                con.execute("ROLLBACK")
+            except sqlite3.Error:
+                pass
+            raise
+        finally:
+            con.close()
+
+    def settle(self, reservation: int, *, input_tokens: int, output_tokens: int,
+               cost_usd: float, estimated: bool) -> None:
+        con = self._connect()
+        try:
+            con.execute("UPDATE spend SET input_tokens=?, output_tokens=?, cost_usd=?, "
+                        "estimated=?, status='settled' WHERE id=?",
+                        (int(input_tokens), int(output_tokens), float(cost_usd),
+                         1 if estimated else 0, reservation))
+        finally:
+            con.close()
+
+    def release(self, reservation: int) -> None:
+        con = self._connect()
+        try:
+            con.execute("DELETE FROM spend WHERE id=? AND status='reserved'", (reservation,))
+        finally:
+            con.close()
+
+    def day_total(self, day: Optional[str] = None) -> float:
+        con = self._connect()
+        try:
+            r = con.execute("SELECT COALESCE(SUM(cost_usd), 0) FROM spend WHERE day=?",
+                            (day or today(),)).fetchone()
+            return float(r[0])
+        finally:
+            con.close()
+
+    def task_total(self, task_id: str) -> Tuple[float, int]:
+        """(spend, model calls) recorded for this task, all days."""
+        con = self._connect()
+        try:
+            r = con.execute("SELECT COALESCE(SUM(cost_usd), 0), COUNT(*) FROM spend "
+                            "WHERE task_id=?", (task_id,)).fetchone()
+            return float(r[0]), int(r[1])
+        finally:
+            con.close()
+
+    def rows(self, day: Optional[str] = None) -> List[Dict[str, Any]]:
+        con = self._connect()
+        try:
+            return [dict(r) for r in con.execute(
+                "SELECT * FROM spend WHERE day=? ORDER BY id", (day or today(),)).fetchall()]
+        finally:
+            con.close()
+
+    # ── owner notices (unattended / guest stops) ──
+    def add_notice(self, text: str, dedupe: Optional[str]) -> bool:
+        con = self._connect()
+        try:
+            con.execute("INSERT INTO owner_notices (ts, day, dedupe, text) VALUES (?,?,?,?)",
+                        (time.time(), today(), dedupe, text))
+            return True
+        except sqlite3.IntegrityError:
+            return False   # already notified for this dedupe key
+        finally:
+            con.close()
+
+    def take_notices(self) -> List[str]:
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            rows = con.execute("SELECT id, text FROM owner_notices WHERE delivered=0 "
+                               "ORDER BY id").fetchall()
+            for r in rows:
+                con.execute("UPDATE owner_notices SET delivered=1 WHERE id=?", (r["id"],))
+            con.execute("COMMIT")
+            return [r["text"] for r in rows]
+        except Exception:
+            try:
+                con.execute("ROLLBACK")
+            except sqlite3.Error:
+                pass
+            raise
+        finally:
+            con.close()
+
+
+_STORES: Dict[str, CostStore] = {}
+_STORES_LOCK = threading.Lock()
+
+
+def get_store() -> CostStore:
+    """The store for the current HYPERCLAW_ROOT / HYPERCLAW_COST_DB (read at call time)."""
+    p = str(default_path())
+    with _STORES_LOCK:
+        if p not in _STORES:
+            _STORES[p] = CostStore(p)
+        return _STORES[p]
+
+
+# ───────────────────────────── tasks ─────────────────────────────
+
+@dataclass
+class Task:
+    """One unit of work under the per-task cap: a user message with all its
+    model rounds and tool calls, or one scheduled job."""
+    id: str
+    surface: str
+    request: str = ""
+    unattended: bool = False
+    owner: bool = True
+    conversation: str = ""
+    evidence: Any = None          # the turn's tools.guard.TurnGuard (its .results)
+    stopped: Optional["CostCapReached"] = None
+    started: float = field(default_factory=time.time)
+    # Restricted-client guard (hyperclaw.client_guard): the providers this
+    # task's model calls went to, and what was withheld from them per source.
+    model_providers: set = field(default_factory=set)
+    withheld: Dict[str, int] = field(default_factory=dict)
+
+
+_CURRENT: contextvars.ContextVar = contextvars.ContextVar("hyperclaw_cost_task", default=None)
+
+
+def current_task() -> Optional[Task]:
+    return _CURRENT.get()
+
+
+@contextlib.contextmanager
+def task(*, surface: str, request: str = "", unattended: bool = False, owner: bool = True,
+         conversation: str = "", evidence: Any = None, task_id: Optional[str] = None):
+    """Run the body as one task. Inside an existing task the existing one is
+    reused (a sub-agent or nested call belongs to the task that started it).
+    A fixed ``task_id`` (e.g. a scheduled job's id) keeps its spend across
+    restarts."""
+    existing = _CURRENT.get()
+    if existing is not None:
+        if evidence is not None and existing.evidence is None:
+            existing.evidence = evidence
+        yield existing
+        return
+    t = Task(id=task_id or uuid.uuid4().hex[:16], surface=surface, request=request or "",
+             unattended=unattended, owner=owner, conversation=conversation, evidence=evidence)
+    _CURRENT.set(t)
+    try:
+        yield t
+    finally:
+        _CURRENT.set(None)
+
+
+# ───────────────────────────── the stop ─────────────────────────────
+
+def usd(x: float) -> str:
+    """$1.23; amounts under a cent keep their significant digits ($0.00063)."""
+    x = float(x or 0)
+    if x == 0 or abs(x) >= 0.01:
+        return f"${x:,.2f}"
+    s = f"{x:.6f}".rstrip("0")
+    return "$" + (s if len(s.split(".")[1]) >= 2 else f"{x:.2f}")
+
+
+class CostCapReached(Exception):
+    """Raised by the guard instead of making a model call at the cap. Its
+    text is safe to show the owner (no internal detail)."""
+
+    def __init__(self, scope: str, *, task: Optional[Task], task_spent: float, task_cap: float,
+                 day_spent: float, daily_cap: float, calls: int):
+        self.scope = scope
+        self.task = task
+        self.task_spent = task_spent
+        self.task_cap = task_cap
+        self.day_spent = day_spent
+        self.daily_cap = daily_cap
+        self.calls = calls
+        self.owner_notified = False   # True when this stop sent the owner a new notice
+        super().__init__(self.headline())
+
+    def headline(self) -> str:
+        if self.scope == LEDGER:
+            return ("Stopped: HyperClaw can't read its cost ledger, so it can't check spend "
+                    "against the cap. No model calls run until the ledger can be read again. "
+                    "The technical detail is in the HyperClaw log.")
+        if self.scope == DAILY:
+            return (f"Stopped at today's cost cap: {usd(self.day_spent)} spent of the "
+                    f"{usd(self.daily_cap)} daily cap. No further model calls run today until "
+                    f"the cap is raised.")
+        return (f"Stopped at the per-task cost cap: {usd(self.task_spent)} spent of the "
+                f"{usd(self.task_cap)} cap for one task. No further model calls run for this task.")
+
+
+_UNTASKED_STOPS: set = set()
+_UNTASKED_LOCK = threading.Lock()
+
+
+def _activity(tool: str, target: str, status: str, message: str, conversation: str = "",
+              surface: str = "", turn: str = "") -> None:
+    """One row in the activity log (tools/ledger.py, spec rule 6)."""
+    try:
+        from hyperclaw.tools.ledger import get_ledger
+        get_ledger().record(conversation=conversation or "cost_guard", turn=turn or None,
+                            surface=surface or "cost_guard", tool=tool, effect="system",
+                            target=target, key=None, status=status, message=message)
+    except Exception as e:
+        log.warning("cost guard: could not write the activity log: %s", e)
+
+
+def _stop(scope: str, t: Optional[Task], tspent: float, tcap: float, dspent: float,
+          dcap: float, calls: int) -> CostCapReached:
+    exc = CostCapReached(scope, task=t, task_spent=tspent, task_cap=tcap, day_spent=dspent,
+                         daily_cap=dcap, calls=calls)
+    if t is not None:
+        t.stopped = exc
+        _activity("cost_guard", f"cost_cap:{scope}", "budget_exhausted",
+                  exc.headline() + f" Task {t.id} ({t.surface}).",
+                  conversation=t.conversation, surface=t.surface, turn=t.id)
+        if t.unattended or not t.owner:
+            try:
+                exc.owner_notified = notify_owner(owner_notice(exc), dedupe=f"{today()}:{scope}:"
+                                                  + (t.id if scope == TASK else "day"))
+            except Exception as e:   # the ledger itself may be what failed
+                log.error("cost guard: could not queue the owner notice: %s", e)
+    else:
+        key = (today(), scope)
+        with _UNTASKED_LOCK:
+            first = key not in _UNTASKED_STOPS
+            _UNTASKED_STOPS.add(key)
+        if first:
+            _activity("cost_guard", f"cost_cap:{scope}", "budget_exhausted", exc.headline())
+    log.info("cost guard: %s", exc.headline())
+    return exc
+
+
+def _ledger_stop(t: Optional[Task], err: Exception) -> CostCapReached:
+    log.error("cost guard: the cost ledger can't be read: %s: %s", type(err).__name__, err)
+    return _stop(LEDGER, t, 0.0, task_cap(), 0.0, daily_cap(), 0)
+
+
+def preflight(provider: str, model: str) -> None:
+    """Check only (no reservation). Raises CostCapReached at the cap. The
+    model-call adapters use ``reserve``, which checks and reserves atomically."""
+    t = _CURRENT.get()
+    if t is not None and t.stopped is not None:
+        raise t.stopped
+    store = get_store()
+    try:
+        dspent, dcap, tcap = store.day_total(), daily_cap(), task_cap()
+        tspent, calls = store.task_total(t.id) if t is not None else (0.0, 0)
+    except sqlite3.DatabaseError as e:
+        raise _ledger_stop(t, e) from None
+    if dspent >= dcap:
+        raise _stop(DAILY, t, tspent, tcap, dspent, dcap, calls)
+    if t is not None and tspent >= tcap:
+        raise _stop(TASK, t, tspent, tcap, dspent, dcap, calls)
+
+
+def reserve_estimate(provider: str, model: str, request: Any = None,
+                     max_output_tokens: Optional[int] = None, reasoning: bool = True) -> float:
+    """The amount held for one call while it is in flight: its estimated
+    input plus its output limit — the call's own max when it sets one, else
+    the model's real output maximum (``max_output_for``) — plus the
+    provider's reasoning allowance when thinking is on for the call
+    (HyperSpeed V2: 8192)."""
+    out = _pos_int(max_output_tokens) or unset_max_fallback(provider, model)
+    if reasoning:
+        out += reasoning_tokens_for(provider, model)
+    return cost_of(provider, model, estimate_tokens(request) if request else 0, out)
+
+
+def unset_max_fallback(provider: str, model: str) -> int:
+    """The reservation for a call that set NO max output (!32): the model's
+    real output maximum. Kept as a safety net only; every shipped path sets
+    an explicit max (``max_output``), so this is unreachable from them. With
+    HYPERCLAW_REQUIRE_MAX_OUTPUT on (the test suite) it raises instead, so a
+    path that forgets its max fails its test."""
+    if (os.environ.get(REQUIRE_MAX_ENV) or "").strip().lower() in ("1", "true", "yes", "on"):
+        raise MissingMaxOutput(
+            f"model call without an explicit max output (provider {provider!r}, model "
+            f"{model!r}): every path must pass cost_guard.max_output(<path>, ...)")
+    return max_output_for(provider, model)
+
+
+def reserve(provider: str, model: str, request: Any = None,
+            max_output_tokens: Optional[int] = None, reasoning: bool = True) -> Optional[int]:
+    """Called before every model request: checks the caps and reserves the
+    call's estimated cost in one transaction, so concurrent calls can't all
+    pass the check before any of them records. Raises CostCapReached at the
+    cap (the request is NOT made: no cheaper model, no retry). Returns the
+    reservation id for ``record`` / ``release``."""
+    t = _CURRENT.get()
+    if t is not None and t.stopped is not None:
+        raise t.stopped
+    # Restricted-client guard: the last check on the outgoing request body
+    # (raises RestrictedContentBlocked; nothing is sent), and the record of
+    # which provider this task's model calls go to.
+    from hyperclaw import client_guard
+    client_guard.note_model(provider)
+    client_guard.final_check(provider, request)
+    dcap, tcap = daily_cap(), task_cap()
+    est = reserve_estimate(provider, model, request, max_output_tokens, reasoning)
+    try:
+        scope, dspent, tspent, calls, rid = get_store().reserve(
+            task_id=t.id if t else None, surface=t.surface if t else "",
+            provider=provider or "", model=model or "", cost_usd=est,
+            daily_cap=dcap, task_cap=tcap)
+    except sqlite3.DatabaseError as e:
+        raise _ledger_stop(t, e) from None
+    if scope is not None:
+        raise _stop(scope, t, tspent, tcap, dspent, dcap, calls)
+    return rid
+
+
+def release(reservation: Optional[int]) -> None:
+    """A call that failed before producing anything: drop its reservation.
+    If that fails, the reserved amount stays counted (conservative)."""
+    if reservation is None:
+        return
+    try:
+        get_store().release(reservation)
+    except Exception as e:
+        log.error("cost guard: could not release reservation %s (it stays counted): %s",
+                  reservation, e)
+
+
+def record(provider: str, model: str, input_tokens: int, output_tokens: int,
+           estimated: bool = False, reservation: Optional[int] = None) -> float:
+    """Persist one model call's spend against today and the current task:
+    settles its reservation, or adds a row when there is none. If the write
+    fails, a reservation keeps its reserved amount counted (never dropped)."""
+    cost = cost_of(provider, model, input_tokens, output_tokens)
+    t = _CURRENT.get()
+    try:
+        if reservation is not None:
+            get_store().settle(reservation, input_tokens=input_tokens,
+                               output_tokens=output_tokens, cost_usd=cost, estimated=estimated)
+        else:
+            get_store().add(task_id=t.id if t else None, surface=t.surface if t else "",
+                            provider=provider or "", model=model or "",
+                            input_tokens=input_tokens, output_tokens=output_tokens,
+                            cost_usd=cost, estimated=estimated)
+    except Exception as e:
+        if reservation is not None:
+            log.error("cost guard: could not settle spend of %s (reservation %s stays counted "
+                      "at its reserved amount): %s", usd(cost), reservation, e)
+        else:
+            log.error("cost guard: could not record spend of %s: %s", usd(cost), e)
+    return cost
+
+
+def status(t: Optional[Task] = None) -> Dict[str, Any]:
+    store = get_store()
+    tspent, calls = store.task_total(t.id) if t is not None else (0.0, 0)
+    return {"day": today(), "day_spent_usd": store.day_total(), "daily_cap_usd": daily_cap(),
+            "task_cap_usd": task_cap(), "task_spent_usd": tspent, "task_calls": calls,
+            "spend_line_min_usd": spend_line_min()}
+
+
+# ───────────────────────────── raising a cap ─────────────────────────────
+
+def raise_cap(scope: str, amount_usd: float, *, by: str, surface: str = "") -> float:
+    """Set the daily or per-task cap. This is the ONLY way a cap changes, and
+    it is the user's explicit action (CLI ``hyperclaw cost raise`` or
+    ``/cost raise`` in the terminal): written to config.json and to the
+    activity log. The model has no tool for it."""
+    if scope not in (DAILY, TASK):
+        raise ValueError("scope must be 'daily' or 'task'")
+    v = _num(amount_usd)
+    if v is None:
+        raise ValueError("amount must be a non-negative number of US dollars")
+    old = daily_cap() if scope == DAILY else task_cap()
+    from hyperclaw.userconfig import load_config, update_config
+    cg = dict(load_config().get("cost_guard") or {})
+    cg["daily_cap_usd" if scope == DAILY else "task_cap_usd"] = v
+    update_config(cost_guard=cg)
+    _activity("cost_cap", f"cost_cap:{scope}", "ok",
+              f"{scope} cost cap {usd(old)} -> {usd(v)} by {by}", surface=surface or by)
+    if scope == DAILY:
+        with _UNTASKED_LOCK:
+            _UNTASKED_STOPS.discard((today(), DAILY))
+    return v
+
+
+# ───────────────────────────── messages ─────────────────────────────
+
+def _evidence_lines(t: Optional[Task]) -> List[str]:
+    res = list(getattr(getattr(t, "evidence", None), "results", None) or [])
+    lines = []
+    for r in res[-12:]:
+        s = f"- {r.get('tool')}: {r.get('status')}"
+        if r.get("target"):
+            s += f" ({r['target']})"
+        if r.get("receipt_id"):
+            s += f", receipt {r['receipt_id']}"
+        lines.append(s)
+    if len(res) > 12:
+        lines.insert(0, f"- ({len(res) - 12} earlier tool results not shown)")
+    return lines
+
+
+def _clip(s: str, n: int = 160) -> str:
+    s = " ".join((s or "").split())
+    return s if len(s) <= n else s[:n - 1] + "…"
+
+
+def stop_message(exc: CostCapReached, *, owner: bool = True) -> str:
+    """The stop-and-ask message. Built only from records: the spend table
+    and the turn's tool results (each with its real status). It claims no
+    action that has no record."""
+    if not owner:
+        return ("I can't continue with this request right now. The owner of this assistant "
+                "has been notified.")
+    t = exc.task
+    if exc.scope == LEDGER:
+        req = f" \"{_clip(t.request)}\"" if t is not None and t.request else " This task"
+        return "\n".join([exc.headline(), "",
+                           f"Not finished:{req} has no final answer yet.",
+                           "Run `hyperclaw doctor` to check the ledger, then reply \"continue\"."])
+    tspent, calls = (get_store().task_total(t.id) if t is not None else (exc.task_spent, exc.calls))
+    dspent = get_store().day_total()
+    parts = [exc.headline(), ""]
+    parts.append(f"Spend: {usd(tspent)} on this task ({calls} model call"
+                 f"{'' if calls == 1 else 's'}; per-task cap {usd(exc.task_cap)}) · "
+                 f"{usd(dspent)} today (daily cap {usd(exc.daily_cap)}).")
+    ev = _evidence_lines(t)
+    if ev:
+        parts.append("Tool results recorded for this task (status as returned):")
+        parts.extend(ev)
+    else:
+        parts.append("No tool actions were recorded for this task.")
+    if t is not None and t.request:
+        parts.append(f"Not finished: \"{_clip(t.request)}\" has no final answer yet.")
+    else:
+        parts.append("Not finished: this task has no final answer yet.")
+    parts.append("")
+    if exc.scope == TASK:
+        parts.append(f"Continue? Reply \"continue\" to give it another task budget of "
+                     f"{usd(exc.task_cap)}, or raise the per-task cap first with "
+                     f"`hyperclaw cost raise --task <USD>` (terminal: /cost raise task <USD>).")
+    else:
+        parts.append("Continue? Raising today's cap is your call: run "
+                     "`hyperclaw cost raise --daily <USD>` (terminal: /cost raise daily <USD>), "
+                     "then reply \"continue\". The change is recorded in the activity log.")
+    return "\n".join(parts)
+
+
+def owner_notice(exc: CostCapReached) -> str:
+    t = exc.task
+    who = "a scheduled job" if (t is not None and t.unattended) else "a guest chat"
+    what = f" (\"{_clip(t.request, 80)}\")" if (t is not None and t.request and t.unattended) else ""
+    return (f"HyperClaw cost guard: {who}{what} was stopped. {exc.headline()} "
+            f"Raise a cap with `hyperclaw cost raise --daily <USD>` or "
+            f"`--task <USD>`; nothing else changes until you do.")
+
+
+def unattended_message(exc: CostCapReached) -> str:
+    """What an unattended (scheduled) job returns at the cap. It goes only to
+    the owner's chat (scheduler output is owner-only). Once the owner has
+    been told about this cap today, later stopped jobs return "" (nothing to
+    send; the scheduler logs it) so a 10-minute heartbeat does not repeat it."""
+    return owner_notice(exc) if exc.owner_notified else ""
+
+
+_NOTIFIERS: List[Any] = []
+
+
+def register_owner_notifier(fn) -> None:
+    """fn(text) -> None, called (best effort) when an unattended or guest
+    task is stopped. Every notice is also queued for the owner's next turn."""
+    if fn not in _NOTIFIERS:
+        _NOTIFIERS.append(fn)
+
+
+def notify_owner(text: str, dedupe: Optional[str] = None) -> bool:
+    """Queue (and push, if a notifier is registered) a notice for the owner.
+    False when this dedupe key was already notified."""
+    try:
+        fresh = get_store().add_notice(text, dedupe)
+    except Exception as e:
+        log.warning("cost guard: could not queue the owner notice: %s", e)
+        fresh = True
+    if not fresh:
+        return False
+    for fn in list(_NOTIFIERS):
+        try:
+            fn(text)
+        except Exception as e:
+            log.warning("cost guard: owner notifier failed: %s", e)
+    return True
+
+
+def take_owner_notices() -> List[str]:
+    """Pending notices for the owner (shown once, on the owner's next turn)."""
+    try:
+        return get_store().take_notices()
+    except Exception:
+        return []
+
+
+def spend_line(t: Optional[Task]) -> str:
+    """A short spend line for an answer, or "" below the threshold."""
+    if t is None:
+        return ""
+    try:
+        tspent, _ = get_store().task_total(t.id)
+        if tspent < spend_line_min() or tspent <= 0:
+            return ""
+        return (f"Spend: {usd(tspent)} this task · {usd(get_store().day_total())} of "
+                f"{usd(daily_cap())} today")
+    except Exception:
+        return ""
+
+
+# ───────────────────────────── metering adapters ─────────────────────────────
+
+def _usage_numbers(u) -> Optional[Tuple[int, int]]:
+    """(input, output) tokens from an Anthropic / OpenAI / Gemini usage object or dict."""
+    if u is None:
+        return None
+    g = (lambda k: u.get(k)) if isinstance(u, dict) else (lambda k: getattr(u, k, None))
+    def n(k):
+        v = g(k)
+        return int(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else None
+    i = n("input_tokens")
+    o = n("output_tokens")
+    if i is not None or o is not None:
+        i = (i or 0) + (n("cache_creation_input_tokens") or 0) + (n("cache_read_input_tokens") or 0)
+        return i, o or 0
+    i, o = n("prompt_tokens"), n("completion_tokens")
+    if i is not None or o is not None:
+        return i or 0, o or 0
+    i, o = n("promptTokenCount"), n("candidatesTokenCount")
+    if i is not None or o is not None:
+        return i or 0, o or 0
+    return None
+
+
+class Meter:
+    """Accumulates one call's usage; commit() records it once."""
+
+    def __init__(self, provider: str, model: str, request: Any = None,
+                 reservation: Optional[int] = None):
+        self.provider, self.model, self.request = provider or "", model or "", request
+        self.reservation = reservation
+        self.input_tokens: Optional[int] = None
+        self.output_tokens: Optional[int] = None
+        self.text: List[str] = []
+        self.committed = False
+
+    def usage(self, u) -> None:
+        nums = _usage_numbers(u)
+        if nums is None:
+            return
+        i, o = nums
+        if i:
+            self.input_tokens = max(self.input_tokens or 0, i)
+        if o or self.output_tokens is None:
+            self.output_tokens = max(self.output_tokens or 0, o)
+
+    def usage_from(self, data) -> None:
+        """Usage from a raw JSON response (Anthropic / OpenAI / Gemini shapes)."""
+        if isinstance(data, dict):
+            self.usage(data.get("usage") or data.get("usageMetadata"))
+
+    def add_text(self, s) -> None:
+        if isinstance(s, str) and s:
+            self.text.append(s)
+
+    def commit(self, failed: bool = False) -> float:
+        if self.committed:
+            return 0.0
+        self.committed = True
+        if self.input_tokens is None and self.output_tokens is None:
+            if failed and not self.text:
+                release(self.reservation)
+                return 0.0     # the request failed before producing anything
+            i = estimate_tokens(self.request)
+            o = estimate_tokens("".join(self.text)) if self.text else 0
+            return record(self.provider, self.model, i, o, estimated=True,
+                          reservation=self.reservation)
+        i = self.input_tokens if self.input_tokens is not None else estimate_tokens(self.request)
+        o = self.output_tokens if self.output_tokens is not None else (
+            estimate_tokens("".join(self.text)) if self.text else 0)
+        return record(self.provider, self.model, i, o,
+                      estimated=self.input_tokens is None or self.output_tokens is None,
+                      reservation=self.reservation)
+
+
+@contextlib.contextmanager
+def metered(provider: str, model: str, request: Any = None,
+            max_output_tokens: Optional[int] = None, reasoning: Optional[bool] = None):
+    """For raw-HTTP model calls: preflight, then record the usage the body
+    reports via ``m.usage_from(json)`` / ``m.usage(...)`` (estimated from the
+    request and ``m.add_text`` output when the provider reports none). The
+    output limit is ``max_output_tokens``, else the request body's own
+    max_tokens / max_completion_tokens, else the model's real maximum.
+    ``reasoning`` (default: from the request body, see ``thinking_on``) adds
+    the provider's reasoning allowance."""
+    if max_output_tokens is None:
+        max_output_tokens = _request_max(request)
+    if reasoning is None:
+        reasoning = thinking_on(request)
+    rid = reserve(provider, model, request, max_output_tokens, reasoning)
+    m = Meter(provider, model, request, reservation=rid)
+    try:
+        yield m
+    except BaseException:
+        m.commit(failed=True)
+        raise
+    else:
+        m.commit()
+
+
+def _request_max(req: Any) -> Optional[int]:
+    """The max output a request sets (max_tokens / max_completion_tokens /
+    max_output_tokens), or None."""
+    if not isinstance(req, dict):
+        return None
+    for k in ("max_tokens", "max_completion_tokens", "max_output_tokens"):
+        n = _pos_int(req.get(k))
+        if n is not None:
+            return n
+    return None
+
+
+def _request_of(kw: dict) -> dict:
+    return {k: kw.get(k) for k in ("system", "messages", "tools", "prompt", "input",
+                                   "instructions") if kw.get(k)}
+
+
+def _observe_event(m: Meter, ev) -> None:
+    """Usage/text from one streamed event: Anthropic raw events or OpenAI chunks."""
+    try:
+        typ = getattr(ev, "type", None)
+        if typ == "message_start":
+            m.usage(getattr(getattr(ev, "message", None), "usage", None))
+        elif typ == "message_delta":
+            m.usage(getattr(ev, "usage", None))
+        elif typ == "content_block_delta":
+            d = getattr(ev, "delta", None)
+            m.add_text(getattr(d, "text", None) or getattr(d, "thinking", None))
+        else:
+            u = getattr(ev, "usage", None)
+            if u is not None:
+                m.usage(u)
+            for ch in (getattr(ev, "choices", None) or []):
+                d = getattr(ch, "delta", None)
+                for k in ("content", "reasoning_content", "reasoning"):
+                    m.add_text(getattr(d, k, None))
+                tcs = getattr(d, "tool_calls", None) or []
+                for tc in tcs:
+                    fn = getattr(tc, "function", None)
+                    m.add_text(getattr(fn, "arguments", None))
+    except Exception:
+        pass
+
+
+class _SyncStream:
+    """A streamed response (create(stream=True)); usage recorded when it ends."""
+
+    def __init__(self, inner, meter: Meter):
+        self._inner, self._m = inner, meter
+
+    def __iter__(self):
+        try:
+            for ev in self._inner:
+                _observe_event(self._m, ev)
+                yield ev
+        finally:
+            self._m.commit()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        self._m.commit()
+        close = getattr(self._inner, "close", None)
+        if callable(close):
+            close()
+        return False
+
+    def close(self):
+        self._m.commit()
+        close = getattr(self._inner, "close", None)
+        if callable(close):
+            close()
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+    def __del__(self):
+        try:
+            self._m.commit()
+        except Exception:
+            pass
+
+
+class _AsyncStream:
+    def __init__(self, inner, meter: Meter):
+        self._inner, self._m = inner, meter
+
+    async def __aiter__(self):
+        try:
+            async for ev in self._inner:
+                _observe_event(self._m, ev)
+                yield ev
+        finally:
+            self._m.commit()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *a):
+        self._m.commit()
+        close = getattr(self._inner, "close", None)
+        if callable(close):
+            r = close()
+            if inspect.isawaitable(r):
+                await r
+        return False
+
+    async def close(self):
+        self._m.commit()
+        close = getattr(self._inner, "close", None)
+        if callable(close):
+            r = close()
+            if inspect.isawaitable(r):
+                await r
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+    def __del__(self):
+        try:
+            self._m.commit()
+        except Exception:
+            pass
+
+
+def _usage_from_stream_obj(m: Meter, s) -> None:
+    """Usage from an Anthropic MessageStream after (or during) consumption."""
+    try:
+        snap = getattr(s, "current_message_snapshot", None)
+    except Exception:
+        snap = None
+    if snap is not None:
+        m.usage(getattr(snap, "usage", None))
+        try:
+            for b in getattr(snap, "content", None) or []:
+                m.add_text(getattr(b, "text", None))
+        except Exception:
+            pass
+
+
+class _StreamManager:
+    """messages.stream(...) wrapper: the request runs on enter; usage is
+    recorded on exit from the stream's final snapshot."""
+
+    def __init__(self, inner, meter: Meter):
+        self._inner, self._m, self._s = inner, meter, None
+
+    def __enter__(self):
+        try:
+            self._s = self._inner.__enter__()
+        except BaseException:
+            self._m.commit(failed=True)
+            raise
+        return self._s
+
+    def __exit__(self, et, ev, tb):
+        try:
+            _usage_from_stream_obj(self._m, self._s)
+        finally:
+            self._m.commit(failed=et is not None)
+        return self._inner.__exit__(et, ev, tb)
+
+    async def __aenter__(self):
+        try:
+            self._s = await self._inner.__aenter__()
+        except BaseException:
+            self._m.commit(failed=True)
+            raise
+        return self._s
+
+    async def __aexit__(self, et, ev, tb):
+        try:
+            _usage_from_stream_obj(self._m, self._s)
+        finally:
+            self._m.commit(failed=et is not None)
+        return await self._inner.__aexit__(et, ev, tb)
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+
+def _finish(meter: Meter, res, streamed: bool, is_async: bool):
+    if streamed:
+        return _AsyncStream(res, meter) if is_async else _SyncStream(res, meter)
+    meter.usage(getattr(res, "usage", None) if not isinstance(res, dict) else res.get("usage"))
+    if meter.input_tokens is None and meter.output_tokens is None:
+        try:
+            from hyperclaw.api_utils import extract_text
+            meter.add_text(extract_text(res))
+            for ch in getattr(res, "choices", None) or []:
+                meter.add_text(getattr(getattr(ch, "message", None), "content", None))
+        except Exception:
+            pass
+    meter.commit()
+    return res
+
+
+def _guard_method(inner_method, provider: str, kind: str):
+    """Wrap one SDK method (create / stream). kind: "create" | "stream"."""
+
+    @functools.wraps(inner_method)
+    def wrapper(*a, **kw):
+        model = str(kw.get("model") or "")
+        from hyperclaw import client_guard   # outside models: restricted content withheld
+        kw = client_guard.redact_request(provider, kw)
+        req = _request_of(kw)
+        rid = reserve(provider, model, req, _request_max(kw), thinking_on(kw))
+        meter = Meter(provider, model, req, reservation=rid)
+        try:
+            res = inner_method(*a, **kw)
+        except BaseException:
+            meter.commit(failed=True)
+            raise
+        if kind == "stream":
+            return _StreamManager(res, meter)
+        streamed = bool(kw.get("stream"))
+        if inspect.isawaitable(res):
+            async def _await():
+                try:
+                    r = await res
+                except BaseException:
+                    meter.commit(failed=True)
+                    raise
+                return _finish(meter, r, streamed, True)
+            return _await()
+        return _finish(meter, res, streamed, False)
+
+    wrapper.__cost_guarded__ = True
+    return wrapper
+
+
+class _Namespace:
+    """Proxy for client.messages / client.chat.completions / client.beta.messages."""
+
+    def __init__(self, inner, provider: str, methods: Dict[str, str], children=None):
+        object.__setattr__(self, "_inner", inner)
+        object.__setattr__(self, "_provider", provider)
+        object.__setattr__(self, "_methods", methods)
+        object.__setattr__(self, "_children", children or {})
+
+    def __getattr__(self, name):
+        inner_attr = getattr(self._inner, name)
+        if name in self._methods:
+            return _guard_method(inner_attr, self._provider, self._methods[name])
+        if name in self._children:
+            methods, children = self._children[name]
+            return _Namespace(inner_attr, self._provider, methods, children)
+        return inner_attr
+
+    def __setattr__(self, name, value):
+        setattr(self._inner, name, value)
+
+
+_MESSAGES = ({"create": "create", "stream": "stream"}, {})
+_CLIENT_TREE = {
+    "messages": _MESSAGES,
+    "chat": ({}, {"completions": ({"create": "create"}, {})}),
+    "completions": ({"create": "create"}, {}),
+    "responses": ({"create": "create"}, {}),
+    "beta": ({}, {"messages": _MESSAGES, "chat": ({}, {"completions": ({"create": "create"}, {})})}),
+}
+
+
+def _provider_of(client, provider: Optional[str]) -> str:
+    if provider:
+        return provider
+    mod = type(client).__module__ or ""
+    base = str(getattr(client, "base_url", "") or "")
+    try:
+        from hyperclaw import hyperspeed
+        hs = {hyperspeed.DEFAULT_BASE_URL.rstrip("/"),
+              (os.environ.get("HYPERSPEED_BASE_URL") or "").strip().rstrip("/")} - {""}
+        if base.rstrip("/") in hs:
+            return "hyperspeed"
+    except Exception:
+        pass
+    if mod.startswith("anthropic") or "anthropic" in type(client).__name__.lower():
+        return "anthropic"
+    if mod.startswith("openai"):
+        return "openai"
+    return "unknown"
+
+
+class GuardedClient(_Namespace):
+    """A provider SDK client whose model calls all go through the cost guard.
+    Every other attribute passes through to the real client."""
+
+    __cost_guarded__ = True
+
+    def __init__(self, client, provider: Optional[str] = None):
+        super().__init__(client, _provider_of(client, provider), {}, _CLIENT_TREE)
+
+    @property
+    def unwrapped(self):
+        return self._inner
+
+    def __enter__(self):
+        enter = getattr(self._inner, "__enter__", None)
+        if callable(enter):
+            enter()
+        return self
+
+    def __exit__(self, *a):
+        ex = getattr(self._inner, "__exit__", None)
+        return ex(*a) if callable(ex) else False
+
+    async def __aenter__(self):
+        enter = getattr(self._inner, "__aenter__", None)
+        if callable(enter):
+            await enter()
+        return self
+
+    async def __aexit__(self, *a):
+        ex = getattr(self._inner, "__aexit__", None)
+        return (await ex(*a)) if callable(ex) else False
+
+
+def guard_client(client, provider: Optional[str] = None):
+    """Wrap a provider SDK client so every model call is guarded. Idempotent."""
+    if client is None or getattr(client, "__cost_guarded__", False) is True:
+        return client
+    return GuardedClient(client, provider)
+
+
+def is_guarded(client) -> bool:
+    return getattr(client, "__cost_guarded__", False) is True
+
+
+# ── provider classes (core.providers.llm.LLMProvider, core.providers.image.VisionProvider) ──
+
+def _call_args(fn, self, a, kw) -> Dict[str, Any]:
+    try:
+        b = inspect.signature(fn).bind_partial(self, *a, **kw)
+        b.apply_defaults()
+        args = dict(b.arguments)
+        args.update(args.pop("kwargs", None) or {})
+        return args
+    except (TypeError, ValueError):
+        return dict(kw)
+
+
+def _model_request_max(fn, self, a, kw) -> Tuple[str, dict, Optional[int]]:
+    """(model, request, max output the call sets or None)."""
+    args = _call_args(fn, self, a, kw)
+    model = str(args.get("model") or getattr(self, "default_model", "") or "")
+    msgs = args.get("messages")
+    try:
+        msgs = [getattr(m, "content", m) for m in (msgs or [])]
+    except TypeError:
+        pass
+    req = {k: v for k, v in (("messages", msgs), ("system", args.get("system")),
+                             ("prompt", args.get("prompt")), ("query", args.get("query")))
+           if v}
+    return model, req, _request_max(args)
+
+
+def _accepts_max(fn) -> bool:
+    try:
+        ps = inspect.signature(fn).parameters.values()
+    except (TypeError, ValueError):
+        return False
+    return any(p.name == "max_tokens" or p.kind is inspect.Parameter.VAR_KEYWORD for p in ps)
+
+
+def _explicit_max(fn, self, a, kw) -> Optional[int]:
+    """The max output the CALLER passed (defaults not applied), or None."""
+    try:
+        b = inspect.signature(fn).bind_partial(self, *a, **kw)
+        args = dict(b.arguments)
+        args.update(args.pop("kwargs", None) or {})
+    except (TypeError, ValueError):
+        args = dict(kw)
+    return _request_max(args)
+
+
+def _with_max(fn, self, a, kw, provider: str, path: str):
+    """(model, request, max output, kwargs): a call that passes no max gets
+    the path's ``max_output`` injected as ``max_tokens``, so the provider
+    sends it and the reservation is made against it."""
+    model, req, _ = _model_request_max(fn, self, a, kw)
+    mx = _explicit_max(fn, self, a, kw)
+    if mx is None and _accepts_max(fn):
+        mx = max_output(path, provider, model)
+        kw = dict(kw, max_tokens=mx)
+    return model, req, mx, kw
+
+
+def _guard_coroutine(fn, pname: str, path: str = "provider"):
+    @functools.wraps(fn)
+    async def wrapper(self, *a, **kw):
+        prov = getattr(self, "name", "") or pname
+        model, req, mx, kw = _with_max(fn, self, a, kw, prov, path)
+        with metered(prov, model, req, mx) as m:
+            res = await fn(self, *a, **kw)
+            m.usage({"input_tokens": getattr(res, "input_tokens", None) or None,
+                     "output_tokens": getattr(res, "output_tokens", None) or None})
+            raw = getattr(res, "raw", None)
+            if m.input_tokens is None and m.output_tokens is None and isinstance(raw, dict):
+                m.usage_from(raw)
+            if m.input_tokens is None and m.output_tokens is None:
+                m.add_text(getattr(res, "content", None))
+            return res
+    wrapper.__cost_guarded__ = True
+    wrapper.__max_output_path__ = path
+    return wrapper
+
+
+def _guard_async_gen(fn, pname: str, path: str = "provider"):
+    @functools.wraps(fn)
+    async def wrapper(self, *a, **kw):
+        prov = getattr(self, "name", "") or pname
+        model, req, mx, kw = _with_max(fn, self, a, kw, prov, path)
+        with metered(prov, model, req, mx) as m:
+            async for piece in fn(self, *a, **kw):
+                m.add_text(piece if isinstance(piece, str) else None)
+                yield piece
+    wrapper.__cost_guarded__ = True
+    wrapper.__max_output_path__ = path
+    return wrapper
+
+
+def guard_provider_class(cls, coroutines: Iterable[str] = ("complete",),
+                         streams: Iterable[str] = ("stream",), path: str = "provider") -> None:
+    """Wrap a provider class's model-call methods (coroutines returning a
+    response, async generators yielding text). Called by the provider base
+    classes from __init_subclass__, so no subclass can skip the guard. A call
+    that passes no max output gets ``max_output(path, ...)`` injected."""
+    pname = getattr(cls, "name", "") or cls.__name__
+    for name in coroutines:
+        fn = cls.__dict__.get(name)
+        if fn is not None and not getattr(fn, "__cost_guarded__", False):
+            setattr(cls, name, _guard_coroutine(fn, pname, path))
+    for name in streams:
+        fn = cls.__dict__.get(name)
+        if fn is not None and not getattr(fn, "__cost_guarded__", False):
+            setattr(cls, name, _guard_async_gen(fn, pname, path))
+
+
+def guarded_async(provider: str, path: str = "provider"):
+    """Decorator for a single async model-call method (e.g. an LLM-backed
+    search). The method must accept ``max_tokens`` (or ``**kwargs``) and send
+    it: a call that passes none gets ``max_output(path, ...)`` injected."""
+    def deco(fn):
+        return _guard_coroutine(fn, provider, path)
+    return deco