zexl-mcp 0.1.0__tar.gz

zexl_mcp-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+
+# Node
+node_modules/
+.next/
+out/
+*.tsbuildinfo
+next-env.d.ts
+
+# Secrets and local config
+.env
+.env.*
+!.env.example
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Database backups (scripts/backup-restore-check.sh)
+backups/

zexl_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: zexl-mcp
+Version: 0.1.0
+Summary: MCP server for Zexl: ask your AI assistant about AI spend and waste, and connect a project in one go.
+Project-URL: Homepage, https://tryzexl.xyz/docs/mcp
+Author: Zexl
+License-Expression: Apache-2.0
+Keywords: ai,cost,llm,mcp,zexl
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.12
+Description-Content-Type: text/markdown
+
+# zexl-mcp
+
+An MCP server for [Zexl](https://tryzexl.xyz). Ask your AI assistant about your AI spend ("what did we waste last week, and why?"), and let a coding agent add Zexl to a project in one go.
+
+It only reads. It cannot send data to Zexl, change budgets, keys or members, and it never sees prompt text, because Zexl does not have any.
+
+## Add it to your AI tool
+
+Claude Code:
+
+```bash
+claude mcp add zexl -- uvx zexl-mcp
+```
+
+Claude Desktop, Cursor and other clients that take a JSON config:
+
+```json
+{
+  "mcpServers": {
+    "zexl": { "command": "uvx", "args": ["zexl-mcp"] }
+  }
+}
+```
+
+`uvx` comes with [uv](https://docs.astral.sh/uv/). With pip instead: `pip install zexl-mcp`, then use `zexl-mcp` as the command.
+
+## Connect
+
+Two ways:
+
+1. **Let the agent do it.** Ask: "Add Zexl to this project." The agent calls `zexl_connect_start` and shows you a link and a code. Open the link, sign up or sign in (email or Google), check the code matches, pick a workspace and an environment, and approve. The agent then calls `zexl_connect_finish`, which:
+   - writes `ZEXL_API_KEY` into the project's `.env` file itself, so the key never appears in the chat;
+   - makes the salt (the part after the dot) on your machine; Zexl never receives it. If the project already had a Zexl key, its salt is kept so earlier calls still match;
+   - adds `.env` to `.gitignore` if git would otherwise commit it;
+   - saves a read key for the other tools in `~/.config/zexl/credentials.json`, readable only by you.
+
+   The agent then follows `zexl_setup_guide` to add the SDK and checks the first call with `zexl_check_connection`.
+
+2. **Use a read key you made.** In the Zexl dashboard, Settings > API keys, create a key with "Read figures (MCP server)". Then:
+
+   ```bash
+   claude mcp add zexl -e ZEXL_READ_KEY=zx_... -- uvx zexl-mcp
+   ```
+
+## Tools
+
+| Tool | What it answers |
+|---|---|
+| `zexl_status` | Is it connected, to which workspace, and when did the last call arrive? |
+| `zexl_connect_start`, `zexl_connect_finish` | Connect this project (see above) |
+| `zexl_setup_guide` | Exact steps to add the SDK to a Python app, or to track Claude Code |
+| `zexl_check_connection` | Did the first call arrive, and what was recorded? |
+| `zexl_spend_summary` | Spend, waste by type, useful share, budget headroom, invoice coverage |
+| `zexl_forecast` | Where this month will end, the likely range, and when it passes the budget |
+| `zexl_top_waste` | The biggest waste findings, each with a fix |
+| `zexl_breakdown` | Spend and waste per feature, model, customer or actor |
+| `zexl_explain_spike` | Why one day cost more: the waste that day, and the features and models behind it |
+| `zexl_pattern_runs` | The runs behind a finding, worst first |
+| `zexl_run_detail` | One run step by step, with repeats, retries and cut-off answers marked |
+
+There is also a prompt, `integrate_zexl`, that walks the agent through connecting, setup and the first check.
+
+Every reading tool takes `days` (default 30) and `environment` (`production` by default; `staging`, `development` or `all`). A read key made for one environment always reads that environment.
+
+## Settings
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `ZEXL_READ_KEY` | A read key. Overrides the saved credentials | the saved credentials |
+| `ZEXL_API_URL` | The Zexl API | `https://zexl-api.fly.dev` |
+| `ZEXL_CONFIG_DIR` | Where credentials are saved | `~/.config/zexl` |
+
+To disconnect, revoke the read key in Settings > API keys and delete `~/.config/zexl/credentials.json`.
+
+## Development
+
+```bash
+uv sync
+```
+
+```bash
+uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest -q
+```

zexl_mcp-0.1.0/README.md

@@ -0,0 +1,83 @@
+# zexl-mcp
+
+An MCP server for [Zexl](https://tryzexl.xyz). Ask your AI assistant about your AI spend ("what did we waste last week, and why?"), and let a coding agent add Zexl to a project in one go.
+
+It only reads. It cannot send data to Zexl, change budgets, keys or members, and it never sees prompt text, because Zexl does not have any.
+
+## Add it to your AI tool
+
+Claude Code:
+
+```bash
+claude mcp add zexl -- uvx zexl-mcp
+```
+
+Claude Desktop, Cursor and other clients that take a JSON config:
+
+```json
+{
+  "mcpServers": {
+    "zexl": { "command": "uvx", "args": ["zexl-mcp"] }
+  }
+}
+```
+
+`uvx` comes with [uv](https://docs.astral.sh/uv/). With pip instead: `pip install zexl-mcp`, then use `zexl-mcp` as the command.
+
+## Connect
+
+Two ways:
+
+1. **Let the agent do it.** Ask: "Add Zexl to this project." The agent calls `zexl_connect_start` and shows you a link and a code. Open the link, sign up or sign in (email or Google), check the code matches, pick a workspace and an environment, and approve. The agent then calls `zexl_connect_finish`, which:
+   - writes `ZEXL_API_KEY` into the project's `.env` file itself, so the key never appears in the chat;
+   - makes the salt (the part after the dot) on your machine; Zexl never receives it. If the project already had a Zexl key, its salt is kept so earlier calls still match;
+   - adds `.env` to `.gitignore` if git would otherwise commit it;
+   - saves a read key for the other tools in `~/.config/zexl/credentials.json`, readable only by you.
+
+   The agent then follows `zexl_setup_guide` to add the SDK and checks the first call with `zexl_check_connection`.
+
+2. **Use a read key you made.** In the Zexl dashboard, Settings > API keys, create a key with "Read figures (MCP server)". Then:
+
+   ```bash
+   claude mcp add zexl -e ZEXL_READ_KEY=zx_... -- uvx zexl-mcp
+   ```
+
+## Tools
+
+| Tool | What it answers |
+|---|---|
+| `zexl_status` | Is it connected, to which workspace, and when did the last call arrive? |
+| `zexl_connect_start`, `zexl_connect_finish` | Connect this project (see above) |
+| `zexl_setup_guide` | Exact steps to add the SDK to a Python app, or to track Claude Code |
+| `zexl_check_connection` | Did the first call arrive, and what was recorded? |
+| `zexl_spend_summary` | Spend, waste by type, useful share, budget headroom, invoice coverage |
+| `zexl_forecast` | Where this month will end, the likely range, and when it passes the budget |
+| `zexl_top_waste` | The biggest waste findings, each with a fix |
+| `zexl_breakdown` | Spend and waste per feature, model, customer or actor |
+| `zexl_explain_spike` | Why one day cost more: the waste that day, and the features and models behind it |
+| `zexl_pattern_runs` | The runs behind a finding, worst first |
+| `zexl_run_detail` | One run step by step, with repeats, retries and cut-off answers marked |
+
+There is also a prompt, `integrate_zexl`, that walks the agent through connecting, setup and the first check.
+
+Every reading tool takes `days` (default 30) and `environment` (`production` by default; `staging`, `development` or `all`). A read key made for one environment always reads that environment.
+
+## Settings
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `ZEXL_READ_KEY` | A read key. Overrides the saved credentials | the saved credentials |
+| `ZEXL_API_URL` | The Zexl API | `https://zexl-api.fly.dev` |
+| `ZEXL_CONFIG_DIR` | Where credentials are saved | `~/.config/zexl` |
+
+To disconnect, revoke the read key in Settings > API keys and delete `~/.config/zexl/credentials.json`.
+
+## Development
+
+```bash
+uv sync
+```
+
+```bash
+uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest -q
+```

zexl_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "zexl-mcp"
+version = "0.1.0"
+description = "MCP server for Zexl: ask your AI assistant about AI spend and waste, and connect a project in one go."
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "Zexl" }]
+keywords = ["mcp", "llm", "ai", "cost", "zexl"]
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.12,<2"]
+
+[project.scripts]
+zexl-mcp = "zexl_mcp.server:main"
+
+[project.urls]
+Homepage = "https://tryzexl.xyz/docs/mcp"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.8", "mypy>=1.13"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zexl_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "S"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "S105", "S106", "S603", "S607", "E501"]
+
+[tool.mypy]
+strict = true
+files = ["src"]
+
+[[tool.mypy.overrides]]
+module = ["mcp.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

zexl_mcp-0.1.0/src/zexl_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Zexl MCP server. See server.py and design section 14."""
+
+__version__ = "0.1.0"

zexl_mcp-0.1.0/src/zexl_mcp/client.py

@@ -0,0 +1,67 @@
+"""A small client for the Zexl query API. Read keys only; nothing here can change a workspace."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from zexl_mcp import config
+
+USER_AGENT = "zexl-mcp/0.1.0"
+
+
+class ZexlError(Exception):
+    """A failure the person or the agent can act on. The message says what to do."""
+
+
+class Api:
+    def __init__(self, base: str | None = None, transport: httpx.AsyncBaseTransport | None = None):
+        self._base = (base or config.api_url()).rstrip("/")
+        self._transport = transport
+
+    def _client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            base_url=self._base,
+            timeout=20.0,
+            transport=self._transport,
+            headers={"User-Agent": USER_AGENT},
+        )
+
+    async def _send(
+        self, method: str, path: str, key: str | None = None, body: Any = None
+    ) -> httpx.Response:
+        headers = {"Authorization": f"Bearer {key}"} if key else {}
+        try:
+            async with self._client() as c:
+                return await c.request(method, path, headers=headers, json=body)
+        except httpx.HTTPError as e:
+            raise ZexlError(f"Could not reach Zexl at {self._base} ({type(e).__name__}).") from e
+
+    async def get(self, path: str, key: str) -> dict[str, Any]:
+        r = await self._send("GET", path, key)
+        return _json(r)
+
+    async def post(self, path: str, body: Any) -> tuple[int, dict[str, Any]]:
+        r = await self._send("POST", path, body=body)
+        if r.status_code in (200, 201, 202):
+            return r.status_code, r.json()
+        _json(r)
+        raise AssertionError("unreachable")
+
+
+def _json(r: httpx.Response) -> dict[str, Any]:
+    if r.status_code < 300:
+        data: dict[str, Any] = r.json()
+        return data
+    try:
+        detail = r.json().get("detail")
+    except ValueError:
+        detail = None
+    if r.status_code == 401:
+        raise ZexlError(
+            "Zexl did not accept the read key. Run zexl_connect_start to connect again, or set "
+            "ZEXL_READ_KEY to a read key from Settings > API keys."
+        )
+    message = detail if isinstance(detail, str) else f"Zexl answered {r.status_code}."
+    raise ZexlError(message)

zexl_mcp-0.1.0/src/zexl_mcp/config.py

@@ -0,0 +1,79 @@
+"""Where the MCP server finds its settings and its read key. Design section 14.
+
+Order for the read key: `ZEXL_READ_KEY`, then the credentials file written by the connect flow
+(`~/.config/zexl/credentials.json`, or `$ZEXL_CONFIG_DIR/credentials.json`).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_API = "https://zexl-api.fly.dev"
+
+
+@dataclass(frozen=True)
+class Credentials:
+    read_key: str
+    workspace_id: str = ""
+    workspace_name: str = ""
+    environment: str = ""
+
+
+def api_url() -> str:
+    return os.environ.get("ZEXL_API_URL", DEFAULT_API).rstrip("/")
+
+
+def config_dir() -> Path:
+    base = os.environ.get("ZEXL_CONFIG_DIR")
+    if base:
+        return Path(base)
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    return (Path(xdg) if xdg else Path.home() / ".config") / "zexl"
+
+
+def credentials_path() -> Path:
+    return config_dir() / "credentials.json"
+
+
+def load() -> Credentials | None:
+    env = os.environ.get("ZEXL_READ_KEY", "").strip()
+    if env:
+        return Credentials(env)
+    path = credentials_path()
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return None
+    key = data.get("read_key")
+    if not isinstance(key, str) or not key.startswith("zx_"):
+        return None
+    return Credentials(
+        key,
+        str(data.get("workspace_id", "")),
+        str(data.get("workspace_name", "")),
+        str(data.get("environment") or ""),
+    )
+
+
+def save(creds: Credentials) -> Path:
+    """Writes the credentials file readable by this user only."""
+    path = credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    body = json.dumps(
+        {
+            "read_key": creds.read_key,
+            "workspace_id": creds.workspace_id,
+            "workspace_name": creds.workspace_name,
+            "environment": creds.environment,
+        },
+        indent=2,
+    )
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, stat.S_IRUSR | stat.S_IWUSR)
+    with os.fdopen(fd, "w") as f:
+        f.write(body + "\n")
+    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+    return path

zexl_mcp-0.1.0/src/zexl_mcp/envfile.py

@@ -0,0 +1,139 @@
+"""Puts the send key into a project's .env file without the key passing through the model.
+
+The salt (the part after the dot) is made here, on the person's machine, and never sent to
+Zexl. When the project already has a Zexl key, its salt is reused so that prompt hashes keep
+matching earlier calls (design sections 3.3 and 14.3).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import secrets
+import shutil
+import subprocess  # noqa: S404 - only `git check-ignore`, with fixed arguments
+from dataclasses import dataclass
+from pathlib import Path
+
+NAME = "ZEXL_API_KEY"
+_LINE = re.compile(rf"^\s*(?:export\s+)?{NAME}\s*=\s*(.*)$")
+_SALT = re.compile(r"^[A-Za-z0-9_-]{22,128}$")
+
+
+def mask(key: str) -> str:
+    """`zx_ab12…` : enough to recognise a key, not enough to use it."""
+    return key[:7] + "…" if len(key) > 7 else "…"
+
+
+def _unquote(value: str) -> str:
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    return value.split(" #", 1)[0].strip()
+
+
+def existing_key(path: Path) -> str | None:
+    """A Zexl key already in the shell or in the .env file."""
+    try:
+        for line in path.read_text().splitlines():
+            m = _LINE.match(line)
+            if m:
+                value = _unquote(m.group(1))
+                if value.startswith("zx_"):
+                    return value
+    except OSError:
+        pass
+    env = os.environ.get(NAME, "").strip()
+    return env if env.startswith("zx_") else None
+
+
+def salt_of(key: str | None) -> str | None:
+    if not key or "." not in key:
+        return None
+    salt = key.rsplit(".", 1)[1]
+    return salt if _SALT.match(salt) else None
+
+
+def new_salt() -> str:
+    return secrets.token_urlsafe(32)
+
+
+@dataclass(frozen=True)
+class Written:
+    path: Path
+    replaced: bool
+    reused_salt: bool
+    gitignore: str  # "added", "already", "not a git repository" or "could not check"
+    key: str
+
+
+def write_key(path: Path, token: str) -> Written:
+    """Adds or replaces ZEXL_API_KEY in `path`, creating it if needed. `token` is
+    `zx_<id>_<secret>` from the API; the salt is added here."""
+    previous = existing_key(path)
+    salt = salt_of(previous)
+    key = f"{token}.{salt or new_salt()}"
+    lines: list[str] = []
+    replaced = False
+    try:
+        lines = path.read_text().splitlines()
+    except FileNotFoundError:
+        pass
+    out = []
+    for line in lines:
+        if _LINE.match(line):
+            if not replaced:
+                out.append(f"{NAME}={key}")
+                replaced = True
+            continue
+        out.append(line)
+    if not replaced:
+        if out and out[-1].strip():
+            out.append("")
+        out.append("# Zexl: sends call metadata only, never prompts. https://tryzexl.xyz/docs")
+        out.append(f"{NAME}={key}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(out) + "\n")
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+    return Written(path, replaced, salt is not None, ensure_ignored(path), key)
+
+
+def ensure_ignored(path: Path) -> str:
+    """Makes sure git will not commit the .env file."""
+    folder = path.parent.resolve()
+    git = shutil.which("git")
+    if git is None:
+        return "could not check"
+    try:
+        top = subprocess.run(  # noqa: S603
+            [git, "rev-parse", "--show-toplevel"],
+            cwd=folder,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return "could not check"
+    if top.returncode != 0:
+        return "not a git repository"
+    root = Path(top.stdout.strip())
+    try:
+        check = subprocess.run(  # noqa: S603
+            [git, "check-ignore", "-q", str(path.resolve())],
+            cwd=root,
+            capture_output=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return "could not check"
+    if check.returncode == 0:
+        return "already"
+    rel = path.resolve().relative_to(root).as_posix()
+    gi = root / ".gitignore"
+    text = gi.read_text() if gi.exists() else ""
+    sep = "" if not text or text.endswith("\n") else "\n"
+    gi.write_text(f"{text}{sep}{rel}\n")
+    return "added"

zexl_mcp-0.1.0/src/zexl_mcp/guide.py

@@ -0,0 +1,82 @@
+"""Setup steps the agent follows to add Zexl to a project. Kept in the package so the tool works
+without fetching anything; the same steps are on https://tryzexl.xyz/docs."""
+
+from __future__ import annotations
+
+PYTHON = """\
+# Add Zexl to a Python app
+
+Zexl records metadata about each OpenAI and Anthropic call (model, tokens, timing, outcome and
+salted hashes) and never sends prompt or response text.
+
+1. Install the SDK. Add `zexl` to the project's dependencies the way the project already does it:
+   - requirements.txt: add a line `zexl`
+   - pyproject.toml (uv, poetry, pdm, hatch): add `"zexl"` to `dependencies`, or run `uv add zexl`
+   - otherwise: `pip install zexl`
+
+2. Load the key from the environment. `ZEXL_API_KEY` is already in the project's `.env` file
+   (written by zexl_connect_finish). Do not copy the key into code or chat.
+   - If the app already loads `.env` (python-dotenv, pydantic-settings, Django-environ, the
+     framework's own loader), nothing to do: make sure the loader runs before step 3.
+   - Otherwise set it in the process environment where the app is deployed. For local runs,
+     `python-dotenv` with `load_dotenv()` at the top of the entry point works.
+
+3. Turn capture on. Add this one import once, at the entry point, before the OpenAI or Anthropic
+   client is created:
+
+       import zexl.auto  # records OpenAI and Anthropic calls; prompts never leave the process
+
+   Typical entry points: `main.py` or `app.py` (FastAPI, Flask), `manage.py` and `wsgi.py`/`asgi.py`
+   (Django), the worker's start module (Celery, RQ), the handler module (AWS Lambda), the first
+   cell (notebooks). If the key is loaded from .env in code, put the import after `load_dotenv()`.
+
+4. Label the spend (optional, recommended). Labels make the dashboard useful:
+
+       import zexl
+
+       with zexl.feature("support-reply"):      # which product feature made the calls
+           ...
+       with zexl.run("research", feature="report-builder"):  # one unit of agent work
+           ...
+       zexl.set_customer(account.id)            # your customer's id, never an email
+
+   Without labels, the feature is the `module.function` that made the call, and agent loops are
+   grouped into runs automatically when each request continues the previous answer.
+
+5. Short-lived processes (serverless, scripts, CLI tools): call `zexl.flush()` before exit.
+
+6. Environment. The key decides the environment (production, staging or development) on the
+   server, so `ZEXL_ENV` is only needed with older keys.
+
+7. Check it works: run the app so it makes one model call, then call zexl_check_connection.
+   `zexl.status()` in the app shows whether capture is on and how many records were sent.
+
+Do not: put the key in source files, log it, or commit `.env`. Do not wrap or replace the
+OpenAI/Anthropic clients; the import hooks them in place. Calls are never blocked or changed, and
+if Zexl is down the app carries on.
+"""
+
+CLAUDE_CODE = """\
+# Track Claude Code usage with Zexl
+
+Claude Code exports usage over OpenTelemetry. No SDK, no code change. It sends model, tokens,
+cost estimate, timing and errors per request; prompts and code are not sent unless the user turns
+that on, and Zexl drops them if they arrive.
+
+Use a send key (zx_<id>_<secret>, the part before the dot is enough). Put these in the shell
+profile (~/.zshrc or ~/.bashrc), or in Claude Code's settings.json under "env":
+
+    export CLAUDE_CODE_ENABLE_TELEMETRY=1
+    export OTEL_LOGS_EXPORTER=otlp
+    export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+    export OTEL_EXPORTER_OTLP_ENDPOINT=https://zexl-intake.fly.dev
+    export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer zx_<id>_<secret>"
+
+Then start a new `claude` session. On a Pro or Max plan the cost shown is what the same usage
+would cost on the API; you are not billed per token.
+
+The key is in the project's .env as ZEXL_API_KEY: the header takes the part before the dot. Ask
+the person to paste it into their profile themselves rather than printing it in chat.
+"""
+
+TOPICS = {"python": PYTHON, "claude-code": CLAUDE_CODE}

zexl_mcp-0.1.0/src/zexl_mcp/server.py

@@ -0,0 +1,462 @@
+"""Zexl MCP server (stdio). Design section 14.
+
+Run with `uvx zexl-mcp`. Tools read a workspace through the query API with a read key, and the
+connect tools set a project up in one go. Nothing here can change a workspace, and no tool ever
+sees prompt text: Zexl does not have any.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import statistics
+import time
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import CallToolResult, TextContent, ToolAnnotations
+
+from zexl_mcp import config, envfile, guide, text
+from zexl_mcp.client import Api, ZexlError
+
+READ = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
+Env = Literal["production", "staging", "development", "all"]
+Category = Literal["retry", "loop", "abandoned", "truncate_redo", "cache_miss", "context_growth"]
+
+INSTRUCTIONS = """\
+Zexl shows how much AI model spend did useful work and what was wasted (retries, loops,
+abandoned responses, answers cut off and redone, prompt caching not used). It only ever has call
+metadata, never prompts.
+
+To add Zexl to the user's project: zexl_connect_start, show the user the link and code, then
+zexl_connect_finish (it writes ZEXL_API_KEY to .env itself; never ask the user to paste a key into
+chat), then follow zexl_setup_guide, then zexl_check_connection after the app makes a call.
+
+To answer questions about spend: start with zexl_spend_summary or zexl_top_waste, then drill in
+with zexl_pattern_runs and zexl_run_detail. Default environment is production. Quote dollar
+figures as given and say when they are estimates.
+"""
+
+
+def _result(message: str, data: dict[str, Any] | None = None) -> CallToolResult:
+    return CallToolResult(
+        content=[TextContent(type="text", text=message)], structuredContent=data or None
+    )
+
+
+def _error(e: Exception) -> CallToolResult:
+    return CallToolResult(content=[TextContent(type="text", text=str(e))], isError=True)
+
+
+def _range(days: int) -> tuple[int, str]:
+    days = max(1, min(int(days), 365))
+    end = datetime.now(timezone.utc).date()  # noqa: UP017 - Python 3.10
+    start = end - timedelta(days=days - 1)
+    return days, f"from={start.isoformat()}&to={end.isoformat()}"
+
+
+class Zexl:
+    """The tools' logic, separate from MCP so it can be tested with a fake API."""
+
+    def __init__(self, api: Api | None = None, sleep: Any = asyncio.sleep) -> None:
+        self.api = api or Api()
+        self._sleep = sleep
+        self._pending: dict[str, Any] | None = None
+        self._connected_at: float | None = None
+
+    # --- credentials ---
+
+    def _creds(self) -> config.Credentials:
+        creds = config.load()
+        if creds is None:
+            raise ZexlError(
+                "Zexl is not connected yet. Run zexl_connect_start to connect this project, or set "
+                "ZEXL_READ_KEY to a read key from Settings > API keys in the Zexl dashboard."
+            )
+        return creds
+
+    async def _workspace(self) -> tuple[config.Credentials, dict[str, Any]]:
+        creds = self._creds()
+        listed = await self.api.get("/v1/workspaces", creds.read_key)
+        workspaces = listed.get("workspaces") or []
+        if not workspaces:
+            raise ZexlError("The read key has no workspace. Connect again with zexl_connect_start.")
+        return creds, workspaces[0]
+
+    async def _get(self, path: str) -> tuple[dict[str, Any], dict[str, Any]]:
+        creds, ws = await self._workspace()
+        return ws, await self.api.get(f"/v1/workspaces/{ws['id']}{path}", creds.read_key)
+
+    @staticmethod
+    def _env(ws: dict[str, Any], environment: str) -> str:
+        return str(ws.get("environment") or environment)
+
+    # --- connect ---
+
+    async def connect_start(self, project: str, client: str) -> CallToolResult:
+        code, body = await self.api.post(
+            "/v1/connect", {"client": client[:40], "project": project[:80]}
+        )
+        self._pending = body
+        pending = config.config_dir() / "pending.json"
+        try:
+            pending.parent.mkdir(parents=True, exist_ok=True)
+            pending.write_text(json.dumps(body))
+            pending.chmod(0o600)
+        except OSError:
+            pass
+        msg = (
+            f"Ask the user to open this link and approve: {body['url']}\n"
+            f"The page shows the code {body['user_code']}; it must match. They can sign up there "
+            "(email or Google) if they have no account. The link works for 15 minutes.\n"
+            "Then call zexl_connect_finish with the path of the project's .env file. Do not ask "
+            "the user to paste any key into chat."
+        )
+        return _result(msg, {"url": body["url"], "user_code": body["user_code"]})
+
+    def _load_pending(self) -> dict[str, Any] | None:
+        if self._pending:
+            return self._pending
+        try:
+            data: dict[str, Any] = json.loads((config.config_dir() / "pending.json").read_text())
+            return data
+        except (OSError, ValueError):
+            return None
+
+    async def connect_finish(self, env_file: str, wait_seconds: int) -> CallToolResult:
+        pending = self._load_pending()
+        if not pending:
+            raise ZexlError("No connect request is open. Call zexl_connect_start first.")
+        deadline = time.monotonic() + max(0, min(int(wait_seconds), 600))
+        poll = {"poll_token": pending["poll_token"]}
+        while True:
+            try:
+                status, body = await self.api.post(
+                    f"/v1/connect/{pending['connect_id']}/token", poll
+                )
+            except ZexlError:
+                self._clear_pending()
+                raise
+            if status == 200:
+                break
+            if time.monotonic() >= deadline:
+                return _result(
+                    f"Still waiting for the user to approve at {pending['url']} (code "
+                    f"{pending['user_code']}). Call zexl_connect_finish again once they have.",
+                    {"status": "pending"},
+                )
+            await self._sleep(float(pending.get("interval_s", 3)))
+        self._clear_pending()
+        path = Path(env_file).expanduser()
+        written = envfile.write_key(path, body["ingest_token"])
+        saved = config.save(
+            config.Credentials(
+                body["read_token"],
+                body["workspace_id"],
+                body["workspace_name"],
+                body.get("environment") or "",
+            )
+        )
+        self._connected_at = time.time()
+        git = {
+            "added": "Added it to .gitignore.",
+            "already": "It is already in .gitignore.",
+            "not a git repository": "The folder is not a git repository.",
+            "could not check": "Could not check .gitignore; make sure .env is not committed.",
+        }[written.gitignore]
+        salt = (
+            "Reused the salt of the key that was there, so prompt hashes keep matching."
+            if written.reused_salt
+            else "Made a new salt on this machine; it is never sent to Zexl."
+        )
+        msg = (
+            f"Connected to workspace {body['workspace_name']} ({body['environment']}). "
+            f"Wrote ZEXL_API_KEY={envfile.mask(written.key)} to {written.path} "
+            f"({'replaced the old value' if written.replaced else 'added'}). {git} {salt} "
+            f"Saved a read key for these tools in {saved}.\n"
+            "Next: call zexl_setup_guide and follow it to add the SDK, then run the app and call "
+            "zexl_check_connection."
+        )
+        return _result(
+            msg,
+            {
+                "workspace": body["workspace_name"],
+                "environment": body["environment"],
+                "env_file": str(written.path),
+                "gitignore": written.gitignore,
+            },
+        )
+
+    def _clear_pending(self) -> None:
+        self._pending = None
+        try:
+            (config.config_dir() / "pending.json").unlink()
+        except OSError:
+            pass
+
+    async def check_connection(self, wait_seconds: int) -> CallToolResult:
+        deadline = time.monotonic() + max(0, min(int(wait_seconds), 300))
+        while True:
+            ws, live = await self._get("/live")
+            recent = live.get("recent") or []
+            if recent:
+                last = recent[0]
+                msg = (
+                    f"Receiving: {live['calls']:,} calls in workspace {ws['name']} so far. Latest: "
+                    f"{last['model'] or 'unknown model'} at {last['ts']} ({last['environment']}, "
+                    f"{last['source']}), {last['input_tokens']:,} in / {last['output_tokens']:,} "
+                    f"out, {text.money(last['cost_usd'])}. Waste analysis follows within about 3 "
+                    "minutes."
+                )
+                return _result(msg, {"calls": live["calls"], "latest": last})
+            if time.monotonic() >= deadline:
+                return _result(
+                    "No calls yet. Check that the app ran a model call, that `import zexl.auto` "
+                    "runs before the client is created, and that ZEXL_API_KEY is set in that "
+                    "process "
+                    "(`zexl.status()` shows what the SDK sees). Then call this again.",
+                    {"calls": 0},
+                )
+            await self._sleep(3.0)
+
+    # --- reading ---
+
+    async def status(self) -> CallToolResult:
+        creds = config.load()
+        if creds is None:
+            return _result(
+                "Not connected. Use zexl_connect_start to connect this project, or set "
+                "ZEXL_READ_KEY.",
+                {"connected": False},
+            )
+        ws, live = await self._get("/live")
+        recent = live.get("recent") or []
+        env = ws.get("environment") or "all environments"
+        last = f" Latest call {recent[0]['ts']}." if recent else " No calls received yet."
+        return _result(
+            f"Connected to workspace {ws['name']} (reads {env}). {live['calls']:,} calls stored."
+            + last,
+            {"connected": True, "workspace": ws["name"], "calls": live["calls"]},
+        )
+
+    async def spend_summary(self, days: int, environment: str) -> CallToolResult:
+        days, q = _range(days)
+        ws, s = await self._get(f"/summary?{q}&environment={environment}")
+        env = self._env(ws, environment)
+        return _result(text.summary(s, days, env), s)
+
+    async def forecast(self, environment: str) -> CallToolResult:
+        _, f = await self._get(f"/forecast?environment={environment}")
+        data = {k: v for k, v in f.items() if k != "days"}
+        return _result(text.forecast(f), data)
+
+    async def top_waste(self, days: int, environment: str, limit: int) -> CallToolResult:
+        days, q = _range(days)
+        ws, p = await self._get(f"/patterns?{q}&environment={environment}")
+        env = self._env(ws, environment)
+        cards = p.get("cards", [])
+        return _result(text.cards(cards, max(1, min(limit, 20)), days, env), {"cards": cards})
+
+    async def breakdown(self, by: str, days: int, environment: str) -> CallToolResult:
+        days, q = _range(days)
+        ws, b = await self._get(f"/breakdown?by={by}&{q}&environment={environment}")
+        env = self._env(ws, environment)
+        return _result(text.breakdown(b["rows"], by, days, env), b)
+
+    async def pattern_runs(
+        self, category: str, feature: str | None, days: int, environment: str
+    ) -> CallToolResult:
+        days, q = _range(days)
+        extra = f"&feature={_quote(feature)}" if feature is not None else ""
+        _, r = await self._get(f"/patterns/{category}/runs?{q}&environment={environment}{extra}")
+        return _result(text.runs(r["runs"], category, feature), r)
+
+    async def run_detail(self, run_id: str) -> CallToolResult:
+        _, r = await self._get(f"/runs/{_quote(run_id)}")
+        return _result(text.run_detail(r), r)
+
+    async def explain_spike(self, day: str | None, days: int, environment: str) -> CallToolResult:
+        days, q = _range(max(days, 7))
+        ws, series = await self._get(f"/timeseries?{q}&environment={environment}")
+        points = series["days"]
+        if not any(p["tracked_usd"] > 0 for p in points):
+            return _result("No spend in this period.")
+        if day:
+            match = [p for p in points if p["day"] == day]
+            if not match:
+                raise ZexlError(f"{day} is not in the last {days} days. Pass days to widen it.")
+            peak = match[0]
+        else:
+            peak = max(points, key=lambda p: p["tracked_usd"])
+        others = [p["tracked_usd"] for p in points if p["day"] != peak["day"]]
+        median = statistics.median(others) if others else 0.0
+        d = date.fromisoformat(peak["day"])
+        one = f"from={d.isoformat()}&to={d.isoformat()}&environment={environment}"
+        whole = f"{q}&environment={environment}"
+        drivers: list[tuple[str, str, float, float]] = []
+        for by in ("feature", "model"):
+            _, on_day = await self._get(f"/breakdown?by={by}&{one}")
+            _, over = await self._get(f"/breakdown?by={by}&{whole}")
+            usual = {r["value"]: r["tracked_usd"] for r in over["rows"]}
+            n = max(len(points) - 1, 1)
+            for r in on_day["rows"]:
+                base = (usual.get(r["value"], 0.0) - r["tracked_usd"]) / n
+                if r["tracked_usd"] - base > 0:
+                    drivers.append((by, r["value"], r["tracked_usd"], max(base, 0.0)))
+        # Only differences that explain a real part of the extra spend.
+        floor = max(0.1 * (peak["tracked_usd"] - median), 0.01)
+        drivers = [t for t in drivers if t[2] - t[3] >= floor]
+        drivers.sort(key=lambda t: -(t[2] - t[3]))
+        top = drivers[:6]
+        return _result(
+            text.spike(peak, median, top),
+            {"day": peak, "median_usd": median, "drivers": [list(t) for t in top]},
+        )
+
+
+def _quote(value: str) -> str:
+    from urllib.parse import quote
+
+    return quote(value, safe="")
+
+
+def build(zexl: Zexl | None = None) -> FastMCP:
+    z = zexl or Zexl()
+    mcp = FastMCP("zexl", instructions=INSTRUCTIONS)
+
+    async def safe(coro: Any) -> CallToolResult:
+        try:
+            result: CallToolResult = await coro
+            return result
+        except ZexlError as e:
+            return _error(e)
+
+    @mcp.tool(annotations=READ)
+    async def zexl_status() -> CallToolResult:
+        """Whether this server is connected to a Zexl workspace, which one, and when the last
+        call arrived. Call this first if unsure."""
+        return await safe(z.status())
+
+    @mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
+    async def zexl_connect_start(project: str = "", client: str = "claude-code") -> CallToolResult:
+        """Start connecting this project to Zexl. Returns a link and a code to show the user;
+        they open it, sign up or sign in, and approve. Then call zexl_connect_finish.
+
+        project: a short name for the project, such as the repository name.
+        client: the AI tool you are, e.g. claude-code, claude-desktop or cursor."""
+        return await safe(z.connect_start(project, client))
+
+    @mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
+    async def zexl_connect_finish(env_file: str = ".env", wait_seconds: int = 90) -> CallToolResult:
+        """Wait for the user to approve the connect request, then write ZEXL_API_KEY into the
+        project's .env file and save a read key for these tools. The key is never returned to
+        you; code should read ZEXL_API_KEY from the environment.
+
+        env_file: path to the project's .env file; prefer an absolute path. Created if missing.
+        wait_seconds: how long to wait for approval in this call (up to 600)."""
+        return await safe(z.connect_finish(env_file, wait_seconds))
+
+    @mcp.tool(annotations=READ)
+    async def zexl_setup_guide(
+        target: Literal["python", "claude-code"] = "python",
+    ) -> CallToolResult:
+        """Exact steps to add Zexl to a project: where `import zexl.auto` goes, labels for
+        features, runs and customers, environments, and how to check it works.
+
+        target: python for an app using the OpenAI or Anthropic Python clients; claude-code to
+        track Claude Code itself."""
+        return _result(guide.TOPICS[target])
+
+    @mcp.tool(annotations=READ)
+    async def zexl_check_connection(wait_seconds: int = 60) -> CallToolResult:
+        """After the app has made a model call, wait for it to arrive in Zexl and report what
+        was recorded (model, tokens, cost). wait_seconds: up to 300."""
+        return await safe(z.check_connection(wait_seconds))
+
+    @mcp.tool(annotations=READ)
+    async def zexl_spend_summary(days: int = 30, environment: Env = "production") -> CallToolResult:
+        """Tracked spend, how much was wasted and on what, the useful-spend share, budget
+        headroom and invoice coverage.
+
+        days: the period, ending today (1 to 365).
+        environment: production, staging, development, or all."""
+        return await safe(z.spend_summary(days, environment))
+
+    @mcp.tool(annotations=READ)
+    async def zexl_forecast(environment: Env = "all") -> CallToolResult:
+        """Where this month's spend is likely to end, with a likely range, and the day it passes
+        the monthly budget if it does. Defaults to all environments, like the budget."""
+        return await safe(z.forecast(environment))
+
+    @mcp.tool(annotations=READ)
+    async def zexl_top_waste(
+        days: int = 30, environment: Env = "production", limit: int = 5
+    ) -> CallToolResult:
+        """The biggest waste findings (pattern and feature), each with its dollar size, a
+        plain explanation and how to fix it."""
+        return await safe(z.top_waste(days, environment, limit))
+
+    @mcp.tool(annotations=READ)
+    async def zexl_breakdown(
+        by: Literal["feature", "model", "customer", "actor"] = "feature",
+        days: int = 30,
+        environment: Env = "production",
+    ) -> CallToolResult:
+        """Spend, waste and useful share per feature, model, customer or actor (person or
+        service), biggest first."""
+        return await safe(z.breakdown(by, days, environment))
+
+    @mcp.tool(annotations=READ)
+    async def zexl_explain_spike(
+        day: str | None = None, days: int = 30, environment: Env = "production"
+    ) -> CallToolResult:
+        """Explain a day of unusually high spend: how far above a usual day it was, the waste
+        that day, and which features and models made the difference.
+
+        day: YYYY-MM-DD; omitted means the highest day in the period."""
+        return await safe(z.explain_spike(day, days, environment))
+
+    @mcp.tool(annotations=READ)
+    async def zexl_pattern_runs(
+        category: Category,
+        feature: str | None = None,
+        days: int = 30,
+        environment: Env = "production",
+    ) -> CallToolResult:
+        """The runs behind one waste finding, worst first. Use the category and feature from
+        zexl_top_waste."""
+        return await safe(z.pattern_runs(category, feature, days, environment))
+
+    @mcp.tool(annotations=READ)
+    async def zexl_run_detail(run_id: str) -> CallToolResult:
+        """One run step by step: model, tokens and cost per step, and which steps repeated an
+        earlier request, input or tool call, failed, or were cut off."""
+        return await safe(z.run_detail(run_id))
+
+    @mcp.prompt()
+    def integrate_zexl(project: str = "") -> str:
+        """Add Zexl to this project, from connecting to the first recorded call."""
+        name = f" (project: {project})" if project else ""
+        return (
+            f"Add Zexl to this project{name}.\n"
+            "1. Call zexl_connect_start with the project name, and show me the link and the code.\n"
+            "2. When I say I have approved, call zexl_connect_finish with the absolute path of "
+            "the project's .env file.\n"
+            "3. Call zexl_setup_guide and make the code changes it describes: add the dependency, "
+            "add `import zexl.auto` at the entry point, and add feature labels where the app calls "
+            "a model. Show me the diff.\n"
+            "4. Tell me how to run the app once, then call zexl_check_connection.\n"
+            "Never print the key or ask me to paste it."
+        )
+
+    return mcp
+
+
+def main() -> None:
+    build().run("stdio")
+
+
+if __name__ == "__main__":
+    main()

zexl_mcp-0.1.0/src/zexl_mcp/text.py

@@ -0,0 +1,220 @@
+"""Turns API answers into short sentences, the dollar figure first. Pure functions; tested."""
+
+from __future__ import annotations
+
+from typing import Any
+
+TITLES = {
+    "retry": "Retries",
+    "loop": "Loops",
+    "abandoned": "Abandoned responses",
+    "truncate_redo": "Cut off and redone",
+    "cache_miss": "Prompt caching not used",
+    "context_growth": "Growing context",
+}
+
+FIXES = {
+    "retry": "Find why the calls fail (timeouts, rate limits, bad requests). Raise the client "
+    "timeout for long answers, back off on 429s, and stop retrying errors that will fail again.",
+    "loop": "Give the agent a step limit and stop when a tool returns the same result twice. "
+    "Open a run with zexl_run_detail to see which step repeats.",
+    "abandoned": "A stream was started and never read to the end, or the client gave up. Cancel "
+    "requests you no longer need early, or do not start them; check client timeouts.",
+    "truncate_redo": "Answers hit the output limit and were asked again. Raise max_tokens for "
+    "this feature, or ask for a shorter answer, so the first attempt is enough.",
+    "cache_miss": "Turn on prompt caching for the long fixed part of the prompt: put the system "
+    "prompt and tool definitions first and unchanged. Anthropic needs cache_control on them; "
+    "OpenAI caches prompts over 1,024 tokens automatically when the start is identical.",
+    "context_growth": "The input grows every step. Summarise or trim the history, or pass tool "
+    "results by reference. Not counted as waste.",
+}
+
+
+def money(usd: float | None) -> str:
+    if usd is None:
+        return "–"
+    if usd >= 100:
+        return f"${usd:,.0f}"
+    if usd >= 0.995:
+        return f"${usd:,.2f}"
+    if usd >= 0.01:
+        return f"${usd:.2f}"
+    if usd > 0:
+        return f"${usd:.4f}".rstrip("0")
+    return "$0"
+
+
+def pct(share: float | None) -> str:
+    return "–" if share is None else f"{100 * share:.0f}%"
+
+
+def scope(days: int, environment: str) -> str:
+    env = "all environments" if environment == "all" else environment
+    return f"last {days} days, {env}"
+
+
+def summary(s: dict[str, Any], days: int, environment: str) -> str:
+    if not s.get("calls"):
+        return f"No calls in the {scope(days, environment)}."
+    est = "About " if s.get("is_estimate") else ""
+    lines = [
+        f"{money(s['tracked_usd'])} tracked spend ({scope(days, environment)}), "
+        f"{s['calls']:,} calls. {est}{money(s['waste_usd'])} wasted; "
+        f"{pct(s.get('useful_share'))} did useful work."
+    ]
+    waste = sorted(s.get("waste", []), key=lambda w: -w["usd"])
+    for w in waste:
+        if w["usd"] > 0:
+            mark = " (estimate)" if w.get("is_estimate") else ""
+            lines.append(
+                f"- {TITLES.get(w['category'], w['category'])}: {money(w['usd'])}{mark}, "
+                f"{w['calls']:,} calls"
+            )
+    growth = s.get("context_growth") or {}
+    if growth.get("runs"):
+        lines.append(
+            f"- Growing context in {growth['runs']:,} runs cost {money(growth['exposure_usd'])} "
+            "extra (not counted as waste)."
+        )
+    b = s.get("budget") or {}
+    if b.get("monthly_usd") is not None:
+        lines.append(
+            f"Budget: {money(b['month_spend_usd'])} of {money(b['monthly_usd'])} spent this "
+            f"month (all environments), {money(max(b['headroom_usd'], 0))} left."
+        )
+    c = s.get("coverage")
+    if c:
+        lines.append(
+            f"Coverage: Zexl tracked {pct(c['share'])} of the {money(c['invoiced_usd'])} on "
+            "entered provider invoices."
+        )
+    unpriced = s.get("unpriced_models") or []
+    if unpriced:
+        names = ", ".join(m["model"] for m in unpriced)
+        lines.append(f"No price known for {names}; those calls count as $0.")
+    return "\n".join(lines)
+
+
+def forecast(f: dict[str, Any]) -> str:
+    if f["method"] == "none":
+        return "No calls yet this month, so there is nothing to forecast."
+    env = "all environments" if f["environment"] == "all" else f["environment"]
+    out = [
+        f"About {money(f['projected_usd'])} by the end of {f['month']} ({env}); likely between "
+        f"{money(f['low_usd'])} and {money(f['high_usd'])}. Spent so far: "
+        f"{money(f['spent_usd'])}. Last 7 days averaged {money(f['last7_daily_usd'])} a day."
+    ]
+    if f.get("budget_usd") is not None:
+        if f.get("crosses_budget_on"):
+            out.append(
+                f"At this trend it passes the {money(f['budget_usd'])} budget around "
+                f"{f['crosses_budget_on']}."
+            )
+        else:
+            out.append(f"At this trend it stays within the {money(f['budget_usd'])} budget.")
+    how = (
+        "pace so far (under 3 full days of data)"
+        if f["method"] == "pace"
+        else f"weighted trend of the last {f['days_used']} full days"
+    )
+    out.append(f"Method: {how}.")
+    return " ".join(out)
+
+
+def cards(rows: list[dict[str, Any]], limit: int, days: int, environment: str) -> str:
+    waste = [r for r in rows if r.get("kind") != "exposure" and r["usd"] > 0]
+    growth = [r for r in rows if r.get("kind") == "exposure"]
+    if not waste and not growth:
+        return f"No waste found in the {scope(days, environment)}."
+    out = [f"Biggest waste, {scope(days, environment)}:"]
+    for i, r in enumerate(sorted(waste, key=lambda r: -r["usd"])[:limit], 1):
+        out.append(
+            f"{i}. {money(r['usd'])} {r['title']} in {r['feature'] or 'unlabelled calls'}. "
+            f"{r['sentence']}\n   Fix: {FIXES.get(r['category'], '')}\n"
+            f"   Runs: zexl_pattern_runs(category='{r['category']}', feature='{r['feature']}')"
+        )
+    for r in growth[:3]:
+        out.append(f"Also: {r['sentence']}")
+    return "\n".join(out)
+
+
+def breakdown(rows: list[dict[str, Any]], by: str, days: int, environment: str) -> str:
+    if not rows:
+        return f"No calls in the {scope(days, environment)}."
+    out = [f"Spend by {by}, {scope(days, environment)}:"]
+    for r in rows[:25]:
+        est = "≈" if r.get("is_estimate") else ""
+        out.append(
+            f"- {r['value'] or '(none)'}: {money(r['tracked_usd'])}, {est}{money(r['waste_usd'])} "
+            f"wasted, {pct(r.get('useful_share'))} useful, {r['calls']:,} calls"
+        )
+    if len(rows) > 25:
+        out.append(f"…and {len(rows) - 25} more.")
+    return "\n".join(out)
+
+
+def runs(rows: list[dict[str, Any]], category: str, feature: str | None) -> str:
+    title = TITLES.get(category, category)
+    where = f" in {feature}" if feature else ""
+    if not rows:
+        return f"No runs with {title.lower()}{where} in this period."
+    out = [f"Runs with {title.lower()}{where}, worst first:"]
+    for r in rows[:20]:
+        steps = f", {r['run_steps']} steps" if r.get("run_steps") else ""
+        total = f" of {money(r['run_cost_usd'])}" if r.get("run_cost_usd") is not None else ""
+        out.append(
+            f"- {r['run_id']}: {money(r['usd'])} wasted{total}{steps}, started {r['started_at']}"
+        )
+    out.append("Open one with zexl_run_detail(run_id=...).")
+    return "\n".join(out)
+
+
+def run_detail(r: dict[str, Any]) -> str:
+    flags = f" Flags: {', '.join(r['flags'])}." if r.get("flags") else ""
+    out = [
+        f"Run {r['run_id']} ({r['feature'] or 'unlabelled'}, {r['environment']}): "
+        f"{money(r['cost_usd'])} over {r['steps']} steps, {money(r['waste_usd'])} wasted.{flags}"
+    ]
+    for s in r.get("timeline", [])[:60]:
+        notes = []
+        same = s.get("same_as") or {}
+        if same.get("request"):
+            notes.append(f"same request as step {same['request']}")
+        elif same.get("input"):
+            notes.append(f"same input as step {same['input']}")
+        elif same.get("tools"):
+            notes.append(f"same tool calls as step {same['tools']}")
+        if s.get("finish_reason") in ("length", "max_tokens"):
+            notes.append("cut off at the output limit")
+        if s.get("error_type") or (s.get("status_code") or 200) >= 400:
+            notes.append(f"error {s.get('error_type') or s.get('status_code')}")
+        if s.get("streamed") and not s.get("stream_completed"):
+            notes.append("stream not finished")
+        tools = f" tools: {', '.join(s['tool_calls'])}" if s.get("tool_calls") else ""
+        cat = "" if s["category"] == "useful" else f" [{s['category']} {money(s['waste_usd'])}]"
+        note = f" — {'; '.join(notes)}" if notes else ""
+        out.append(
+            f"{s['position']}. {s['model']} {s['input_tokens']:,} in / {s['output_tokens']:,} out, "
+            f"{money(s['cost_usd'])}{cat}{tools}{note}"
+        )
+    return "\n".join(out)
+
+
+def spike(day: dict[str, Any], median: float, drivers: list[tuple[str, str, float, float]]) -> str:
+    extra = day["tracked_usd"] - median
+    out = [
+        f"{day['day']}: {money(day['tracked_usd'])}, {money(extra)} above the median day "
+        f"({money(median)})."
+    ]
+    waste = sum(day.get("waste", {}).values())
+    if waste > 0:
+        top = max(day["waste"].items(), key=lambda kv: kv[1])
+        out.append(
+            f"Waste that day: {money(waste)}, mostly {TITLES.get(top[0], top[0]).lower()} "
+            f"({money(top[1])})."
+        )
+    if drivers:
+        out.append("What changed against a usual day:")
+        for kind, value, usd, usual in drivers:
+            out.append(f"- {kind} {value or '(none)'}: {money(usd)} vs {money(usual)} usually")
+    return "\n".join(out)