cortad 0.1.6 → 0.1.9

package/lib/door.mjs

@@ -14,9 +14,12 @@ const ENV_FILE = /^\.env(\..*)?$/;
 const KEY_FILE = /^(?:id_(?:rsa|ed25519|ecdsa).*|.*\.(?:pem|key|p12|pfx|jks|keystore)|\.npmrc|\.netrc|\.pypirc)$/;
 const CLOSED_DIR = new Set([".git", "node_modules", ".ssh", ".aws", ".gnupg"]);
 
-export function openDoor(root, { store = join(homedir(), ".cortad", "checkpoints") } = {}) {
+// `owner` names whose checkpoints these are: the account and connection the server attached this
+// folder to. Keyed by the folder alone, a second account on the same folder was shown the first
+// account's edits as its own.
+export function openDoor(root, { store = join(homedir(), ".cortad", "checkpoints"), owner = "" } = {}) {
   const realRoot = realpathSync(root);
-  const dir = join(store, sha(realRoot).slice(0, 16));
+  const dir = join(store, sha(`${owner}\0${realRoot}`).slice(0, 16));
   const blobs = join(dir, "blobs");
   const journalFile = join(dir, "journal.json");
   mkdirSync(blobs, { recursive: true });

package/lib/identities.mjs

@@ -40,10 +40,12 @@ export function identityCurlArg(as) {
 
 // Every string the recipes carry reaches the program as base64 JSON, never as source, and only
 // after the charset gate: a route or a role is read from a repository.
-export function identityScript(recipes, target) {
+export function identityScript(recipes, target, accounts = {}) {
   const safe = recipes.filter(safeRecipe).slice(0, 12);
   const headers = Object.fromEntries(Object.entries(target.headers ?? {}).filter(([k, v]) => HEADER.test(k) && typeof v === "string" && v.length <= 300 && !/[\r\n]/.test(v)));
-  const plan = { envPath: /^[\w./-]+$/.test(target.envPath) ? target.envPath : "/workspace/repo/.env", base: BASE.test(target.base) ? target.base : "http://127.0.0.1:0", headers, recipes: safe };
+  const kept = Object.fromEntries(Object.entries(accounts).filter(([role, a]) => ROLE.test(role) && a
+    && ["username", "email", "password", "name"].every((f) => typeof a[f] === "string" && a[f].length <= 120 && !/[\r\n]/.test(a[f]))));
+  const plan = { envPath: /^[\w./-]+$/.test(target.envPath) ? target.envPath : "/workspace/repo/.env", base: BASE.test(target.base) ? target.base : "http://127.0.0.1:0", headers, recipes: safe, accounts: kept };
   return PROGRAM
     .replace("__PLAN__", Buffer.from(JSON.stringify(plan), "utf8").toString("base64"))
     .replace("__OUT__", IDENTITY_OUT)
@@ -68,7 +70,10 @@ PLAN = json.loads(base64.b64decode("__PLAN__").decode("utf-8"))
 OUT = "__OUT__"
 FILE = "__FILE__"
 TTL = 6 * 3600
-TEST = "cortad-test-user"
+# Digits only: an account column is an integer in Strapi, Django and Rails, and a word here makes
+# the database itself raise. Nonerds crashed its whole process on "cortad-test-user". Digits are a
+# valid string id too, so this one value fits both kinds of account table.
+TEST = "9000001"
 # A dev server compiles its auth route on the first request: better-chatbot's sign-in timed out at 10s
 # and the caller was filed unreachable. The whole program stays inside the step's two minutes.
 DEADLINE = time.time() + 100
@@ -96,7 +101,11 @@ def slug(role):
     return re.sub(r"[^a-z0-9-]", "-", role)
 
 
+# One account per role, made once and signed into on every later run: a fresh account per run left
+# 1,600 active test logins in one app's own account store.
 def gen(role):
+    if role in PLAN.get("accounts", {}):
+        return PLAN["accounts"][role]
     tag = secrets.token_hex(4)
     return {
         "username": "cortad-%s-%s" % (slug(role), tag),
@@ -206,6 +215,9 @@ def walk(steps, recipe, env, g, role_value):
             return {"status": "unreachable", "note": text}
         if status >= 400 and unset:
             return {"status": "absent", "note": unset}
+        # The account this role was given on an earlier run is still there: go on and sign in.
+        if status in (400, 409, 422) and step is not steps[-1] and re.search(r"exist|taken|already|duplicate|in use|registered", text or "", re.I):
+            continue
         if status >= 400:
             said = re.sub(r"\s+", " ", re.sub(r"<[^>]+>", "", text or "")).strip()[:160]
             return {"status": "refused", "note": "HTTP %d at %s%s" % (status, step["route"], (": " + said) if said else "")}

package/lib/listing.mjs

@@ -0,0 +1,12 @@
+// Where a provider key is asked for its model listing: the base URL their app is pointed at, when
+// their env sets one beside the key (OPENAI_BASE_URL beside OPENAI_API_KEY), else the provider's own
+// host. A Fireworks key under OPENAI_API_KEY is refused by api.openai.com and works where it is sent.
+export function listingUrl(name, canonical, values) {
+  const prefix = name.replace(/_API_KEY$/, "");
+  const base = values[`${prefix}_BASE_URL`] || values[`${prefix}_API_BASE`];
+  if (!base) return canonical;
+  try {
+    const u = new URL(base);
+    return /^https?:$/.test(u.protocol) ? `${base.replace(/\/+$/, "")}/models` : canonical;
+  } catch { return canonical; }
+}

package/lib/mint.mjs

@@ -5,8 +5,9 @@
 // a role arrives carrying a marker; the real header is put in its place here, so neither a secret
 // nor a token ever leaves this machine.
 import { execFile } from "node:child_process";
-import { createSign } from "node:crypto";
+import { createHmac, createSign, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { identityScript, parseIdentityReport } from "./identities.mjs";
@@ -17,6 +18,18 @@ const ROLE = /^[a-z][a-z0-9_-]{0,30}(?::[a-z][a-z0-9_-]{0,30})?$/;
 const slug = (role) => role.replace(/[^a-z0-9-]/g, "-");
 const TEST_UID = "brainsless-test-user";
 
+// The account each role signs in as, the same on every run from this folder: derived from a key that
+// never leaves this machine, so no server holds a password to any of their accounts.
+export function accountsFor(root, roles, keyFile = join(homedir(), ".cortad", "identity.key")) {
+  if (!existsSync(keyFile)) { mkdirSync(dirname(keyFile), { recursive: true, mode: 0o700 }); writeFileSync(keyFile, randomBytes(32), { mode: 0o600 }); }
+  const key = readFileSync(keyFile);
+  const mac = (what) => createHmac("sha256", key).update(`${what}\0${root}`).digest("base64url");
+  return Object.fromEntries(roles.filter((role) => ROLE.test(role)).map((role) => {
+    const username = `cortad-${slug(role)}-${mac(`name\0${role}`).replace(/[^a-z0-9]/gi, "").slice(0, 8).toLowerCase()}`;
+    return [role, { username, email: `${username}@example.invalid`, password: `${mac(`pw\0${role}`).slice(0, 24)}A1!`, name: `Cortad test ${role}` }];
+  }));
+}
+
 // Who this machine signs in as, whatever a recipe asks: an account made for the session, or a test
 // id that belongs to nobody. Never a person who already has an account, never an admin, and never a
 // key the app does not already hand to every browser. The recipes come from the cloud; these rules
@@ -130,7 +143,10 @@ export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], s
     const refused = new Map();
     for (const r of recipes) { const why = refusal(r, merged, (value) => inSource(root, sourceFiles(), value)); if (why && typeof r?.role === "string") refused.set(r.role, why); }
     const forProgram = recipes.filter((r) => !refused.has(r?.role) && (r?.kind !== "firebase" || emulated));
-    const script = identityScript(forProgram, { envPath: envs().path, base: `http://127.0.0.1:${port}`, headers: body?.headers ?? {} }).split("/tmp/bl-identit").join(join(dir, "bl-identit"));
+    // The program signs in once per role value ("staff" as sales, support, marketing), each named
+    // role:value; an account made for "staff" alone was never the one it asked for.
+    const accounts = accountsFor(root, forProgram.flatMap((r) => (Array.isArray(r.roles) && r.roles.length ? r.roles.map((v) => `${r.role}:${v}`) : [r.role])));
+    const script = identityScript(forProgram, { envPath: envs().path, base: `http://127.0.0.1:${port}`, headers: body?.headers ?? {} }, accounts).split("/tmp/bl-identit").join(join(dir, "bl-identit"));
     const file = join(dir, "mint.py");
     writeFileSync(file, script, { mode: 0o600 });
     const ran = forProgram.length ? await exec("python3", [file], { cwd: root, timeout: 115_000, maxBuffer: 1 << 20 }).then(() => true, (e) => e?.code !== "ENOENT") : true;

package/lib/pyhook/sitecustomize.py

@@ -22,7 +22,7 @@ def _install():
     ctx = contextvars.ContextVar("cortad_request", default=None)
     limit = 65536
     said = set()
-    model_host = re.compile(r"(?:^|\.)(?:openai\.com|anthropic\.com|fireworks\.ai|openrouter\.ai|groq\.com|mistral\.ai|together\.xyz|together\.ai|deepseek\.com|cohere\.ai|cohere\.com|perplexity\.ai|x\.ai|openai\.azure\.com|cognitiveservices\.azure\.com|replicate\.com|huggingface\.co|cerebras\.ai|deepinfra\.com|novita\.ai|moonshot\.cn|dashscope\.aliyuncs\.com|bigmodel\.cn)$", re.I)
+    model_host = re.compile(r"(?:^|\.)(?:openai\.com|anthropic\.com|fireworks\.ai|openrouter\.ai|groq\.com|mistral\.ai|together\.xyz|together\.ai|deepseek\.com|cohere\.ai|cohere\.com|perplexity\.ai|x\.ai|openai\.azure\.com|cognitiveservices\.azure\.com|replicate\.com|huggingface\.co|cerebras\.ai|deepinfra\.com|novita\.ai|moonshot\.cn|dashscope\.aliyuncs\.com|bigmodel\.cn|ai-gateway\.vercel\.sh|gateway\.ai\.cloudflare\.com|helicone\.ai|portkey\.ai)$", re.I)
     model_path = re.compile(r"/(?:chat/completions|completions|responses|messages|embeddings)$|:(?:generateContent|streamGenerateContent)|/invoke(?:-with-response-stream)?$|/api/(?:chat|generate)$", re.I)
 
     def write(row):
@@ -70,6 +70,88 @@ def _install():
         write({"at": int(time.time() * 1000), "method": req["method"], "path": req["path"], "headers": req["headers"],
                "body": b"".join(req["chunks"]).decode("utf-8", "replace")[:limit], "sent": text(body)})
 
+    # The meter: one row per model call your app makes, with the provider's own token counts and
+    # never the reply's text.
+    reply_max = 8 * 1024 * 1024
+
+    def number(v):
+        return v if isinstance(v, int) and not isinstance(v, bool) and v > 0 else 0
+
+    def tokens_of(u):
+        if not isinstance(u, dict):
+            return None
+        if isinstance(u.get("tokens"), dict):
+            return tokens_of(u["tokens"])
+        if "prompt_tokens" in u:
+            return {"promptTokens": number(u.get("prompt_tokens")), "cachedTokens": number((u.get("prompt_tokens_details") or {}).get("cached_tokens")), "completionTokens": number(u.get("completion_tokens"))}
+        if "input_tokens" in u and isinstance(u.get("input_tokens_details"), dict):
+            return {"promptTokens": number(u.get("input_tokens")), "cachedTokens": number(u["input_tokens_details"].get("cached_tokens")), "completionTokens": number(u.get("output_tokens"))}
+        if "input_tokens" in u:
+            read = number(u.get("cache_read_input_tokens"))
+            return {"promptTokens": number(u.get("input_tokens")) + read + number(u.get("cache_creation_input_tokens")), "cachedTokens": read, "completionTokens": number(u.get("output_tokens"))}
+        if "inputTokens" in u:
+            read = number(u.get("cacheReadInputTokens"))
+            return {"promptTokens": number(u.get("inputTokens")) + read + number(u.get("cacheWriteInputTokens")), "cachedTokens": read, "completionTokens": number(u.get("outputTokens"))}
+        if "promptTokenCount" in u:
+            return {"promptTokens": number(u.get("promptTokenCount")), "cachedTokens": number(u.get("cachedContentTokenCount")), "completionTokens": number(u.get("candidatesTokenCount"))}
+        return None
+
+    def parsed(raw):
+        try:
+            return json.loads(raw)
+        except (TypeError, ValueError):
+            return None
+
+    def read_reply(kind, raw):
+        if "event-stream" in (kind or "").lower():
+            events = [parsed(line[5:].strip()) for line in raw.split("\n") if line.startswith("data:")]
+        else:
+            body = parsed(raw)
+            events = body if isinstance(body, list) else [body]
+        usage, model = {}, None
+        for e in events:
+            if not isinstance(e, dict):
+                continue
+            msg = e["message"] if isinstance(e.get("message"), dict) else {}
+            resp = e["response"] if isinstance(e.get("response"), dict) else {}
+            part = e.get("usage") or msg.get("usage") or resp.get("usage") or e.get("usageMetadata")
+            if isinstance(part, dict):
+                usage.update(part)
+            model = e.get("model") or msg.get("model") or resp.get("model") or e.get("modelVersion") or model
+        return tokens_of(usage or None), model
+
+    def asked_for(url, sent):
+        body = parsed(sent) if isinstance(sent, str) else None
+        if isinstance(body, dict) and isinstance(body.get("model"), str):
+            return body["model"]
+        m = re.search(r"/models/([^/:]+):|/model/([^/]+)/(?:invoke|converse)", urlsplit(str(url)).path or "")
+        return (m.group(1) or m.group(2)) if m else ""
+
+    def unpacked(raw, encoding):
+        import zlib
+        try:
+            e = (encoding or "").lower()
+            if e == "gzip":
+                raw = zlib.decompress(raw, 16 + zlib.MAX_WBITS)
+            elif e == "deflate":
+                raw = zlib.decompress(raw)
+            elif e == "br":
+                return ""
+            return raw.decode("utf-8", "replace")
+        except Exception:
+            return ""
+
+    def meter(url, sent, status, kind, raw):
+        try:
+            tokens, model = read_reply(kind, (raw or "")[:reply_max])
+            parts = urlsplit(str(url))
+            row = {"at": int(time.time() * 1000), "host": parts.netloc.replace(":443", ""), "model": str(asked_for(url, sent) or model or "")[:160],
+                   "status": int(status or 0), "usage": tokens is not None}
+            row.update(tokens or {"promptTokens": 0, "cachedTokens": 0, "completionTokens": 0})
+            write({"call": row})
+        except Exception:
+            pass
+
     def started(method, path, headers):
         return {"method": method, "path": path, "headers": headers, "chunks": [], "size": 0, "noted": False}
 
@@ -175,6 +257,8 @@ def _install():
             out = load(self, *a, **k)
             if not isinstance(self.loaded_app, Asgi):
                 self.loaded_app = Asgi(self.loaded_app)
+            if isinstance(getattr(self, "port", None), int):
+                write({"listen": self.port, "pid": os.getpid()})
             return out
 
         module.Config.load = loaded
@@ -183,6 +267,8 @@ def _install():
         run_simple = module.run_simple
 
         def run(hostname, port, application, *a, **k):
+            if isinstance(port, int):
+                write({"listen": port, "pid": os.getpid()})
             return run_simple(hostname, port, wsgi(application), *a, **k)
 
         module.run_simple = run
@@ -195,30 +281,107 @@ def _install():
 
         module.WSGIHandler.__call__ = called
 
+    def sent_of(request):
+        try:
+            return text(request.content)
+        except Exception:
+            return ""
+
     def patch_httpx(module):
+        # A streamed reply is read by your app after send returns: its raw bytes are kept as they go
+        # past and the row is written when the stream closes. A read reply is metered at once.
+        class Kept:
+            def __init__(self, stream, done):
+                self.stream, self.done, self.got, self.size = stream, done, [], 0
+
+            def keep(self, chunk):
+                if self.size < reply_max:
+                    self.got.append(bytes(chunk))
+                    self.size += len(chunk)
+
+            def finish(self):
+                done, self.done = self.done, None
+                if done:
+                    done(b"".join(self.got))
+
+        class SyncKept(module.SyncByteStream, Kept):
+            def __iter__(self):
+                for chunk in self.stream:
+                    self.keep(chunk)
+                    yield chunk
+
+            def close(self):
+                try:
+                    self.stream.close()
+                finally:
+                    self.finish()
+
+        class AsyncKept(module.AsyncByteStream, Kept):
+            async def __aiter__(self):
+                async for chunk in self.stream:
+                    self.keep(chunk)
+                    yield chunk
+
+            async def aclose(self):
+                try:
+                    await self.stream.aclose()
+                finally:
+                    self.finish()
+
+        def watch(request, response, sent):
+            if not is_model_call(request.url):
+                return response
+            kind = response.headers.get("content-type", "")
+            if getattr(response, "_content", None) is not None:
+                meter(request.url, sent, response.status_code, kind, response.content.decode("utf-8", "replace"))
+                return response
+            done = lambda raw: meter(request.url, sent, response.status_code, kind, unpacked(raw, response.headers.get("content-encoding")))
+            stream = response.stream
+            if hasattr(stream, "__aiter__") and hasattr(stream, "aclose"):
+                response.stream = AsyncKept(stream, done)
+            elif hasattr(stream, "__iter__"):
+                response.stream = SyncKept(stream, done)
+            else:
+                meter(request.url, sent, response.status_code, kind, "")
+            return response
+
         for cls in (module.Client, module.AsyncClient):
             send = cls.send
             if cls is module.Client:
                 def sync_send(self, request, *a, _send=send, **k):
+                    sent = sent_of(request)
+                    try:
+                        note(request.url, sent)
+                    except Exception:
+                        pass
+                    try:
+                        response = _send(self, request, *a, **k)
+                    except Exception:
+                        if is_model_call(request.url):
+                            meter(request.url, sent, 0, "", "")
+                        raise
                     try:
-                        note(request.url, request.content)
+                        return watch(request, response, sent)
                     except Exception:
-                        try:
-                            note(request.url, None)
-                        except Exception:
-                            pass
-                    return _send(self, request, *a, **k)
+                        return response
                 cls.send = sync_send
             else:
                 async def async_send(self, request, *a, _send=send, **k):
+                    sent = sent_of(request)
+                    try:
+                        note(request.url, sent)
+                    except Exception:
+                        pass
+                    try:
+                        response = await _send(self, request, *a, **k)
+                    except Exception:
+                        if is_model_call(request.url):
+                            meter(request.url, sent, 0, "", "")
+                        raise
                     try:
-                        note(request.url, request.content)
+                        return watch(request, response, sent)
                     except Exception:
-                        try:
-                            note(request.url, None)
-                        except Exception:
-                            pass
-                    return await _send(self, request, *a, **k)
+                        return response
                 cls.send = async_send
 
     def patch_requests(module):
@@ -229,7 +392,15 @@ def _install():
                 note(request.url, request.body)
             except Exception:
                 pass
-            return send(self, request, *a, **k)
+            response = send(self, request, *a, **k)
+            try:
+                if is_model_call(request.url):
+                    # A streamed reply is counted as a call whose counts were not read.
+                    raw = response.content.decode("utf-8", "replace") if getattr(response, "_content_consumed", False) else ""
+                    meter(request.url, text(request.body), response.status_code, response.headers.get("content-type", ""), raw)
+            except Exception:
+                pass
+            return response
 
         module.Session.send = sent
 
@@ -237,13 +408,37 @@ def _install():
         request = module.ClientSession._request
 
         async def requested(self, method, str_or_url, *a, **k):
+            body = k.get("json") if k.get("json") is not None else k.get("data")
             try:
-                note(str_or_url, k.get("json") if k.get("json") is not None else k.get("data"))
+                note(str_or_url, body)
             except Exception:
                 pass
-            return await request(self, method, str_or_url, *a, **k)
+            response = await request(self, method, str_or_url, *a, **k)
+            if is_model_call(str_or_url):
+                response._cortad = (str_or_url, text(body))
+            return response
+
+        # Metered when your app reads the reply, or, for one it streams, when the reply is let go.
+        read, release = module.ClientResponse.read, module.ClientResponse.release
+
+        async def read_kept(self, *a, **k):
+            raw = await read(self, *a, **k)
+            call = getattr(self, "_cortad", None)
+            if call:
+                self._cortad = None
+                meter(call[0], call[1], self.status, self.headers.get("content-type", ""), (raw or b"").decode("utf-8", "replace"))
+            return raw
+
+        def release_kept(self, *a, **k):
+            call = getattr(self, "_cortad", None)
+            if call:
+                self._cortad = None
+                meter(call[0], call[1], self.status, self.headers.get("content-type", ""), "")
+            return release(self, *a, **k)
 
         module.ClientSession._request = requested
+        module.ClientResponse.read = read_kept
+        module.ClientResponse.release = release_kept
 
     exact = {"uvicorn.config": patch_uvicorn, "werkzeug.serving": patch_werkzeug, "django.core.handlers.wsgi": patch_django,
              "requests.sessions": patch_requests, "aiohttp.client": patch_aiohttp}

package/lib/replay.mjs

@@ -1,7 +1,8 @@
 // The other half of lib/trace.cjs: the command's side. It hands the hook to the app it starts,
 // reads what the hook wrote, keeps the sign-in that request carried on this machine, and tells the
 // cloud only what it needs to ask again: the route, the method and the body.
-import { readFileSync, statSync } from "node:fs";
+import { copyFileSync, mkdtempSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -17,12 +18,19 @@ export function makeCapture({ work, keepSecret, onDoor }) {
   let read = 0;
   let held = null;
   let alive = false;
-  // Both hooks are handed to whatever is started: a Node app loads the first, a Python app the
-  // second, and each ignores the other's variable.
-  // ponytail: Node and Python. Go, Ruby, Java and PHP apps are asked for their route on the screen.
+  // The ports a hooked process listens on. Loading is not listening: turbo's own Node launcher loads
+  // the hook, and databuddy was told we would see its messages while its API on Bun carried none.
+  const ports = new Set();
+  // Bun reads BUN_OPTIONS and splits it on spaces, quotes included, and only the `--preload=` form
+  // leaves `bun run <script>` working. A hook path with a space in it is copied to one without.
+  const bunHook = /\s/.test(HOOK) ? (() => { const at = join(mkdtempSync(join(tmpdir(), "cortad-")), "trace.cjs"); copyFileSync(HOOK, at); return at; })() : HOOK;
+  // The hooks are handed to whatever is started: a Node app loads the first, a Bun app the same file
+  // through its own variable, a Python app the second, and each ignores the others' variables.
+  // ponytail: Node, Bun and Python. Go, Ruby, Java and PHP apps are asked for their route on the screen.
   const env = (base) => ({
     CORTAD_TRACE_FILE: file,
     NODE_OPTIONS: `${base.NODE_OPTIONS ?? ""} --require ${JSON.stringify(HOOK)}`.trim(),
+    BUN_OPTIONS: `${base.BUN_OPTIONS ?? ""} --preload=${bunHook}`.trim(),
     PYTHONPATH: [PYHOOK, base.PYTHONPATH].filter(Boolean).join(":"),
   });
 
@@ -30,11 +38,15 @@ export function makeCapture({ work, keepSecret, onDoor }) {
     let size = 0;
     try { size = statSync(file).size; } catch { return; }
     if (size <= read) return;
-    const fresh = readFileSync(file, "utf8").slice(read);
+    // Bytes, not characters: a reply in Arabic put the next read in the middle of a line.
+    const fresh = readFileSync(file).subarray(read, size).toString("utf8");
     read = size;
     for (const line of fresh.split("\n").filter(Boolean)) {
       let row; try { row = JSON.parse(line); } catch { continue; }
       if (row.hello) { alive = true; continue; }
+      if (Number.isInteger(row.listen)) { ports.add(row.listen); continue; }
+      if (row.call) { meter.add(row.call); continue; }
+      if (row.dep) { meter.dep(row.dep); continue; }
       let body; try { body = JSON.parse(row.body); } catch { continue; }
       if (!body || typeof body !== "object" || typeof row.path !== "string" || !row.path.startsWith("/")) continue;
       const headers = Object.fromEntries(Object.entries(row.headers ?? {}).filter(([k, v]) => !HOP.test(k) && typeof v === "string"));
@@ -45,5 +57,59 @@ export function makeCapture({ work, keepSecret, onDoor }) {
   }
   const timer = setInterval(poll, 700);
   timer.unref();
-  return { env, headers: () => held?.headers ?? null, alive: () => { poll(); return alive; } };
+  return {
+    env,
+    headers: () => held?.headers ?? null,
+    // A message sent to the app on `port` can be seen arriving. A hook that has not said where it
+    // listens (Django under runserver) is taken at its hello, as before.
+    watching: (port) => { poll(); return ports.has(port) || (alive && ports.size === 0); },
+    alive: () => { poll(); return alive; },
+    // What your app spent on its model providers since it started, as the hook saw each call. Null
+    // when no hook is in your app (an app this command did not start): absent, never zero.
+    usage: () => { poll(); return alive ? meter.report() : null; },
+  };
 }
+
+// Every model call the hook wrote down, kept here: totals per host and model, and the newest rows.
+const ROWS = 5000;
+const meter = (() => {
+  const rows = [];
+  const deps = [];
+  const count = (v) => (Number.isInteger(v) && v > 0 ? v : 0);
+  return {
+    add(call) {
+      if (!call || typeof call.host !== "string" || !call.host) return;
+      rows.push({
+        at: count(call.at), host: call.host.slice(0, 253), model: String(call.model ?? "").slice(0, 160), status: count(call.status),
+        promptTokens: count(call.promptTokens), cachedTokens: count(call.cachedTokens), completionTokens: count(call.completionTokens),
+        usage: call.usage === true,
+      });
+      if (rows.length > ROWS) rows.splice(0, rows.length - ROWS);
+    },
+    // A service their settings name: only its setting, host and status travel, never a byte of it.
+    dep(d) {
+      if (!d || typeof d.env !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(d.env) || typeof d.host !== "string") return;
+      deps.push({ at: count(d.at), env: d.env, host: d.host.slice(0, 253), status: count(d.status), ...(typeof d.code === "string" ? { code: d.code.slice(0, 40) } : {}) });
+      if (deps.length > ROWS) deps.splice(0, deps.length - ROWS);
+    },
+    report() {
+      const totals = new Map();
+      for (const r of rows) {
+        const key = `${r.host}|${r.model}`;
+        const t = totals.get(key) ?? { host: r.host, model: r.model, calls: 0, promptTokens: 0, cachedTokens: 0, completionTokens: 0, unmetered: 0 };
+        t.calls += 1;
+        t.promptTokens += r.promptTokens;
+        t.cachedTokens += r.cachedTokens;
+        t.completionTokens += r.completionTokens;
+        // An answered call the provider sent no counts for: it was spent, and what it cost is not known.
+        if (!r.usage && r.status > 0 && r.status < 400) t.unmetered += 1;
+        totals.set(key, t);
+      }
+      return {
+        totals: [...totals.values()].sort((a, b) => b.calls - a.calls),
+        rows: rows.slice(-200).reverse().map(({ at, host, model, status }) => ({ at, host, model, status })),
+        deps: deps.slice(-400).reverse(),
+      };
+    },
+  };
+})();