@allansantos-dev/smart-tool 0.9.31 → 0.9.32

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.9.32 - beta
+
+- Users who updated are told about the new recommended models. `model_upgrade` compares the saved `router_model`,
+  `scope_model`, `research_model` and `scout_model` with the recommended ones against the gateway's catalog and the
+  Windows tray shows a toast with "Apply now" and "Don't show again". Applying keeps the previous models so they can be
+  restored from the setup page (card "New recommended models"); a role you changed after the offer is never overwritten;
+  closing the toast reminds again after 24 h; declining silences it for this version. Embedding and rerank models are
+  never offered (changing them invalidates every index). Buttons are protocol links run by `notice_action.py`
+  (`pythonw`, no window, HKCU only, no admin), each carrying a nonce of the offer.
+- Model failures are logged and shown. `model_health` records every model call by hour, model and role (and, on
+  failure, tool, route and error text without the request content). A tool answer that hit a failing model now carries
+  a line with the model, the role, the error and the link to `/setup#models`; the Models page shows the last 24 h
+  (failures/calls) and the 20 latest failures; the tray raises one toast per model per day (5+ calls and 50%+ failures
+  in 24 h) with "Switch model" and "Mute 7 days". Endpoint: `GET /setup/models/health`.
+- Tests: `tests/test_model_upgrade.py`, `tests/test_model_health.py`; research note
+  `docs/research/2026-10-24-aviso-de-modelos-novos-e-falhas-de-modelo.md`.
+
 ## 0.9.31 - beta
 
 - `scout_model` is filled by default. The setup screen (and the daemon, when it checks the models) now fills an empty

package/README.md

@@ -16,7 +16,7 @@ registered as the `playwright` server where this machine lets a browser be drive
 An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
 are cheaper, or just tells the agent what Smart Tool would do.
 
-**Status:** 0.9.31 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
+**Status:** 0.9.32 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
 
 ## How it works
 
@@ -92,7 +92,7 @@ updating, updated, update failed), and agent sessions get the same line on their
 start when the SessionStart report is on, shown to you too) with the link to the changes. The tray menu has "Update to
 X" (or "Check for updates") on demand and an "Update automatically" switch; `SMART_TOOL_AUTO_UPDATE=off` also turns
 automatic updates off, and the newer-version notice then carries the command to run. Running the command by hand also updates; `~/.smart-tool` is kept. It downloads [uv](https://docs.astral.sh/uv/) (checksum
-verified) and a private Python 3.12 into `~/.smart-tool/runtime`, with nothing added to `PATH` or the registry, then
+verified) and a private Python 3.12 into `~/.smart-tool/runtime`, with nothing added to `PATH` and, in the registry, only two per-user (HKCU) keys that make the notification buttons work, then
 copies Smart Tool to `%LOCALAPPDATA%\Programs\SmartTool` with its own virtual environment,
 installs the web runtime, registers a per-user Scheduled Task that starts the tray at logon and starts the daemon on
 `http://127.0.0.1:8765` (another free port is used, and announced, if 8765 is taken).
@@ -251,13 +251,16 @@ fails to load is listed in the setup screen with its error and does not affect t
   everything local.
 - Web queries go to the search sources listed in `NOTICE`. Their free tiers are rate limited per IP address; respect
   each service's terms of use.
