claude-finops 0.13.0 → 0.14.0

package/README.md

@@ -204,14 +204,61 @@ billed at another model's rate.
   },
   "budgets": { "monthly_usd": null, "daily_usd": null, "per_project_usd": {} },
   "alert_thresholds_pct": [50, 75, 90, 100],
+  "guard": {                         // per-session token budget + the session guard hook
+    "session_tokens": null,          // billable tokens per Claude Code session; null => off
+    "warn_pct": [75, 80],            // warn (never block) as a session crosses these
+    "after_approval": "step",        // "step": ask again every step_pct; "once": never again
+    "step_pct": 25,
+    "projects": {}                   // {"/abs/path": {"session_tokens": n} | {"off": true}}
+  },
   "waste_rules": { /* thresholds for each detector */ },
   "anomaly":    { /* z-score and ratio triggers */ },
   "scorecard":  { /* the reference points each dimension is graded against */ }
 }
 ```
 
-The **Budgets** view edits limits, budgets and thresholds from the browser and writes
-them back to this file.
+The **Budgets** page has three numbered blocks (① money, ② tokens, ③ one conversation) and an
+Advanced section, folded away, for plan limits and alert thresholds. **How does this work?** (and
+the small **?** on each block) opens a short picture guide; it also opens by itself the first
+time. Values are saved to `~/.claude-finops/settings.local.json`. Each amount suggests values
+from your own last 30 days, accepts shorthand (`20M`, `500k`, `$3,000`), and explains a bad
+value before saving.
+
+**Live warnings** (inside block ③) is the optional session guard hook. Your budgets work
+without it; it only adds the warning and "continue?" prompt inside Claude Code.
+
+**Settings** (sidebar, Setup) stores the optional API keys used by **Billed vs local**, in
+`~/.claude-finops/secrets.local.json` (0600, the same file `--set-key` writes). The page only
+ever gets back whether a key is set, where from, and its last four characters. An environment
+variable (`ANTHROPIC_ADMIN_KEY`, `CURSOR_API_KEY`) takes priority over a stored key.
+
+### Per-session token budget and the session guard
+
+`guard.session_tokens` is a budget for one Claude Code session, in billable tokens (input +
+output + cache read + cache write, the same figure as the Tokens column in Sessions). Cache
+reads dominate long sessions, which is exactly what a session cap is for. A project override
+(matched on the project path; the most specific path wins) sets a different budget or turns
+it off for that project.
+
+With a budget set, **Budgets** shows the largest session this billing period against its
+budget and how many sessions went over, and the dots in **Sessions** mark sessions at 75%
+(amber) and 100% (red) of theirs.
+
+The **session guard** is an opt-in Claude Code `PreToolUse` hook (`--install-guard`, or
+**Install** under Live warnings on the Budgets page, block ③). Before each tool call it counts the session's tokens
+from its transcript (only the lines added since the last call), and:
+
+- below the budget, warns you once at each `warn_pct` and suggests `/compact` to Claude;
+- at 100%, asks you to approve the next tool call; after you approve, it asks again every
+  `step_pct` (`"step"`) or not at all for that session (`"once"`). If you decline, it asks
+  again on the next tool call.
+
+Checked on Claude Code 2.1.284: the approval prompt appears in the default mode, in
+`--dangerously-skip-permissions` (bypass) mode, and for tools on your allow list. In
+non-interactive `claude -p` there is nobody to ask, so the tool call is refused. A hook cannot
+end a session, and the guard fails open: if it errors or cannot read the transcript, the tool
+call goes ahead. It keeps a small state file per session in `~/.claude-finops/data/guard/`
+(deleted after 30 days).
 
 Note on `waste_rules.low_output_ratio_vs_median`: sessions are flagged relative to
 *your own* median output ratio rather than an absolute number, because a healthy ratio
@@ -277,6 +324,8 @@ claude-finops --set-key       store a provider API key (hidden prompt, 0600)
 claude-finops --keys          which provider keys are configured
 claude-finops --install-statusline    model, context % and 5-hour limit under every prompt
 claude-finops --uninstall-statusline  remove it again
+claude-finops --install-guard         warn near, and ask at, your per-session token budget
+claude-finops --uninstall-guard       remove it again
 claude-finops --help          everything
 ```
 
