claude-finops 0.12.0 → 0.14.0

package/finops/guard.py

@@ -0,0 +1,412 @@
+"""Session guard: a PreToolUse hook that keeps a human in the loop on token-heavy sessions.
+
+  claude-finops --guard            invoked by Claude Code before every tool call
+  claude-finops --install-guard    wire it into ~/.claude/settings.json (see integrate.py)
+
+It counts the session's billable tokens (input + output + cache read + cache
+write, the same figure as the dashboard's Tokens column) straight from the
+transcript, reading only what was appended since the last call. Below the
+budget it warns once at each configured percentage; at the budget it asks the
+user to approve the next tool call, then again every step_pct (or never, in
+"once" mode).
+
+A hook cannot end a session, and this one never blocks on its own failure:
+anything unexpected means exit 0 with no output, so Claude Code carries on as
+if the guard were not installed.
+"""
+import glob
+import json
+import os
+import re
+import sys
+import time
+
+from .paths import DATA_DIR, SETTINGS_PATH, LOCAL_SETTINGS_PATH
+
+try:
+    import fcntl
+except ImportError:          # Windows: no advisory locks, concurrent calls are rare there
+    fcntl = None
+
+STATE_DIR = os.path.join(DATA_DIR, "guard")
+MAX_READ = 64 * 1024 * 1024      # new bytes read per call; the rest waits for the next call
+STALE_S = 30 * 86400
+SWEEP_S = 3600
+SESSION_KEEP_S = 30 * 86400          # a per-session limit is forgotten after this long
+SAFE_ID = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+REJECTED = ("User rejected tool use", "The user doesn't want to proceed with this tool use")
+
+
+# ---------------------------------------------------------------- settings ----
+
+def _num(v):
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def validate_guard(g, default):
+    """Clean a guard block. Returns (cleaned, [bad paths]); bad leaves use the default."""
+    default = default or {}
+    if not isinstance(g, dict):
+        return json.loads(json.dumps(default)), (["guard"] if g is not None else [])
+    out, bad = dict(default), []
+    for k, v in g.items():
+        if k.startswith("_"):
+            out[k] = v
+        elif k == "session_tokens":
+            if v is None or (_num(v) and v > 0):
+                out[k] = v
+            else:
+                bad.append(f"guard.{k}")
+        elif k == "warn_pct":
+            if isinstance(v, list) and all(_num(x) and 0 < x < 100 for x in v):
+                out[k] = sorted(set(v))
+            else:
+                bad.append(f"guard.{k}")
+        elif k == "after_approval":
+            if v in ("step", "once"):
+                out[k] = v
+            else:
+                bad.append(f"guard.{k}")
+        elif k == "step_pct":
+            if _num(v) and 1 <= v <= 1000:
+                out[k] = v
+            else:
+                bad.append(f"guard.{k}")
+        elif k == "sessions":
+            if not isinstance(v, dict):
+                bad.append(f"guard.{k}")
+                continue
+            sessions = {}
+            for sid, o in v.items():
+                keep = {"set_at": o["set_at"]} if isinstance(o, dict) and isinstance(o.get("set_at"), str) else {}
+                if not SAFE_ID.match(str(sid)):
+                    bad.append(f"guard.sessions.{sid}")
+                elif isinstance(o, dict) and o.get("off") is True:
+                    sessions[sid] = dict(keep, off=True)
+                elif isinstance(o, dict) and _num(o.get("session_tokens")) and o["session_tokens"] > 0:
+                    sessions[sid] = dict(keep, session_tokens=o["session_tokens"])
+                else:
+                    bad.append(f"guard.sessions.{sid}")
+            out[k] = sessions
+        elif k == "projects":
+            if not isinstance(v, dict):
+                bad.append(f"guard.{k}")
+                continue
+            projects = {}
+            for path, o in v.items():
+                if isinstance(o, dict) and o.get("off") is True:
+                    projects[path] = {"off": True}
+                elif isinstance(o, dict) and _num(o.get("session_tokens")) and o["session_tokens"] > 0:
+                    projects[path] = {"session_tokens": o["session_tokens"]}
+                else:
+                    bad.append(f"guard.projects.{path}")
+            out[k] = projects
+        else:
+            out[k] = v
+    return out, bad
+
+
+def load_guard_settings():
+    """The guard block only: shipped default + settings.local.json, validated.
+
+    Deliberately not analytics.load_settings(): that also detects the account
+    from ~/.claude.json, which the hook has no use for on every tool call.
+    """
+    with open(SETTINGS_PATH) as fh:
+        default = json.load(fh).get("guard") or {}
+    local = {}
+    try:
+        with open(LOCAL_SETTINGS_PATH) as fh:
+            local = json.load(fh).get("guard") or {}
+    except (OSError, ValueError, AttributeError):
+        pass
+    merged = dict(default)
+    if isinstance(local, dict):
+        merged.update(local)
+    return validate_guard(merged, default)[0]
+
+
+def _norm(p):
+    return os.path.normcase(os.path.realpath(os.path.expanduser(p)))
+
+
+def prune_sessions(sessions, now=None):
+    """Drop per-session limits set more than 30 days ago (entries without a date stay)."""
+    now = now or time.time()
+    out = {}
+    for sid, o in (sessions or {}).items():
+        try:
+            age = now - time.mktime(time.strptime(o["set_at"], "%Y-%m-%dT%H:%M:%S"))
+        except (KeyError, TypeError, ValueError):
+            age = 0
+        if age <= SESSION_KEEP_S:
+            out[sid] = o
+    return out
+
+
+def has_any_budget(cfg):
+    """Is any per-session budget set: global, a project override, or one session's own?"""
+    return bool(cfg.get("session_tokens")) or any(
+        o.get("session_tokens") for sect in ("projects", "sessions")
+        for o in (cfg.get(sect) or {}).values())
+
+
+def budget_for(cfg, cwd, session_id=None):
+    """The budget that applies: this session's own limit, else the most specific
+    project override, else the global one."""
+    own = (cfg.get("sessions") or {}).get(session_id) if session_id else None
+    if own is not None:
+        return None if own.get("off") else own.get("session_tokens")
+    best, best_len = None, -1
+    if cwd:
+        here = _norm(cwd)
+        for path, o in (cfg.get("projects") or {}).items():
+            p = _norm(path)
+            if (here == p or here.startswith(p.rstrip(os.sep) + os.sep)) and len(p) > best_len:
+                best, best_len = o, len(p)
+    if best is not None:
+        return None if best.get("off") else best.get("session_tokens")
+    return cfg.get("session_tokens")
+
+
+# ---------------------------------------------------------------- counting ----
+
+def billable(u):
+    cc = u.get("cache_creation") or {}
+    cw = int(u.get("cache_creation_input_tokens") or 0) or (
+        int(cc.get("ephemeral_5m_input_tokens") or 0) + int(cc.get("ephemeral_1h_input_tokens") or 0))
+    return (int(u.get("input_tokens") or 0) + int(u.get("output_tokens") or 0)
+            + int(u.get("cache_read_input_tokens") or 0) + cw)
+
+
+def session_files(transcript_path, session_id):
+    """The transcript plus its subagents' transcripts, which the dashboard counts too."""
+    files = [transcript_path]
+    sub = os.path.join(os.path.dirname(transcript_path), session_id, "subagents")
+    files += sorted(glob.glob(os.path.join(sub, "*.jsonl")))
+    return files
+
+
+def _read_new(path, fs, budget_left, on_row):
+    """Feed complete lines appended since fs["offset"] to on_row. Returns bytes read."""
+    try:
+        size = os.path.getsize(path)
+    except OSError:
+        return 0
+    if size < fs.get("offset", 0):          # rewritten: start over
+        fs["offset"] = 0
+        fs.setdefault("requests", {}).clear()
+    if size == fs.get("offset", 0) or budget_left <= 0:
+        return 0
+    with open(path, "rb") as fh:
+        fh.seek(fs.get("offset", 0))
+        chunk = fh.read(min(size - fs.get("offset", 0), budget_left))
+    end = chunk.rfind(b"\n")
+    if end < 0:
+        return 0                               # a partial line: wait for the rest
+    for raw in chunk[:end].split(b"\n"):
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            row = json.loads(raw)
+        except ValueError:
+            continue
+        if isinstance(row, dict):
+            on_row(row)
+    fs["offset"] = fs.get("offset", 0) + end + 1
+    return end + 1
+
+
+def count_session(transcript_path, session_id, state, pending_tool=None):
+    """Update state["files"] with newly appended lines; return (total billable, tool outcome).
+
+    Each API request is counted once, from the last line carrying its usage (the
+    ETL keys requests the same way: requestId, else message.id, else uuid). The
+    outcome is "approved"/"rejected" once the result of pending_tool appears.
+    """
+    files = state.setdefault("files", {})
+    outcome = []
+    left = MAX_READ
+    for path in session_files(transcript_path, session_id):
+        fs = files.setdefault(path, {"offset": 0, "requests": {}})
+        reqs = fs.setdefault("requests", {})
+
+        def on_row(r):
+            msg = r.get("message") if isinstance(r.get("message"), dict) else {}
+            if r.get("type") == "assistant" and isinstance(msg.get("usage"), dict):
+                key = r.get("requestId") or msg.get("id") or r.get("uuid")
+                if key:
+                    reqs[key] = billable(msg["usage"])
+            elif pending_tool and r.get("type") == "user":
+                for c in msg.get("content") or []:
+                    if isinstance(c, dict) and c.get("type") == "tool_result" \
+                            and c.get("tool_use_id") == pending_tool:
+                        text = json.dumps(c.get("content")) + json.dumps(r.get("toolUseResult"))
+                        outcome.append("rejected" if any(s in text for s in REJECTED) else "approved")
+
+        left -= _read_new(path, fs, left, on_row)
+    total = sum(sum(f.get("requests", {}).values()) for f in files.values())
+    return total, (outcome[-1] if outcome else None)
+
+
+def session_usage(transcript_path, session_id):
+    """The session's billable tokens, counted like the hook does, without saving state."""
+    state = {}
+    while True:
+        before = {p: f.get("offset", 0) for p, f in state.get("files", {}).items()}
+        total, _ = count_session(transcript_path, session_id, state)
+        after = {p: f.get("offset", 0) for p, f in state.get("files", {}).items()}
+        if after == before:                    # nothing new read: the whole session is counted
+            return total
+
+
+def find_transcript(session_id, roots):
+    """<root>/<project>/<session_id>.jsonl for a Claude Code session id, or None."""
+    if not SAFE_ID.match(str(session_id or "")):
+        return None
+    for root in roots:
+        hits = glob.glob(os.path.join(root, "*", f"{session_id}.jsonl"))
+        if hits:
+            return hits[0]
+    return None
+
+
+# ---------------------------------------------------------------- deciding ----
+
+def fmt_tokens(n):
+    for div, unit in ((1e9, "B"), (1e6, "M"), (1e3, "k")):
+        if n >= div:
+            s = f"{n / div:.1f}".rstrip("0").rstrip(".")
+            return f"{s}{unit}"
+    return str(int(n))
+
+
+def next_ask(cfg, state):
+    approved = state.get("approved_pct")
+    if approved is None:
+        return 100
+    if cfg.get("after_approval") == "once":
+        return None
+    return approved + (cfg.get("step_pct") or 25)
+
+
+def decide(total, budget, cfg, state, outcome=None, tool_use_id=None):
+    """The hook's answer for this tool call (a dict to print), or None to stay silent."""
+    if not budget:
+        return None
+    if state.get("asked_at") is not None and outcome == "approved":
+        state["approved_pct"], state["asked_at"], state["asked_tool"] = state["asked_at"], None, None
+    elif outcome == "rejected":
+        state["asked_at"], state["asked_tool"] = None, None     # declined: ask again next time
+    pct = 100.0 * total / budget
+    level = next_ask(cfg, state)
+    if level is not None and pct >= level:
+        state["asked_at"], state["asked_tool"] = level, tool_use_id
+        # the ask supersedes any warning it jumped past; don't replay them after approval
+        state["warned"] = sorted(set(state.get("warned") or [])
+                                 | {w for w in (cfg.get("warn_pct") or []) if pct >= w})
+        after = next_ask(cfg, dict(state, approved_pct=level))
+        hint = (f"Approving continues until {after:g}%." if after is not None
+                else "Approving turns the guard off for the rest of this session.")
+        return {"hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "ask",
+            "permissionDecisionReason":
+                f"Session guard: this session has used {fmt_tokens(total)} tokens, "
+                f"{pct:.0f}% of its {fmt_tokens(budget)} budget. Allow this tool call? {hint}"}}
+    warned = set(state.get("warned") or [])
+    crossed = [w for w in (cfg.get("warn_pct") or []) if pct >= w and w not in warned]
+    if crossed:
+        state["warned"] = sorted(warned | set(crossed))
+        return {"systemMessage": f"Session guard: {fmt_tokens(total)} tokens, {pct:.0f}% of "
+                                 f"this session's {fmt_tokens(budget)} budget.",
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "additionalContext":
+                        f"This session has used {pct:.0f}% of its token budget. At a natural "
+                        "break, suggest the user run /compact or start a fresh session."}}
+    return None
+
+
+# ------------------------------------------------------------------- state ----
+
+def _state_path(session_id):
+    safe = "".join(ch for ch in session_id if ch.isalnum() or ch in "-_")
+    return os.path.join(STATE_DIR, f"{safe or 'unknown'}.json")
+
+
+def _load_state(path):
+    try:
+        with open(path) as fh:
+            s = json.load(fh)
+        return s if isinstance(s, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _save_state(path, state):
+    state["updated"] = time.strftime("%Y-%m-%dT%H:%M:%S")
+    tmp = f"{path}.{os.getpid()}.tmp"
+    with open(tmp, "w") as fh:
+        json.dump(state, fh)
+    os.replace(tmp, path)
+
+
+def _sweep():
+    """Drop state for sessions untouched for 30 days; at most once an hour."""
+    marker = os.path.join(STATE_DIR, ".swept")
+    now = time.time()
+    try:
+        if now - os.path.getmtime(marker) < SWEEP_S:
+            return
+    except OSError:
+        pass
+    for p in glob.glob(os.path.join(STATE_DIR, "*.json")) + glob.glob(os.path.join(STATE_DIR, "*.lock")):
+        try:
+            if now - os.path.getmtime(p) > STALE_S:
+                os.remove(p)
+        except OSError:
+            pass
+    with open(marker, "w"):
+        pass
+
+
+# -------------------------------------------------------------------- hook ----
+
+def run(payload, cfg=None):
+    """Decide for one PreToolUse payload. Returns the dict to print, or None."""
+    session_id = payload.get("session_id")
+    transcript = payload.get("transcript_path")
+    if not session_id or not transcript:
+        return None
+    cfg = cfg if cfg is not None else load_guard_settings()
+    budget = budget_for(cfg, payload.get("cwd"), session_id)
+    if not budget:
+        return None
+    os.makedirs(STATE_DIR, exist_ok=True)
+    path = _state_path(session_id)
+    lock = open(path + ".lock", "w")
+    try:
+        if fcntl:
+            fcntl.flock(lock, fcntl.LOCK_EX)     # parallel tool calls share one state file
+        state = _load_state(path)
+        total, outcome = count_session(transcript, session_id, state, state.get("asked_tool"))
+        out = decide(total, budget, cfg, state, outcome, payload.get("tool_use_id"))
+        _save_state(path, state)
+    finally:
+        lock.close()
+    _sweep()
+    return out
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        payload = json.loads(raw) if raw.strip() else {}
+        out = run(payload) if isinstance(payload, dict) else None
+        if out:
+            print(json.dumps(out))
+    except Exception:
+        pass          # fail open: never stand between the user and their session
+    return 0

package/finops/integrate.py

@@ -4,6 +4,7 @@
   claude-finops --install-statusline   wire it into settings
   claude-finops --hook          retired no-op, kept so existing installs do not error
   claude-finops --install-hook  prints that the hook is retired and does nothing else
+  claude-finops --install-guard wire the session guard (finops/guard.py) into settings
 
 The prompt hook that used to "suggest a cheaper model" is retired: that
 suggestion had no basis — it would have meant repricing work that never ran.
@@ -89,6 +90,19 @@ def _command():
     return f"{shlex.quote(sys.executable)} {shlex.quote(os.path.join(root, 'run.py'))}"
 
 
+def _guard_command():
+    """The hook command: this installation's own code, and never a blocking exit.
+
+    Not the claude-finops on PATH: that can be an older release without --guard,
+    and its "unknown option" exit code 2 is what Claude Code reads as "block this
+    tool call". `|| true` keeps any failure (missing Python, a moved install) from
+    ever blocking; a successful run's JSON on stdout passes through unchanged.
+    """
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    run = f"{shlex.quote(sys.executable)} {shlex.quote(os.path.join(root, 'run.py'))}"
+    return f"{run} --guard || true"
+
+
 def _load_settings():
     try:
         with open(SETTINGS) as fh:
@@ -146,3 +160,67 @@ def install_statusline(remove=False):
     return {"ok": True, "message": f"Installed the statusline in {SETTINGS}. It shows the model, "
                                    "context % and 5-hour limit % under every prompt. "
                                    "Undo: claude-finops --uninstall-statusline"}
+
+
+# ------------------------------------------------------------------- guard ----
+
+def _is_guard(h):
+    cmd = h.get("command") if isinstance(h, dict) else None
+    return isinstance(cmd, str) and "--guard" in cmd.split() and "finops" in cmd
+
+
+def guard_state():
+    """"installed" when our PreToolUse guard hook is in settings, else None."""
+    groups = ((_load_settings().get("hooks") or {}).get("PreToolUse")) or []
+    for g in groups if isinstance(groups, list) else []:
+        if isinstance(g, dict) and any(_is_guard(h) for h in g.get("hooks") or []):
+            return "installed"
+    return None
+
+
+def install_guard(remove=False):
+    """Add (or remove) our PreToolUse hook. Returns {"ok", "message"}.
+
+    Only our own entry is ever touched: other PreToolUse hooks, and other hook
+    events, are left exactly as they were.
+    """
+    s = _load_settings()
+    hooks = s.get("hooks") if isinstance(s.get("hooks"), dict) else {}
+    groups = hooks.get("PreToolUse") if isinstance(hooks.get("PreToolUse"), list) else []
+    if remove:
+        if guard_state() is None:
+            return {"ok": True, "message": "The session guard is not installed; nothing changed."}
+        kept = []
+        for g in groups:
+            if isinstance(g, dict) and isinstance(g.get("hooks"), list):
+                g = dict(g, hooks=[h for h in g["hooks"] if not _is_guard(h)])
+                if not g["hooks"]:
+                    continue
+            kept.append(g)
+        if kept:
+            hooks["PreToolUse"] = kept
+        else:
+            hooks.pop("PreToolUse", None)
+        if hooks:
+            s["hooks"] = hooks
+        else:
+            s.pop("hooks", None)
+        _save_settings(s)
+        return {"ok": True, "message": f"Removed the session guard from {SETTINGS}"}
+    if guard_state() == "installed":
+        return {"ok": True, "message": "The session guard is already installed."}
+    groups.append({"matcher": "", "hooks": [
+        {"type": "command", "command": _guard_command(), "timeout": 10}]})
+    hooks["PreToolUse"] = groups
+    s["hooks"] = hooks
+    _save_settings(s)
+    msg = (f"Installed the session guard in {SETTINGS}. It applies to new Claude Code sessions. "
+           "Undo: claude-finops --uninstall-guard")
+    try:
+        from .guard import load_guard_settings, has_any_budget
+        if not has_any_budget(load_guard_settings()):
+            msg += (" It stays inactive until you set a per-session token budget "
+                    "(Budgets page, or guard.session_tokens in settings.local.json).")
+    except Exception:
+        pass
+    return {"ok": True, "message": msg}

package/finops/jev.py

@@ -0,0 +1,175 @@
+"""Jev (TypeSafe's "System One" model): install its Claude Code plugin, keep its API key.
+
+Jev makes fast, typed decisions (pick one, yes or no, a score, a value). It does not write
+text or code, so it cannot stand in for the model behind Claude Code; the plugin teaches
+Claude how to use Jev in the software you build. https://docs.typesafe.ai
+
+  install    claude plugin marketplace add typesafe-ai/skills
+             claude plugin install typesafe@typesafe-ai
+  uninstall  claude plugin uninstall typesafe@typesafe-ai
+  API key    env.TYPESAFE_API_KEY in ~/.claude/settings.json, which Claude Code hands to
+             every new session (the page never gets the key back, only its last four)
+
+Every command is a fixed argument list, run only when the user clicks.
+"""
+import json
+import os
+import re
+import shutil
+import subprocess
+
+from . import integrate
+
+PLUGIN = "typesafe@typesafe-ai"
+MARKETPLACE = "typesafe-ai/skills"
+ENV_KEY = "TYPESAFE_API_KEY"
+JEV_USD_PER_INPUT_TOKEN = 0.042 / 1e6      # TypeSafe's published price; output is free
+
+
+# ------------------------------------------------------------------ plugin ----
+
+def _claude():
+    return shutil.which("claude")
+
+
+def _run(cmd, log):
+    """Run one fixed command, log every output line, and put its last lines in any error
+    (so "already added" can be recognised). No shell."""
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+    except (OSError, subprocess.SubprocessError) as e:
+        raise RuntimeError(f"{' '.join(cmd[1:4])} could not run: {e}") from None
+    lines = [ln.strip() for ln in (r.stdout + "\n" + r.stderr).splitlines() if ln.strip()]
+    for ln in lines:
+        log(ln[-200:])
+    if r.returncode:
+        raise RuntimeError(f"{' '.join(cmd[1:4])} failed: " + (" ".join(lines[-3:]) or f"exit {r.returncode}"))
+
+
+def status():
+    """Is the plugin installed? Never raises: a broken `claude` just reads as not installed."""
+    exe = _claude()
+    out = {"claude": bool(exe), "installed": False, "version": None, "enabled": None}
+    if not exe:
+        return out
+    try:
+        r = subprocess.run([exe, "plugin", "list", "--json"], capture_output=True, text=True,
+                           timeout=20)
+        rows = json.loads(r.stdout or "[]")
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return out
+    for p in rows if isinstance(rows, list) else []:
+        if isinstance(p, dict) and p.get("id") == PLUGIN:
+            out.update(installed=True, version=p.get("version"), enabled=p.get("enabled"))
+    return out
+
+
+def _need_claude():
+    exe = _claude()
+    if not exe:
+        raise RuntimeError("Claude Code's `claude` command was not found. Install Claude Code, "
+                           "or start the dashboard from a terminal where `claude` works.")
+    return exe
+
+
+def install(log):
+    exe = _need_claude()
+    log(f"Adding TypeSafe's plugin list: claude plugin marketplace add {MARKETPLACE}")
+    try:
+        _run([exe, "plugin", "marketplace", "add", MARKETPLACE], log)
+    except RuntimeError as e:
+        if "already" not in str(e).lower():
+            raise
+        log("Already added. Carrying on.")
+    log(f"Installing the plugin: claude plugin install {PLUGIN}")
+    _run([exe, "plugin", "install", PLUGIN], log)
+    log("Installed. New Claude Code sessions can use it; restart any open ones.")
+    return status()
+
+
+def uninstall(log):
+    exe = _need_claude()
+    log(f"Removing the plugin: claude plugin uninstall {PLUGIN}")
+    _run([exe, "plugin", "uninstall", PLUGIN], log)
+    log("Removed.")
+    return status()
+
+
+# --------------------------------------------------------------------- key ----
+
+def key_status():
+    """Where the key comes from and its last four characters. Never the key."""
+    shell = os.environ.get(ENV_KEY)
+    stored = ((integrate._load_settings().get("env") or {}).get(ENV_KEY)) or ""
+    key = shell or stored
+    return {"source": "shell" if shell else "claude_settings" if stored else None,
+            "last4": key[-4:] if len(key) >= 12 else None}
+
+
+def save_key(value):
+    value = (value or "").strip()
+    if not value:
+        raise ValueError("Paste your Jev API key first.")
+    if any(ch.isspace() for ch in value):
+        raise ValueError("A key has no spaces or line breaks in it.")
+    if len(value) < 16:
+        raise ValueError("That looks too short for a TypeSafe API key.")
+    s = integrate._load_settings()
+    env = s.get("env") if isinstance(s.get("env"), dict) else {}
+    env[ENV_KEY] = value
+    s["env"] = env
+    integrate._save_settings(s)
+
+
+def remove_key():
+    s = integrate._load_settings()
+    env = s.get("env") if isinstance(s.get("env"), dict) else {}
+    if ENV_KEY not in env:
+        return
+    env.pop(ENV_KEY)
+    if env:
+        s["env"] = env
+    else:
+        s.pop("env", None)
+    integrate._save_settings(s)
+
+
+# --------------------------------------------------------------- where it fits ----
+# A prompt Jev could have answered: short (at most two model calls), no tools, a short
+# reply, and worded as a decision rather than a request to build something.
+DECIDE = re.compile(r"\b(classify|categori[sz]e|category|label|which (one|of)|yes or no|true or false|"
+                    r"is (this|it) (a|an)\b|extract|score|rate this|triage|route|detect|decide|pick one|"
+                    r"choose|prioriti[sz]e|sentiment|is it valid|should (i|we)\b|does (this|it)\b)", re.I)
+BUILD = re.compile(r"\b(write|implement|build|create|fix|refactor|add|update|change|make|generate|"
+                   r"design|explain|debug)\b", re.I)
+# Claude Code's own summary after a context compaction is stored like a prompt; it is not yours.
+NOT_YOURS = ("This session is being continued from a previous conversation",)
+_MASK = re.compile(r"\S+@\S+|(?:~|\.{0,2})?/[\w.\-/]+|\d{3,}")
+
+
+def _mask(text):
+    return _MASK.sub("…", re.sub(r"\s+", " ", text or "")).strip()[:140]
+
+
+def fit(a, f=None):
+    """How much of the filtered Claude Code work was decision-shaped, and what it would cost on Jev."""
+    w, p = a.where(f)
+    total = a.one(f"SELECT COALESCE(SUM(r.est_cost_usd),0) c FROM requests r "
+                  f"WHERE {w} AND r.agent='claude'", p)["c"]
+    rows = a.q(f"""SELECT pr.text, pr.request_count, pr.output_tokens, pr.est_cost_usd cost,
+                          COALESCE(pr.input_tokens,0) + COALESCE(pr.cache_read_tokens,0)
+                            + COALESCE(pr.cache_write_tokens,0) ctx
+                   FROM prompts pr WHERE pr.agent='claude' AND pr.id IN (
+                     SELECT r.prompt_id FROM requests r WHERE {w} AND r.agent='claude')
+                     AND COALESCE(pr.request_count,0) <= 2 AND COALESCE(pr.tool_calls,0) = 0
+                     AND COALESCE(pr.output_tokens,0) <= 300""", p)
+    hits = [r for r in rows if DECIDE.search(r["text"] or "") and not BUILD.search((r["text"] or "")[:200])
+            and not (r["text"] or "").lstrip().startswith(NOT_YOURS)]
+    n_all = a.one(f"SELECT COUNT(DISTINCT r.prompt_id) n FROM requests r "
+                  f"WHERE {w} AND r.agent='claude' AND r.prompt_id IS NOT NULL", p)["n"]
+    cost = sum(r["cost"] or 0 for r in hits)
+    return {"prompts": len(hits), "total_prompts": n_all, "claude_cost": cost,
+            "jev_cost": sum(r["ctx"] or 0 for r in hits) * JEV_USD_PER_INPUT_TOKEN,
+            "share_pct": 100.0 * cost / total if total else 0.0, "total_cost": total,
+            "examples": [{"text": _mask(r["text"]), "cost": r["cost"] or 0}
+                         for r in sorted(hits, key=lambda r: -(r["cost"] or 0))[:5]]}