-- Logs and metrics are written to `~/.smart-tool/data` and never leave the machine.
+- Logs and metrics are written to `~/.smart-tool/data` and never leave the machine. That includes the model failure log
+  (model, role, tool and the error text, up to 300 characters, which can carry the gateway's error body; never the request).
 
 ## Uninstall
 
 Turn off "Start automatically" in the setup screen, quit from the tray, remove the hook entries from
 `~/.claude/settings.json` / `~/.codex/hooks.json` (the setup screen shows them), run `claude mcp remove smart-tool -s
-user` / `codex mcp remove smart-tool`, then delete `%LOCALAPPDATA%\Programs\SmartTool` and `~/.smart-tool`.
+user` / `codex mcp remove smart-tool`, then delete `%LOCALAPPDATA%\Programs\SmartTool` and `~/.smart-tool`. Turning off "Start automatically" also removes the
+two per-user registry keys of the notification buttons (`HKCU\Software\Classes\smart-tool-action` and
+`HKCU\Software\Classes\AppUserModelId\SmartTool.Notifications`); they come back the next time a notification is shown.
 
 ## License
 

package/autostart.py

@@ -11,6 +11,8 @@ import subprocess
 import sys
 import tempfile
 
+import toast_notice
+
 TASK_NAME = os.environ.get("SMART_TOOL_TASK_NAME", "SmartTool-Tray")
 
 
@@ -188,6 +190,8 @@ def remove():
         pass
     if _remove_startup_shortcut():
         removed.append("startup_folder")
+    if sys.platform == "win32" and toast_notice.unregister():
+        removed.append("toast_registry")
     return {"ok": True, "removed": removed}
 
 

package/model_client.py

@@ -7,6 +7,7 @@ import urllib.error
 import usage_meter
 
 import gateway
+import model_health
 
 OFFLINE = contextvars.ContextVar("model_offline", default=None)
 _NO_TEMPERATURE = set()
@@ -34,6 +35,7 @@ def fetch(path, token, method="GET", body=None, timeout=15):
         raise
     finally:
         usage_meter.record(path,body,result,headers,failure,time.monotonic()-started)
+        model_health.record(path,body,failure)
 
 
 def _fetch(path, _token, method="GET", body=None, timeout=15):

package/model_health.py

@@ -0,0 +1,164 @@
+"""Failure log and failure rate of the gateway models, per model and role (router, scope, scout, research, embedding,
+rerank). Never stores request content: the model, the role, the tool that was running, the HTTP path, a short error
+text and the time.
+
+Three consumers read it: the tool answer (a warning line when a call of that very tool failed), the setup screen
+(rate table and recent failures) and the tray (one toast per model per day when the rate passes the limit).
+"""
+import contextlib
+import contextvars
+import io
+import os
+import sqlite3
+import time
+
+import config
+import project_store
+
+WINDOW_S = 24 * 3600
+ALERT_MIN_CALLS = 5
+ALERT_RATE = 0.5
+ALERT_EVERY_S = 24 * 3600
+MUTE_S = 7 * 24 * 3600
+KEEP_S = 7 * 24 * 3600
+KEEP_FAILURES = 500
+ERROR_CHARS = 300
+_ROLES = ("router_model", "scope_model", "scout_model", "research_model", "embedding_model", "rerank_model")
+_PATHS = ("/v1/chat/completions", "/v1/embeddings", "/v1/rerank")
+_TOOL = contextvars.ContextVar("model_health_tool", default=None)
+_COLLECTED = contextvars.ContextVar("model_health_collected", default=None)
+_SCHEMA = set()
+
+
+@contextlib.contextmanager
+def tool_call(name):
+    """Marks the model calls made inside the block as run by tool `name` and collects their failures; the block yields
+    the list, which `warning_text` turns into the line appended to the tool answer."""
+    failures = []
+    tool_token, list_token = _TOOL.set(name), _COLLECTED.set(failures)
+    try:
+        yield failures
+    finally:
+        _TOOL.reset(tool_token)
+        _COLLECTED.reset(list_token)
+
+
+def _db():
+    return project_store._db()
+
+
+def _tables(db):
+    if project_store.DB_PATH in _SCHEMA and os.path.isfile(project_store.DB_PATH):
+        return
+    db.execute("CREATE TABLE IF NOT EXISTS model_calls(hour INTEGER,model TEXT,role TEXT,calls INTEGER,errors INTEGER,"
+               "PRIMARY KEY(hour,model,role))")
+    db.execute("CREATE TABLE IF NOT EXISTS model_failures(at REAL,model TEXT,role TEXT,tool TEXT,path TEXT,error TEXT)")
+    db.execute("CREATE TABLE IF NOT EXISTS model_alerts(model TEXT PRIMARY KEY,last_notified REAL,muted_until REAL)")
+    _SCHEMA.add(project_store.DB_PATH)
+
+
+def role_of(model, cfg=None):
+    """Name of the config field that selects `model` ('other' when none does)."""
+    cfg = cfg if cfg is not None else config.load_config()
+    return next((field for field in _ROLES if cfg.get(field) == model), "other")
+
+
+def error_text(exc):
+    """Short text of a failed call. An HTTP error body is read once and put back so the caller can still read it."""
+    text = f"{type(exc).__name__}: {exc}"
+    fp = getattr(exc, "fp", None)
+    if fp is not None and hasattr(exc, "read"):
+        try:
+            detail = exc.read()
+            exc.read = io.BytesIO(detail).read
+            text += " | " + detail.decode("utf-8", "replace")
+        except Exception:
+            pass
+    return " ".join(text.split())[:ERROR_CHARS]
+
+
+def record(path, body, failure=None):
+    """Counts one model call and, when it failed, logs it. Never raises: the log must not change the call's result."""
+    if path not in _PATHS:
+        return
+    try:
+        model = str((body or {}).get("model", "")) if isinstance(body, dict) else ""
+        role = role_of(model)
+        now = time.time()
+        text = error_text(failure) if failure is not None else None
+        with project_store._LOCK, _db() as db:
+            _tables(db)
+            db.execute("INSERT INTO model_calls VALUES(?,?,?,1,?) ON CONFLICT(hour,model,role) DO UPDATE SET "
+                       "calls=calls+1,errors=errors+excluded.errors", (int(now // 3600), model, role, int(text is not None)))
+            if text is not None:
+                db.execute("INSERT INTO model_failures VALUES(?,?,?,?,?,?)", (now, model, role, _TOOL.get() or "", path, text))
+                db.execute("DELETE FROM model_failures WHERE at<? OR rowid NOT IN "
+                           "(SELECT rowid FROM model_failures ORDER BY at DESC LIMIT ?)", (now - KEEP_S, KEEP_FAILURES))
+                db.execute("DELETE FROM model_calls WHERE hour<?", (int((now - KEEP_S) // 3600),))
+        collected = _COLLECTED.get()
+        if text is not None and collected is not None:
+            collected.append({"model": model, "role": role, "error": text})
+    except Exception:
+        pass
+
+
+def warning_text(failures, setup_url):
+    """The line a tool answer carries when a model call inside it failed ('' when none did)."""
+    if not failures:
+        return ""
+    first = failures[0]
+    more = f" (+{len(failures) - 1} more)" if len(failures) > 1 else ""
+    return (f"\n\nSmart Tool model warning: {first['role']} `{first['model']}` failed in this call{more}: "
+            f"{first['error']}. Pick another model: {setup_url}/setup#models")
+
+
+def summary(now=None):
+    """Per model and role over the last 24 h, plus the 20 latest failures."""
+    now = now or time.time()
+    with project_store._LOCK, _db() as db:
+        _tables(db)
+        db.row_factory = sqlite3.Row
+        models = [dict(row) for row in db.execute(
+            "SELECT model,role,SUM(calls) AS calls,SUM(errors) AS errors FROM model_calls WHERE hour>=? "
+            "GROUP BY model,role ORDER BY SUM(errors) DESC,SUM(calls) DESC", (int((now - WINDOW_S) // 3600),))]
+        failures = [dict(row) for row in db.execute(
+            "SELECT at,model,role,tool,path,error FROM model_failures WHERE at>=? ORDER BY at DESC LIMIT 20", (now - WINDOW_S,))]
+        for row in models:
+            last = db.execute("SELECT error FROM model_failures WHERE model=? AND role=? ORDER BY at DESC LIMIT 1",
+                              (row["model"], row["role"])).fetchone()
+            row["last_error"] = last[0] if last else ""
+    for row in models:
+        row["rate"] = round(row["errors"] / row["calls"], 3) if row["calls"] else 0.0
+        row["failing"] = row["calls"] >= ALERT_MIN_CALLS and row["rate"] >= ALERT_RATE
+    return {"window_hours": WINDOW_S // 3600, "models": models, "failures": failures}
+
+
+def alerts_due(now=None):
+    """Models over the failure limit that are neither muted nor already announced in the last 24 h; marks them
+    announced, so a second call in the same day returns nothing."""
+    now = now or time.time()
+    due = []
+    for row in summary(now)["models"]:
+        if not row["failing"]:
+            continue
+        with project_store._LOCK, _db() as db:
+            _tables(db)
+            seen = db.execute("SELECT last_notified,muted_until FROM model_alerts WHERE model=?", (row["model"],)).fetchone()
+            if seen and (seen[1] > now or now - seen[0] < ALERT_EVERY_S):
+                continue
+            db.execute("INSERT INTO model_alerts VALUES(?,?,0) ON CONFLICT(model) DO UPDATE SET last_notified=excluded.last_notified",
+                       (row["model"], now))
+        due.append(row)
+    return due
+
+
+def mute(model, now=None):
+    """Silences the failure toast for `model` for 7 days (the failures stay in the log)."""
+    if not model:
+        raise ValueError("No model to mute.")
+    now = now or time.time()
+    with project_store._LOCK, _db() as db:
+        _tables(db)
+        db.execute("INSERT INTO model_alerts VALUES(?,?,?) ON CONFLICT(model) DO UPDATE SET muted_until=excluded.muted_until",
+                   (model, now, now + MUTE_S))
+    return f"failure alerts for {model} muted for 7 days"

package/model_upgrade.py

@@ -0,0 +1,140 @@
+"""Tells who updated that this version recommends other models than the ones the config holds, and applies them only on
+consent. `model_defaults.ensure_recommended_models` fills empty fields only, so a user who updated keeps the previous
+version's defaults forever; this module is the visible, reversible way out.
+
+State lives in `config.json` under `defaults_notice`, tied to DEFAULTS_VERSION: pending (announced once a day until the
+user answers), declined (silent for this version), applied (the replaced models are kept for `revert`). Raising
+DEFAULTS_VERSION when RECOMMENDED_MODELS changes starts a new notice for everyone. Embedding and rerank are never
+offered: changing them invalidates every index.
+"""
+import secrets
+import time
+
+import config
+import model_catalog
+import model_defaults
+
+DEFAULTS_VERSION = 1
+ROLES = ("router_model", "scope_model", "scout_model", "research_model")
+REMIND_EVERY_S = 24 * 3600
+
+
+def _current(cfg):
+    """The notice of this defaults version, or a blank one."""
+    notice = cfg.get("defaults_notice") or {}
+    return notice if notice.get("version") == DEFAULTS_VERSION else {"version": DEFAULTS_VERSION, "state": "none"}
+
+
+def _differences(cfg, chat):
+    """{role: {"current", "new"}} for each role the user has set to something other than the recommended model that
+    this gateway's catalog has."""
+    found = {}
+    for role in ROLES:
+        wanted = model_defaults._matching(chat, model_defaults.RECOMMENDED_MODELS[role][1])
+        if wanted and cfg.get(role) and cfg[role] != wanted:
+            found[role] = {"current": cfg[role], "new": wanted}
+    return found
+
+
+def check():
+    """Recomputes what is on offer against the gateway catalog and stores it. Raises when the catalog is unreachable
+    (the caller shows that; no answer is invented). Returns `status()`."""
+    cfg = config.load_config()
+    notice = _current(cfg)
+    if notice["state"] in ("declined", "applied"):
+        return status()
+    found = _differences(cfg, set(model_catalog.list_models("chat")))
+
+    def store(current):
+        notice = dict(_current(current))
+        if not found:
+            notice.update(state="none", changes={}, nonce="")
+        else:
+            notice.update(state="pending", changes=found, nonce=notice.get("nonce") or secrets.token_hex(8))
+        current["defaults_notice"] = notice
+
+    config.update_config(store)
+    return status()
+
+
+def status(cfg=None):
+    """What the setup screen and the tray read: state, the model changes on offer, and what `revert` would restore."""
+    notice = _current(cfg if cfg is not None else config.load_config())
+    return {"version": DEFAULTS_VERSION, "state": notice["state"], "changes": notice.get("changes") or {},
+            "previous": notice.get("previous") or {}, "nonce": notice.get("nonce", "")}
+
+
+def _change(mutate_notice, nonce):
+    """Runs `mutate_notice(cfg, notice)` under the config lock on a pending notice; `nonce` None (the setup screen,
+    which has its own token) skips the link check, a toast button must carry the nonce it was shown with."""
+    result = {}
+
+    def apply(cfg):
+        notice = dict(_current(cfg))
+        if notice["state"] != "pending":
+            raise ValueError(f"No new default models are waiting (state: {notice['state']}).")
+        if nonce is not None and not secrets.compare_digest(str(nonce), str(notice.get("nonce", ""))):
+            raise ValueError("This notification is out of date; open the settings to see the current offer.")
+        result["text"] = mutate_notice(cfg, notice)
+        cfg["defaults_notice"] = notice
+
+    config.update_config(apply)
+    return result["text"]
+
+
+def apply(nonce=None):
+    """Switches the offered roles to the recommended models and keeps the previous ones for `revert`."""
+    def mutate(cfg, notice):
+        # A role the user changed since the offer was made is theirs: it is skipped, never overwritten.
+        todo = {role: change for role, change in notice["changes"].items() if cfg.get(role) == change["current"]}
+        if not todo:
+            raise ValueError("The offered roles were changed since the notice; open the settings to see the current state.")
+        notice["previous"] = {role: change["current"] for role, change in todo.items()}
+        for role, change in todo.items():
+            cfg[role] = change["new"]
+        notice.update(state="applied", applied_at=time.time())
+        return "applied: " + ", ".join(f"{role} {change['current']} -> {change['new']}" for role, change in todo.items())
+    return _change(mutate, nonce)
+
+
+def decline(nonce=None):
+    """Stops announcing this defaults version; the user's models stay as they are."""
+    def mutate(cfg, notice):
+        notice["state"] = "declined"
+        return "declined: no more notices for this version of the defaults"
+    return _change(mutate, nonce)
+
+
+def revert():
+    """Puts back the models `apply` replaced. Raises when nothing was applied."""
+    done = {}
+
+    def put_back(cfg):
+        notice = dict(_current(cfg))
+        if notice["state"] != "applied" or not notice.get("previous"):
+            raise ValueError("Nothing to revert: the recommended models were not applied.")
+        for role, model in notice["previous"].items():
+            cfg[role] = model
+        done["text"] = "reverted: " + ", ".join(f"{role} -> {model}" for role, model in notice["previous"].items())
+        notice.update(state="declined", previous={})
+        cfg["defaults_notice"] = notice
+
+    config.update_config(put_back)
+    return done["text"]
+
+
+def due(now=None):
+    """The offer the tray should announce now (pending and not announced in the last 24 h), or None. Marks it
+    announced, so a second call in the same day returns None; closing the toast without choosing brings it back."""
+    now = now or time.time()
+    taken = {}
+
+    def mark(cfg):
+        notice = dict(_current(cfg))
+        if notice["state"] == "pending" and notice.get("changes") and now - notice.get("last_notified", 0) >= REMIND_EVERY_S:
+            notice["last_notified"] = now
+            cfg["defaults_notice"] = notice
+            taken["offer"] = {"changes": notice["changes"], "nonce": notice["nonce"]}
+
+    config.update_config(mark)
+    return taken.get("offer")

package/notice_action.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Runs a toast button: `pythonw notice_action.py "smart-tool-action:<action>?<query>"`.
+
+Started by Windows through the protocol registered in `toast_notice.register`, with no window. Every outcome (done or
+refused) is appended to `notice-actions.log` in the data folder, because nothing else can show an error here.
+"""
+import os
+import sys
+import time
+import urllib.parse
+import webbrowser
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import model_upgrade
+import paths
+import toast_notice
+
+LOG_PATH = os.path.join(paths.DATA_DIR, "notice-actions.log")
+
+
+def run(uri):
+    """Returns a short result line. Raises ValueError for a link that is not ours or an action that does not exist."""
+    prefix = toast_notice.PROTOCOL + ":"
+    if not uri.startswith(prefix):
+        raise ValueError(f"Not a Smart Tool link: {uri[:80]!r}")
+    action, _, query = uri[len(prefix):].partition("?")
+    params = dict(urllib.parse.parse_qsl(query))
+    if action == "models-apply":
+        return model_upgrade.apply(params.get("n", ""))
+    if action == "models-decline":
+        return model_upgrade.decline(params.get("n", ""))
+    if action == "open-setup":
+        import daemon_launcher
+        webbrowser.open(daemon_launcher.ensure_daemon_running().rstrip("/") + "/setup#" + params.get("section", "models"))
+        return "setup opened"
+    if action == "mute-model":
+        import model_health
+        return model_health.mute(params.get("model", ""))
+    raise ValueError(f"Unknown action {action!r}")
+
+
+def main(argv):
+    """Runs the link in `argv[1]` and logs the outcome; returns the process exit code (0 done, 1 refused)."""
+    os.makedirs(os.path.dirname(LOG_PATH), exist_ok=True)
+    stamp = time.strftime("%Y-%m-%d %H:%M:%S")
+    try:
+        line = f"{stamp} ok {argv[1] if len(argv) > 1 else ''} -> {run(argv[1])}"
+        code = 0
+    except Exception as exc:
+        line = f"{stamp} FAIL {argv[1] if len(argv) > 1 else ''} -> {type(exc).__name__}: {exc}"
+        code = 1
+    with open(LOG_PATH, "a", encoding="utf-8") as log:
+        log.write(line + "\n")
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allansantos-dev/smart-tool",
-  "version": "0.9.31",
+  "version": "0.9.32",
   "description": "Local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search. Windows.",
   "license": "Apache-2.0",
   "author": "Allan Santos",

package/setup_ui.py

@@ -18,6 +18,7 @@ import json
 import os
 import re
 import secrets
+import time
 
 import autostart
 import block_patterns
@@ -29,6 +30,8 @@ import endpoint_sync
 import gateway
 import model_catalog
 import model_defaults
+import model_health
+import model_upgrade
 import local_embedder
 import project_store
 import secret_store
@@ -155,6 +158,56 @@ def handle_models_get():
     }
 
 
+_UPGRADE_CHECK_EVERY_S = 3600
+_upgrade_checked = {"at": 0.0, "error": ""}
+
+
+def _checked_upgrade(force=False):
+    """The model offer, rechecked against the catalog at most once an hour (or when forced). A catalog that cannot be
+    read is reported in `check_error`, with the last stored offer, never as 'nothing to offer'."""
+    now = time.time()
+    if force or now - _upgrade_checked["at"] >= _UPGRADE_CHECK_EVERY_S:
+        try:
+            model_upgrade.check()
+            _upgrade_checked["error"] = ""
+        except Exception as exc:
+            _upgrade_checked["error"] = str(exc)[:300]
+        _upgrade_checked["at"] = now
+    return {**model_upgrade.status(), "check_error": _upgrade_checked["error"]}
+
+
+def handle_upgrade_get():
+    return _checked_upgrade(force=True)
+
+
+def handle_upgrade_action(body):
+    action = body.get("action") if isinstance(body, dict) else None
+    try:
+        if action == "apply":
+            text = model_upgrade.apply()
+        elif action == "decline":
+            text = model_upgrade.decline()
+        elif action == "revert":
+            text = model_upgrade.revert()
+        else:
+            raise SetupError("Invalid action: use apply, decline or revert.")
+    except (ValueError, config.ConfigCorruptedError, OSError) as exc:
+        raise SetupError(str(exc))
+    return {"ok": True, "message": text, "upgrade": model_upgrade.status()}
+
+
+def handle_health_get():
+    return model_health.summary()
+
+
+def handle_notices():
+    """What the tray should show now: the model offer (once a day until answered) and models over the failure limit
+    (once a day each). Fetching marks them announced, so each toast is shown once per reminder period."""
+    upgrade = _checked_upgrade()
+    offer = model_upgrade.due() if upgrade["state"] == "pending" else None
+    return {"upgrade": offer, "failing": model_health.alerts_due(), "check_error": upgrade["check_error"]}
+
+
 def handle_local_models_get():
     available = local_embedder.info() if local_embedder.configured() else None
     return {"mode": config.local_models_mode(), "modes": list(config.LOCAL_MODEL_MODES),
@@ -671,6 +724,24 @@ _PAGE_TEMPLATE = """<!doctype html>
         <div class="msg" id="gateway-msg" role="status"></div>
       </div>
 
+      <div class="card" id="upgrade-card" hidden>
+        <div class="card-head"><h3>New recommended models</h3><span class="pill" id="upgrade-pill" data-tone="warn">Available</span></div>
+        <p class="lede">This version recommends other models than the ones you use. Nothing changes until you apply; the models you have now are kept so you can switch back.</p>
+        <ul id="upgrade-list"></ul>
+        <div class="actions">
+          <button type="button" class="primary" id="btn-upgrade-apply">Apply recommended models</button>
+          <button type="button" id="btn-upgrade-decline">Keep mine, don't ask again</button>
+          <button type="button" id="btn-upgrade-revert" hidden>Switch back to my previous models</button>
+        </div>
+        <div class="msg" id="upgrade-msg" role="status"></div>
+      </div>
+
+      <div class="card" id="health-card">
+        <div class="card-head"><h3>Model failures (last 24 h)</h3><span class="pill" id="health-pill" data-tone="busy">Checking</span></div>
+        <p class="lede">Every failed call to a gateway model, by role and tool. A model that fails half of its calls (5 or more) also raises a Windows notification.</p>
+        <div id="health-table"></div>
+      </div>
+
       <div class="card" id="models-card">
         <div class="card-head"><h3>2. Models</h3><span class="pill" id="models-pill" data-tone="busy">Checking</span></div>
         <p class="lede">Any model id your gateway accepts. The gateway's catalog shows up as suggestions while you type.</p>
@@ -1048,6 +1119,52 @@ async function loadModels() {
     setMsg("models-msg", "error", "Could not read the gateway catalog: " + error.message);
   }
 }
+
+function esc(text) { const el = document.createElement("span"); el.textContent = text; return el.innerHTML; }
+async function loadUpgrade() {
+  try {
+    const data = await getJSON("/setup/models/upgrade");
+    const rows = Object.entries(data.changes || {}).map(([role, change]) => `<li><b>${esc(role)}</b>: ${esc(change.current)} → ${esc(change.new)}</li>`);
+    const offer = data.state === "pending" && rows.length;
+    const applied = data.state === "applied" && Object.keys(data.previous || {}).length;
+    $("upgrade-card").hidden = !(offer || applied);
+    $("upgrade-list").innerHTML = offer ? rows.join("") : Object.entries(data.previous).map(([role, model]) => `<li><b>${esc(role)}</b> was ${esc(model)}</li>`).join("");
+    setPill("upgrade-pill", offer ? "warn" : "ok", offer ? "Available" : "Applied");
+    $("btn-upgrade-apply").hidden = $("btn-upgrade-decline").hidden = !offer;
+    $("btn-upgrade-revert").hidden = !applied;
+    if (data.check_error) setMsg("upgrade-msg", "error", "Could not check the catalog: " + data.check_error);
+  } catch (error) {
+    $("upgrade-card").hidden = false;
+    setMsg("upgrade-msg", "error", "Could not read the model offer: " + error.message);
+  }
+}
+for (const [id, action] of [["btn-upgrade-apply", "apply"], ["btn-upgrade-decline", "decline"], ["btn-upgrade-revert", "revert"]]) {
+  $(id).addEventListener("click", async () => {
+    setMsg("upgrade-msg", "", "Working…");
+    try {
+      const result = await post("/setup/models/upgrade", { action });
+      await loadUpgrade();
+      await loadModels();
+      setMsg("upgrade-msg", "ok", result.message);
+    } catch (error) {
+      setMsg("upgrade-msg", "error", error.message);
+    }
+  });
+}
+async function loadHealth() {
+  try {
+    const data = await getJSON("/setup/models/health");
+    const failing = data.models.filter((row) => row.failing).length;
+    setPill("health-pill", failing ? "bad" : "ok", failing ? plural(failing, "model") + " failing" : "No problem");
+    const models = data.models.map((row) => `<tr><td>${esc(row.role)}</td><td>${esc(row.model)}</td><td>${row.errors} / ${row.calls}</td><td>${Math.round(row.rate * 100)}%</td></tr>`).join("");
+    const failures = data.failures.map((row) => `<tr><td>${esc(new Date(row.at * 1000).toLocaleString())}</td><td>${esc(row.role)}</td><td>${esc(row.model)}</td><td>${esc(row.tool || "-")}</td><td>${esc(row.error)}</td></tr>`).join("");
+    $("health-table").innerHTML = (models ? `<table><tr><th>Role</th><th>Model</th><th>Failed / calls</th><th>Rate</th></tr>${models}</table>` : "<p>No model call in the last 24 hours.</p>")
+      + (failures ? `<table><tr><th>When</th><th>Role</th><th>Model</th><th>Tool</th><th>Error</th></tr>${failures}</table>` : "");
+  } catch (error) {
+    setPill("health-pill", "bad", "Unavailable");
+    $("health-table").textContent = "Could not read the failure log: " + error.message;
+  }
+}
 $("btn-save-models").addEventListener("click", async () => {
   if (!modelsLoaded) { setMsg("models-msg", "error", "The catalog has not loaded yet; nothing was saved."); return; }
   setMsg("models-msg", "", "Saving…");
@@ -1809,7 +1926,8 @@ $("btn-audit-run").addEventListener("click", async () => {
 
 renderGateway();
 renderOverview();
-if (status.gateway.status === "ready") loadModels();
+if (status.gateway.status === "ready") { loadModels(); loadUpgrade(); }
+loadHealth();
 loadLocalModels();
 loadIntegration();
 loadAutostart();

package/smart_tool_daemon.py

@@ -55,6 +55,7 @@ import dossier
 import scout
 import embedding_cache
 import model_defaults
+import model_health
 import project_identity
 import project_store
 import project_scheduler
@@ -3984,13 +3985,19 @@ def _dispatch_tool_call(params, session_id=None):
         return _tool_result(_sanitize_text(f"Unknown tool: {name}"), is_error=True)
     token = _MCP_SESSION.set(session_id)
     try:
-        return _tool_result(handler(arguments))
-    except Exception as exc:
-        # Boundary central pra qualquer handler atual/futuro: uma exceção pode
-        # carregar texto de uma fonte não totalmente confiável (ex.: corpo/reason
-        # de erro de um proxy externo) até este ponto sem ter passado por
-        # sanitização própria do handler.
-        return _tool_result(_sanitize_text(str(exc)), is_error=True)
+        with model_health.tool_call(name) as failures:
+            try:
+                result = _tool_result(handler(arguments))
+            except Exception as exc:
+                # Boundary central pra qualquer handler atual/futuro: uma exceção pode
+                # carregar texto de uma fonte não totalmente confiável (ex.: corpo/reason
+                # de erro de um proxy externo) até este ponto sem ter passado por
+                # sanitização própria do handler.
+                result = _tool_result(_sanitize_text(str(exc)), is_error=True)
+        warning = model_health.warning_text(failures, setup_ui.setup_origin())
+        if warning:
+            result["content"][0]["text"] += _sanitize_text(warning)
+        return result
     finally:
         _MCP_SESSION.reset(token)
 
@@ -4059,6 +4066,7 @@ def _loopback_host(header_value, require_port=False):
 
 _SETUP_SAVES = {
     "/setup/models": setup_ui.handle_models_save,
+    "/setup/models/upgrade": setup_ui.handle_upgrade_action,
     "/setup/providers": setup_ui.handle_providers_save,
     "/setup/local-models": setup_ui.handle_local_models_save,
     "/setup/integration": setup_ui.handle_integration_save,
@@ -4180,6 +4188,13 @@ class MCPHandler(BaseHTTPRequestHandler):
             except Exception as exc:
                 self._write_json(500, {"error": _sanitize_text(str(exc))})
             return
+        if self.path in ("/setup/models/upgrade", "/setup/models/health"):
+            try:
+                self._write_json(200, setup_ui.handle_upgrade_get() if self.path.endswith("upgrade")
+                                 else setup_ui.handle_health_get())
+            except Exception as exc:
+                self._write_json(500, {"error": _sanitize_text(str(exc))})
+            return
         if self.path == "/projects":
             import projects_ui
             self._write_html(200, projects_ui.render_projects_page())
@@ -4263,6 +4278,12 @@ class MCPHandler(BaseHTTPRequestHandler):
         if urllib.parse.urlsplit(self.path).path == "/hooks/session-audit":
             self._write_json(200, _session_audit_hook(self))
             return
+        if self.path == "/setup/notices":
+            try:
+                self._write_json(200, setup_ui.handle_notices())
+            except Exception as exc:
+                self._write_json(500, {"error": _sanitize_text(str(exc))})
+            return
         save = _SETUP_SAVES.get(self.path)
         if save:
             self._post_setup(save)

package/toast_notice.py

@@ -0,0 +1,99 @@
+"""Windows toast with buttons, no dependency: PowerShell 5.1 (always present) shows it through the WinRT toast API and
+each button is a protocol link that Windows hands to `notice_action.py`.
+
+An unpackaged app has no COM activator, so a button cannot call back into a running process. The protocol route needs
+only HKCU keys (no admin): one AppUserModelId key (name and icon of the toast) and one URL protocol whose command runs
+`pythonw notice_action.py "<uri>"` without a window. Actions are therefore small independent commands that read and
+write the config file, never state held by the tray.
+"""
+import base64
+import os
+import subprocess
+import sys
+import urllib.parse
+from xml.sax.saxutils import quoteattr, escape
+
+APP_ID = "SmartTool.Notifications"
+PROTOCOL = "smart-tool-action"
+ACTION_SCRIPT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "notice_action.py")
+
+_SHOW_SCRIPT = r"""
+$ErrorActionPreference = 'Stop'
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+$xml.LoadXml($env:SMART_TOOL_TOAST_XML)
+$toast = New-Object Windows.UI.Notifications.ToastNotification $xml
+if ($env:SMART_TOOL_TOAST_TAG) { $toast.Tag = $env:SMART_TOOL_TOAST_TAG; $toast.Group = 'smart-tool' }
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($env:SMART_TOOL_TOAST_APPID).Show($toast)
+"""
+
+
+def _pythonw():
+    candidate = os.path.join(os.path.dirname(sys.executable), "pythonw.exe")
+    return candidate if os.path.isfile(candidate) else sys.executable
+
+
+def action_command():
+    """The command the protocol runs; `%1` is the clicked link."""
+    return f'"{_pythonw()}" "{ACTION_SCRIPT}" "%1"'
+
+
+def register():
+    """Writes the HKCU keys (idempotent). Raises on any failure: a toast whose buttons do nothing is worse than none."""
+    import winreg
+    with winreg.CreateKey(winreg.HKEY_CURRENT_USER, rf"Software\Classes\AppUserModelId\{APP_ID}") as key:
+        winreg.SetValueEx(key, "DisplayName", 0, winreg.REG_SZ, "Smart Tool")
+    root = rf"Software\Classes\{PROTOCOL}"
+    with winreg.CreateKey(winreg.HKEY_CURRENT_USER, root) as key:
+        winreg.SetValueEx(key, None, 0, winreg.REG_SZ, "URL:Smart Tool action")
+        winreg.SetValueEx(key, "URL Protocol", 0, winreg.REG_SZ, "")
+    with winreg.CreateKey(winreg.HKEY_CURRENT_USER, root + r"\shell\open\command") as key:
+        winreg.SetValueEx(key, None, 0, winreg.REG_SZ, action_command())
+
+
+def unregister():
+    """Deletes the HKCU keys `register` wrote, deepest first; returns how many existed (missing keys are not an error)."""
+    import winreg
+    count = 0
+    for path in (rf"Software\Classes\{PROTOCOL}\shell\open\command", rf"Software\Classes\{PROTOCOL}\shell\open",
+                 rf"Software\Classes\{PROTOCOL}\shell", rf"Software\Classes\{PROTOCOL}",
+                 rf"Software\Classes\AppUserModelId\{APP_ID}"):
+        try:
+            winreg.DeleteKey(winreg.HKEY_CURRENT_USER, path)
+            count += 1
+        except FileNotFoundError:
+            pass
+    return count
+
+
+def action_uri(action, **params):
+    """The protocol link a button carries: `smart-tool-action:<action>?<params>`; returns the link as text."""
+    query = urllib.parse.urlencode(params)
+    return f"{PROTOCOL}:{action}" + (f"?{query}" if query else "")
+
+
+def toast_xml(title, lines, buttons):
+    """`buttons` is a list of (label, uri); each one launches its protocol link and closes the toast."""
+    text = "".join(f"<text>{escape(line)}</text>" for line in [title, *lines])
+    actions = "".join(
+        f'<action content={quoteattr(label)} arguments={quoteattr(uri)} activationType="protocol"/>'
+        for label, uri in buttons)
+    return (f'<toast><visual><binding template="ToastGeneric">{text}</binding></visual>'
+            f'<actions>{actions}</actions></toast>')
+
+
+def show(title, lines, buttons, tag=None):
+    """Shows the toast; raises RuntimeError with PowerShell's message when Windows refuses it."""
+    if sys.platform != "win32":
+        raise RuntimeError("Toast notifications are only available on Windows.")
+    register()
+    script = base64.b64encode(_SHOW_SCRIPT.encode("utf-16-le")).decode("ascii")
+    env = {**os.environ, "SMART_TOOL_TOAST_XML": toast_xml(title, lines, buttons),
+           "SMART_TOOL_TOAST_APPID": APP_ID, "SMART_TOOL_TOAST_TAG": tag or ""}
+    done = subprocess.run(
+        ["powershell.exe", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", script],
+        env=env, capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=30,
+        creationflags=subprocess.CREATE_NO_WINDOW)
+    if done.returncode:
+        raise RuntimeError(f"Windows refused the notification: {(done.stderr or done.stdout).strip()[:500]}")

package/tray.py

@@ -22,11 +22,13 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import autostart
 import config
 import daemon_launcher
+import toast_notice
 import update_check
 import version
 
 POLL_INTERVAL_S = 45
 UPDATE_CHECK_INTERVAL_S = 24 * 3600
+NOTICE_INTERVAL_S = 600
 SETUP_URL = "http://127.0.0.1:8765/setup"
 
 _STATE_LOCK = threading.Lock()
@@ -111,6 +113,42 @@ def _poll_loop(icon):
         time.sleep(POLL_INTERVAL_S)
 
 
+def _show_notices(icon, notices):
+    """Shows a toast for each pending notice: the new-default-models offer and each model over the failure limit."""
+    offer = notices.get("upgrade")
+    if offer:
+        lines = [f"{role}: {change['current']} -> {change['new']}" for role, change in offer["changes"].items()]
+        nonce = offer["nonce"]
+        toast_notice.show("Smart Tool has new recommended models", lines, [
+            ("Apply now", toast_notice.action_uri("models-apply", n=nonce)),
+            ("Don't show again", toast_notice.action_uri("models-decline", n=nonce)),
+        ], tag="models-upgrade")
+    for row in notices.get("failing") or []:
+        last = row.get("last_error") or "see the failure log in the settings"
+        toast_notice.show(
+            f"{row['model']} is failing", [f"{row['errors']} of {row['calls']} calls failed in 24 h as {row['role']}.", last[:160]],
+            [("Switch model", toast_notice.action_uri("open-setup", section="models")),
+             ("Mute 7 days", toast_notice.action_uri("mute-model", model=row["model"]))], tag="model-failing:" + row["model"])
+
+
+def _notice_loop(icon):
+    """Asks the daemon every 10 minutes whether a toast is due. The daemon decides (once a day per notice) and marks it
+    announced, so a restart of the tray never repeats one."""
+    while True:
+        try:
+            daemon_url = (daemon_launcher.read_registry() or {}).get("url")
+            if daemon_url:
+                request = urllib.request.Request(daemon_url.rstrip("/") + "/setup/notices", data=b"{}", method="POST",
+                                                 headers={"Content-Type": "application/json"})
+                with urllib.request.urlopen(request, timeout=60) as response:
+                    _show_notices(icon, json.load(response))
+        except Exception as exc:
+            if str(exc) != _state.get("notice_error"):
+                _state["notice_error"] = str(exc)
+                icon.notify(f"Could not show a Smart Tool notice: {exc}", "Smart Tool")
+        time.sleep(NOTICE_INTERVAL_S)
+
+
 def _announce_start(icon):
     """Tells the user, once per start, that Smart Tool was just updated or that the last automatic update failed."""
     updated = update_check.note_running_version()
@@ -304,6 +342,7 @@ def main():
     )
     threading.Thread(target=_poll_loop, args=(icon,), daemon=True).start()
     threading.Thread(target=_update_loop, args=(icon,), daemon=True).start()
+    threading.Thread(target=_notice_loop, args=(icon,), daemon=True).start()
     try:
         icon.run()
     finally:

package/version.py

@@ -1,7 +1,7 @@
 """Single source of the Smart Tool version and of the User-Agent sent to public APIs."""
 import re
 
-VERSION = "0.9.31"
+VERSION = "0.9.32"
 _CONTACT_RE = re.compile(r"^(?:[^\s@()<>;]+@[^\s@()<>;]+\.[^\s@()<>;]+|https?://[^\s()<>;]+)$")