@@ -328,7 +377,8 @@ The app makes exactly one outbound request of its own: once a day it asks
 you when an upgrade is out (npm has no way to push one at you). It sends nothing
 about you or your usage. Turn it off with `NO_UPDATE_NOTIFIER=1` or
 `CLAUDE_FINOPS_NO_UPDATE_CHECK=1`. Provider cost APIs are called only if you
-configure a key with `--set-key`.
+configure a key (with `--set-key` or on the Settings page), and only
+when you click Refresh on Billed vs local.
 
 ---
 
@@ -390,6 +440,30 @@ files on Windows.
 - **Install statusline** (Act now, or `--install-statusline`) adds a `statusLine` entry to
   `~/.claude/settings.json`, keeping a `.finops-backup` copy. It won't replace a statusline you
   already have.
+- **Install** under Live warnings (Budgets, block ③, or `--install-guard`) adds one `PreToolUse` hook entry to
+  `~/.claude/settings.json`, keeping a `.finops-backup` copy. Your other hooks are left
+  alone, and uninstalling removes only that entry.
+
+---
+
+## Jev (fast decisions)
+
+[Jev](https://docs.typesafe.ai) is TypeSafe AI's "System One" model: very fast, very cheap typed
+decisions (pick one, yes or no, a score, a value). It does not write text or code, so it does not
+make Claude Code itself cheaper; it makes the apps and scripts you build cheaper where an LLM call
+only decides something.
+
+The **Jev (fast decisions)** page (sidebar, Optimize):
+
+- **Install** runs Claude Code's own plugin manager, after showing you the commands:
+  `claude plugin marketplace add typesafe-ai/skills` then `claude plugin install typesafe@typesafe-ai`.
+  **Uninstall** runs `claude plugin uninstall typesafe@typesafe-ai`.
+- **API key** is saved as `env.TYPESAFE_API_KEY` in `~/.claude/settings.json` (backed up first,
+  nothing else changed), so new Claude Code sessions can use it. The page only ever gets back
+  its last four characters. A key exported in your shell takes priority.
+- **Where Jev fits** counts your Claude Code prompts that were really just a decision (short, no
+  tools, worded as "which one", "yes or no", "classify"…) and what they would cost at TypeSafe's
+  published price ($0.042 per million input tokens). Read-only.
 
 ---
 

package/config/settings.json

@@ -30,6 +30,15 @@
     90,
     100
   ],
+  "guard": {
+    "_comment": "Per-session token budget (billable tokens) and the opt-in session guard hook (claude-finops --install-guard). session_tokens null => no per-session budget and the guard allows everything. projects maps an absolute project path to {\"session_tokens\": n} or {\"off\": true}; sessions maps one Claude Code session id to the same (set from Running sessions, forgotten after 30 days).",
+    "session_tokens": null,
+    "warn_pct": [75, 80],
+    "after_approval": "step",
+    "step_pct": 25,
+    "projects": {},
+    "sessions": {}
+  },
   "waste_rules": {
     "long_prompt_chars": 6000,
     "large_context_tokens": 150000,

package/finops/analytics.py

@@ -124,6 +124,9 @@ def _validate_settings(cur, defaults):
         if pct is not None:
             bad.append("alert_thresholds_pct")
         cur["alert_thresholds_pct"] = defaults.get("alert_thresholds_pct", [])
+    from .guard import validate_guard
+    cur["guard"], guard_bad = validate_guard(cur.get("guard"), defaults.get("guard"))
+    bad += guard_bad
     for path in bad:
         print(f"finops: settings.local.json has an invalid '{path}'; using the shipped default",
               file=sys.stderr)
@@ -571,7 +574,8 @@ class Analytics:
         rows = self.q(f"""
           SELECT s.id session_id, s.title, s.git_branch, s.cli_version, s.started_at,
                  s.ended_at, s.duration_s, s.files_touched, pr.name project, pr.id project_id,
-                 s.agent, s.source_file,
+                 s.agent, s.source_file, pr.path project_path,
+                 s.billable_tokens session_tokens,
                  COUNT(DISTINCT r.prompt_id) prompts, COUNT(*) requests,
                  SUM(r.tool_call_count) tool_calls,
                  SUM(r.input_tokens) input_tokens, SUM(r.output_tokens) output_tokens,
@@ -590,9 +594,21 @@ class Analytics:
             r["output_ratio"] = (r["output_tokens"] or 0) / r["tokens"] if r["tokens"] else 0
             cr, cw = r["cache_read_tokens"] or 0, r["cache_write_tokens"] or 0
             r["cache_hit_ratio"] = (cr / (cr + cw)) if (cr + cw) else None
+            r["budget_tokens"] = self.session_budget(r["agent"], r.pop("project_path"), r["session_id"])
             r["resume"] = resume_command(r["session_id"], r.pop("agent"), r.pop("source_file"))
         return rows
 
+    def session_budget(self, agent, project_path, session_id=None):
+        """The per-session token budget that applies to a session, or None.
+
+        Claude Code sessions only: the guard hook runs there, and other agents'
+        sessions are not what the budget was set for.
+        """
+        if agent != "claude":
+            return None
+        from .guard import budget_for
+        return budget_for(self.settings.get("guard") or {}, project_path, session_id)
+
     def sessions_total(self, f=None):
         w, p = self.where(f)
         return self.one(f"SELECT COUNT(DISTINCT s.id) n FROM requests r "
@@ -1575,11 +1591,18 @@ class Analytics:
                     "thresholds_breached": breached, "thresholds_forecast_breach": fbreach,
                     "unit": unit}
 
+        out["suggest"] = self.budget_suggestions(f)
         fc_cost = fc.get("scenarios", {}).get("expected", {}).get("end_of_period_cost")
         out["lines"].append(line("Monthly spend", b.get("monthly_usd"), period["c"], fc_cost))
         out["lines"].append(line("Daily spend", b.get("daily_usd"), today["c"], today["c"]))
         out["lines"].append(line("Monthly tokens", b.get("monthly_tokens"), period["t"],
                                  fc.get("end_of_period_tokens"), unit="tokens"))
+        g = self.settings.get("guard") or {}
+        from .guard import has_any_budget
+        if has_any_budget(g):
+            out["lines"].append(self._session_budget_line(f, bp, line))
+        else:
+            out["lines"].append(line("Per-session tokens", None, 0, None, unit="tokens"))
         for proj, bud in (b.get("per_project_usd") or {}).items():
             act = self.one("""SELECT COALESCE(SUM(r.est_cost_usd),0) c FROM requests r
                               JOIN projects pr ON pr.id=r.project_id
@@ -1593,6 +1616,59 @@ class Analytics:
             out["lines"].append(line(f"Model: {self.pricing.display_name(model)}", bud, act, None))
         return out
 
+    def budget_suggestions(self, f=None):
+        """Figures the Budgets form offers as suggestions: recent spend and session sizes.
+
+        Last 30 days up to today, under the current filter; session sizes are Claude Code
+        sessions' whole-session billable tokens (a sorted sample, at most 2,000 values),
+        so the page can say how many past sessions a budget would have caught.
+        """
+        w, p = self.where(f)
+        start = (self.today() - timedelta(days=29)).isoformat()
+        days = [r["c"] for r in self.q(
+            f"SELECT r.day, SUM(r.est_cost_usd) c FROM requests r WHERE {w} AND r.day >= ? "
+            f"GROUP BY r.day", p + [start])]
+        tot = self.one(f"SELECT COALESCE(SUM(r.est_cost_usd),0) c, COALESCE(SUM(r.billable_tokens),0) t "
+                       f"FROM requests r WHERE {w} AND r.day >= ?", p + [start])
+        sizes = [r["t"] for r in self.q(
+            "SELECT billable_tokens t FROM sessions WHERE agent='claude' AND billable_tokens > 0 "
+            "ORDER BY t")]
+        if len(sizes) > 2000:
+            step = len(sizes) / 2000.0
+            sizes = [sizes[int(i * step)] for i in range(2000)]
+        days.sort()
+        return {"spend_30d": round(tot["c"], 2), "tokens_30d": tot["t"],
+                "daily_avg": round(tot["c"] / 30.0, 2),
+                "daily_p90": round(days[min(len(days) - 1, int(len(days) * 0.9))], 2) if days else 0,
+                "session_tokens": sizes}
+
+    def _session_budget_line(self, f, bp, line):
+        """Largest Claude Code session this period against its own budget, and who went over."""
+        w, p = self.where(f)
+        rows = self.q(f"""SELECT s.id session_id, s.title, pr.name project, pr.path path,
+                                 s.billable_tokens tokens
+                          FROM sessions s JOIN projects pr ON pr.id = s.project_id
+                          WHERE s.agent = 'claude' AND s.id IN (
+                            SELECT r.session_id FROM requests r
+                            WHERE {w} AND r.day >= ? AND r.day <= ?)""",
+                      p + [bp["start"], bp["end"]])
+        scored = []
+        for r in rows:
+            bud = self.session_budget("claude", r.pop("path"), r["session_id"])
+            if bud:
+                r["budget"], r["pct"] = bud, round(100.0 * (r["tokens"] or 0) / bud, 1)
+                scored.append(r)
+        scored.sort(key=lambda r: r["pct"], reverse=True)
+        top = scored[0] if scored else None
+        g = self.settings.get("guard") or {}
+        ln = line("Per-session tokens", top["budget"] if top else g.get("session_tokens"),
+                  top["tokens"] if top else 0, None, unit="tokens")
+        over = [r for r in scored if r["pct"] >= 100]
+        ln["sessions_over"] = len(over)
+        ln["top_over"] = over[:5]
+        ln["basis"] = "largest session this period vs its budget"
+        return ln
+
     # ---------------- anomalies ----------------
     def anomalies(self, f=None):
         w, p = self.where(f)
@@ -1891,7 +1967,7 @@ class Analytics:
         return {
             "agents": self.agents(),
             "models": self.q("SELECT model, agent, COUNT(*) n FROM requests GROUP BY 1 ORDER BY 3 DESC"),
-            "projects": self.q("SELECT pr.id project_id, pr.name, pr.is_sandbox, pr.agent, COUNT(r.id) n"
+            "projects": self.q("SELECT pr.id project_id, pr.name, pr.path, pr.is_sandbox, pr.agent, COUNT(r.id) n"
                                " FROM projects pr LEFT JOIN requests r ON r.project_id=pr.id"
                                " GROUP BY pr.id HAVING n>0 ORDER BY n DESC"),
             "categories": self.q("SELECT category, COUNT(*) n FROM prompts GROUP BY 1 ORDER BY 2 DESC"),

package/finops/api.py

@@ -38,7 +38,7 @@ def _int(qs, key, default, lo=0, hi=1_000_000):
 
 SETTINGS_SHAPE = {
     "budgets": dict, "limits": dict, "alert_thresholds_pct": list, "waste_rules": dict,
-    "anomaly": dict, "scorecard": dict, "account": dict, "billing_period": dict,
+    "anomaly": dict, "scorecard": dict, "account": dict, "billing_period": dict, "guard": dict,
 }
 
 
@@ -62,6 +62,89 @@ def _validate_thresholds(v):
     if not all(_is_num(x) and 0 <= x <= 1000 for x in v):
         raise BadRequest("alert_thresholds_pct must be a list of numbers 0..1000")
 
+def _validate_guard(v):
+    from .guard import validate_guard
+    _, bad = validate_guard(v, {})
+    if bad:
+        raise BadRequest(f"invalid {', '.join(bad)}: session_tokens > 0 or null, warn_pct "
+                         "numbers between 0 and 100, after_approval step|once, step_pct 1..1000, "
+                         "projects {path: {session_tokens: n} | {off: true}}")
+
+class NotFound(BadRequest):
+    """A 404 raised from a helper; handled next to BadRequest."""
+
+
+def _session_transcript(sid):
+    from . import guard as G
+    from .etl import DEFAULT_SOURCE
+    if not G.SAFE_ID.match(sid or ""):
+        raise BadRequest("That is not a Claude Code session id.")
+    tp = G.find_transcript(sid, [os.environ.get("CLAUDE_PROJECTS") or DEFAULT_SOURCE])
+    if not tp:
+        raise NotFound("No Claude Code transcript found for that session.")
+    return tp
+
+
+def _session_limit_status(a, sid):
+    """GET /api/guard/session/<id>: tokens used so far (as the guard counts them),
+    this session's own limit, the budget that applies, and whether the hook is installed."""
+    from . import guard as G
+    from .integrate import guard_state
+    tp = _session_transcript(sid)
+    cwd = None
+    with open(tp, errors="replace") as fh:
+        for i, line in enumerate(fh):
+            if '"cwd"' in line:
+                try:
+                    cwd = json.loads(line).get("cwd")
+                except ValueError:
+                    pass
+            if cwd or i > 50:
+                break
+    cfg = a.settings.get("guard") or {}
+    try:
+        installed = guard_state() == "installed"
+    except Exception:
+        installed = False
+    return {"session_id": sid, "tokens": G.session_usage(tp, sid),
+            "limit": (cfg.get("sessions") or {}).get(sid), "applies": G.budget_for(cfg, cwd, sid),
+            "installed": installed}
+
+
+def _set_session_limit(sid, payload):
+    """POST /api/do/session_limit/<id>: {session_tokens: n} | {off: true} | {remove: true}."""
+    global A
+    from . import guard as G
+    import time
+    if not G.SAFE_ID.match(sid or ""):
+        raise BadRequest("That is not a Claude Code session id.")
+    if payload.get("remove"):
+        entry = None
+    elif payload.get("off") is True:
+        entry = {"off": True}
+    elif _is_num(payload.get("session_tokens")) and payload["session_tokens"] > 0:
+        entry = {"session_tokens": payload["session_tokens"]}
+    else:
+        raise BadRequest("Enter a token limit above 0, or turn the guard off for this session.")
+    local = {}
+    if os.path.exists(LOCAL_SETTINGS_PATH):
+        with open(LOCAL_SETTINGS_PATH) as fh:
+            local = json.load(fh)
+    g = local.setdefault("guard", {})
+    sessions = dict(g.get("sessions") or {})
+    if entry is None:
+        sessions.pop(sid, None)
+    else:
+        sessions[sid] = dict(entry, set_at=time.strftime("%Y-%m-%dT%H:%M:%S"))
+    g["sessions"] = G.prune_sessions(sessions)
+    with open(LOCAL_SETTINGS_PATH, "w") as fh:
+        json.dump(local, fh, indent=2)
+    cur = load_settings()
+    with _lock:
+        A.settings = cur
+    return {"ok": True, "limit": g["sessions"].get(sid)}
+
+
 MIME = {".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8",
         ".css": "text/css; charset=utf-8", ".json": "application/json",
         ".svg": "image/svg+xml", ".ico": "image/x-icon"}
@@ -218,6 +301,8 @@ class Handler(BaseHTTPRequestHandler):
                         _validate_numeric_section(section, payload[section])
                 if "alert_thresholds_pct" in payload:
                     _validate_thresholds(payload["alert_thresholds_pct"])
+                if "guard" in payload:
+                    _validate_guard(payload["guard"])
                 # UI edits go to the gitignored per-machine file, never the shared defaults
                 local = {}
                 if os.path.exists(LOCAL_SETTINGS_PATH):
@@ -225,7 +310,7 @@ class Handler(BaseHTTPRequestHandler):
                         local = json.load(fh)
                 for k, v in payload.items():
                     if k in ("budgets", "limits", "alert_thresholds_pct", "waste_rules",
-                             "anomaly", "scorecard", "account", "billing_period"):
+                             "anomaly", "scorecard", "account", "billing_period", "guard"):
                         if isinstance(v, dict) and isinstance(local.get(k), dict):
                             local[k].update(v)
                         else:
@@ -238,7 +323,7 @@ class Handler(BaseHTTPRequestHandler):
                 return self.send_json({"ok": True, "settings": cur})
             self.send_json({"error": "unknown endpoint"}, 404)
         except BadRequest as e:
-            self.send_json({"error": str(e)}, 400)
+            self.send_json({"error": str(e)}, 404 if isinstance(e, NotFound) else 400)
         except Exception:
             log.exception("POST %s failed", path)
             self.send_json({"error": "internal error; see data/server.log"}, 500)
@@ -273,6 +358,34 @@ class Handler(BaseHTTPRequestHandler):
         if parts == ["statusline"]:
             from .integrate import install_statusline
             return self.send_json(install_statusline())
+        if len(parts) == 2 and parts[0] == "session_limit":
+            return self.send_json(_set_session_limit(parts[1], payload))
+        if parts in (["jev", "install"], ["jev", "uninstall"]):
+            from . import jev
+            return self.send_json({"job": X._job(jev.install if parts[1] == "install" else jev.uninstall)["id"]})
+        if parts == ["jev", "key"]:
+            from . import jev
+            try:
+                if payload.get("remove"):
+                    jev.remove_key()
+                else:
+                    jev.save_key(payload.get("value") if isinstance(payload.get("value"), str) else "")
+            except ValueError as e:
+                raise BadRequest(str(e))
+            return self.send_json({"ok": True, "key": jev.key_status()})
+        if len(parts) == 2 and parts[0] == "key":
+            from .cloud import save_key, key_status
+            value = payload.get("value")
+            if not payload.get("remove") and not (isinstance(value, str) and value.strip()):
+                raise BadRequest("Paste a key, or use Remove.")
+            try:
+                save_key(parts[1], "" if payload.get("remove") else value)
+            except ValueError as e:
+                raise BadRequest(str(e))
+            return self.send_json({"ok": True, "keys": key_status()})
+        if parts == ["guard"]:
+            from .integrate import install_guard
+            return self.send_json(install_guard(remove=bool(payload.get("remove"))))
         if len(parts) == 2 and parts[0] == "mcp":
             return self.send_json(X.add_mcp(parts[1], payload))
         return self.send_json({"error": "unknown action"}, 404)
@@ -357,7 +470,7 @@ class Handler(BaseHTTPRequestHandler):
         except BrokenPipeError:
             pass
         except BadRequest as e:
-            self.send_json({"error": str(e) or "bad request"}, 400)
+            self.send_json({"error": str(e) or "bad request"}, 404 if isinstance(e, NotFound) else 400)
         except Exception:
             log.exception("GET %s failed", path)
             self.send_json({"error": "internal error; see data/server.log"}, 500)
@@ -382,6 +495,11 @@ class Handler(BaseHTTPRequestHandler):
             from .cloud import configured
             o = a.options()
             o["cloud"] = configured()          # nav hides "Billed vs local" until a key exists
+            from .integrate import guard_state
+            try:
+                o["guard_installed"] = guard_state() == "installed"
+            except Exception:
+                o["guard_installed"] = False
             return self.send_json(o)
         if route == "by_agent":
             return self.send_json(a.by_agent(f))
@@ -457,6 +575,14 @@ class Handler(BaseHTTPRequestHandler):
                 if not want or any(x != "claude" for x in want) else []
             rows = sorted(claude + others, key=lambda x: -(x.get("context") or 0))
             return self.send_json({"sessions": rows, "actions": list(ACTIONS)})
+        if route.startswith("guard/session/"):
+            return self.send_json(_session_limit_status(a, route[len("guard/session/"):]))
+        if route == "jev":
+            from . import jev
+            return self.send_json({"status": jev.status(), "key": jev.key_status(), "fit": jev.fit(a, f)})
+        if route == "keys":
+            from .cloud import key_status
+            return self.send_json(key_status())
         if route == "cloud":
             from .cloud import report
             return self.send_json(report(a, _int(qs, "days", 30)))

package/finops/cloud.py

@@ -3,9 +3,10 @@
 Everything else in this dashboard reads local files. This module is the one part that
 talks to the internet, and only when you ask it to (the Refresh button / --cloud-sync).
 
-Keys are never stored by the UI. Put them in the environment, or store one with
-`claude-finops --set-key`, which writes ~/.claude-finops/secrets.local.json (0600,
-outside the install tree, never packaged):
+Keys come from the environment, or are stored with `claude-finops --set-key` or the
+API keys section on the Budgets page. Both write ~/.claude-finops/secrets.local.json
+(0600, outside the install tree, never packaged); the dashboard never sends a stored
+key back to the browser, only whether it is set and its last four characters:
 
     {"anthropic_admin_key": "sk-ant-admin...", "cursor_api_key": "key_..."}
 
@@ -65,6 +66,53 @@ def configured():
     return {k: bool(key_for(k)) for k in PROVIDERS}
 
 
+# A light shape check, to catch pasting the wrong thing: not a validity test.
+KEY_SHAPES = {
+    "anthropic": (lambda v: v.startswith("sk-ant-admin"),
+                  "An Anthropic Admin key starts with sk-ant-admin (a regular API key will not work)."),
+    "cursor": (lambda v: len(v) >= 16, "That looks too short for a Cursor Admin API key."),
+}
+
+
+def key_status():
+    """Per provider: where the key comes from and its last four characters. Never the key."""
+    stored = _secrets()
+    out = {}
+    for pid, p in PROVIDERS.items():
+        env, val = os.environ.get(p["env"]), stored.get(p["field"])
+        src = "env" if env else "stored" if val else None
+        key = env or val or ""
+        out[pid] = {"name": p["name"], "env": p["env"], "how": p["how"], "covers": p["covers"],
+                    "source": src, "last4": key[-4:] if len(key) >= 12 else None}
+    return out
+
+
+def save_key(provider, value):
+    """Store (value) or remove (empty value) one provider key in the 0600 secrets file.
+
+    Raises ValueError for an unknown provider or a value that fails the shape check.
+    """
+    if provider not in PROVIDERS:
+        raise ValueError(f"unknown provider {provider!r}")
+    value = (value or "").strip()
+    if value:
+        if any(ch.isspace() for ch in value):
+            raise ValueError("A key has no spaces or line breaks in it.")
+        ok, msg = KEY_SHAPES.get(provider, (lambda v: True, ""))
+        if not ok(value):
+            raise ValueError(msg)
+    data = _secrets()
+    if value:
+        data[PROVIDERS[provider]["field"]] = value
+    else:
+        data.pop(PROVIDERS[provider]["field"], None)
+    os.makedirs(os.path.dirname(SECRETS_PATH), exist_ok=True)
+    fd = os.open(SECRETS_PATH, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        json.dump(data, fh, indent=2)
+    os.chmod(SECRETS_PATH, 0o600)      # O_CREAT's mode only applies to a new file
+
+
 def _get(url, headers, data=None, method="GET"):
     req = urllib.request.Request(url, data=data, method=method,
                                  headers={"User-Agent": UA, **headers})