cortad 0.1.6 → 0.1.8

package/lib/sample.mjs

@@ -0,0 +1,218 @@
+// Reading your own material from your own stores, here on this machine.
+//
+// A world's shell cannot do this and must not: it runs inside the OS sandbox, which denies every
+// env file and every host but this one. A reader written into that shell read nothing on a real
+// laptop: no address, no key, no network. The address and the key are in your environment file,
+// which this program already opened to mask what your commands print, so the read happens here and
+// only rows of short fields go back.
+//
+// Nothing runnable arrives from the outside: the plan names store kinds and variable NAMES, and
+// this file decides what is asked and what is kept. Values are never sent; the rows are.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const ROAD = /^[\w.:/-]+$/;
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const KINDS = new Set(["qdrant", "postgres", "files"]);
+const STORES_MAX = 12;
+const PER_STORE = 6;
+const PER_STORE_MAX = 60;
+// A few rows from MANY collections, never many rows from few: a store whose collection names are
+// the product's own grid (jordan_grade-10_sem-2_math) is only read when every cell is read. Forty
+// eight of them, twenty two rows apiece, filled the whole answer with seven of ulaim's cells and
+// left grade 10 semester 2 maths unread, so the depth follows the breadth: how many rows a
+// collection gets is the answer's room divided by how many collections there are.
+const COLLECTIONS = 200;
+// One row of theirs as this store gave it: a page and its short fields, measured on a real store.
+const ROW_BYTES = 800;
+const PER_MIN = 2;
+const ROWS = 200;
+const FIELDS = 12;
+const STRING_MAX = 120;
+// The one long prose field a row carries is the page itself, kept to what the control plane keeps.
+const PAGE_MAX = 700;
+const BUDGET = 540_000;
+const READ_MS = 50_000;
+const ASK_MS = 10_000;
+
+const PII = /(^|_)(e?mail|phone|mobile|tel|fax|password|passwd|pwd|secret|token|otp|ssn|iban|card|address|street|zip|postal|birth|dob|salt|hash|ip)(_|$)|(mail|phone|password|token|secret|hash)$/i;
+const CORPUS = /grade|sem|subject|book|lesson|chunk|doc|page|content|unit|chapter|curricul|textbook|knowledge|embed|vector|material|note|article/i;
+const RECORDS = /histor|attempt|session|log|event|message|user|profile|audit|analytic|trace|queue|cache|token|auth|billing|payment|invoice/i;
+// The narrow security floor: names that are credentials, never a corpus in any product.
+const SENSITIVE = /(?:^|[_\-/.])(?:password|passwd|pwd|credential|secret|apikey|api[_-]?key|access[_-]?token|refresh[_-]?token|jwt|session|oauth)s?(?:$|[_\-/.])|^(?:passwords|credentials|api_keys|secrets)$/i;
+const DOC = /\.(?:md|mdx|txt|rst|html?|pdf|docx?|csv|json)$/i;
+const SKIP_DIR = new Set(["node_modules", ".git", "dist", "build", ".venv", "venv", "__pycache__", ".next"]);
+
+const store = (plan, status, rows, note = "") => ({ road: plan.road, kind: plan.kind, status, rows, ...(note ? { note } : {}) });
+const reason = (err) => String(err?.cause?.code ?? err?.code ?? err?.message ?? err).slice(0, 120);
+const valueFor = (names, env, pattern) => names.map((n) => (pattern.test(n) ? env[n] : "")).find(Boolean) ?? "";
+
+// The short fields of one row: numbers, short strings, and at most one page of prose. The page is
+// looked for in every column, never in the first twelve alone: a row of theirs carries a dozen ids,
+// dates and flags before its text, so a cap that stopped early kept the bookkeeping and dropped the
+// page, and the cell had nothing of theirs to ask about.
+function short(fields) {
+  const out = {};
+  let page = null;
+  for (const [key, value] of Object.entries(fields ?? {})) {
+    if (typeof key !== "string" || PII.test(key) || typeof value === "boolean") continue;
+    if (typeof value === "string" && value.trim().length > STRING_MAX) {
+      const text = value.trim();
+      if (!page || text.length > page[1].length) page = [key, text];
+      continue;
+    }
+    if (Object.keys(out).length >= FIELDS) continue;
+    if (typeof value === "number" && Number.isFinite(value)) out[key] = value;
+    else if (typeof value === "string" && value.trim()) out[key] = value.trim();
+  }
+  if (page) out[page[0]] = page[1].slice(0, PAGE_MAX);
+  return out;
+}
+
+const rank = (name) => `${RECORDS.test(name) ? 1 : 0}${CORPUS.test(name) ? 0 : 1}${name}`;
+
+// Round robin over the cell a name addresses, which is every segment but the last:
+// jordan_grade-10_sem-2 holds math, physics and the rest. Keyed on the first two segments instead,
+// the semester was never part of the key, the names sorted with every sem-1 collection first, and a
+// cap of forty-eight read semester 1 of everything and semester 2 of nothing.
+export function spread(names) {
+  const groups = new Map();
+  for (const name of names) {
+    const parts = name.split(/[_/.]/);
+    const key = parts.length > 1 ? parts.slice(0, -1).join("_") : parts[0];
+    groups.set(key, [...(groups.get(key) ?? []), name]);
+  }
+  const out = [];
+  for (let i = 0; out.length < names.length; i += 1) {
+    for (const key of [...groups.keys()].sort()) {
+      const list = groups.get(key);
+      if (list.length > i) out.push(list[i]);
+    }
+  }
+  return out;
+}
+
+async function ask(url, key, body) {
+  const res = await fetch(url, {
+    method: body ? "POST" : "GET",
+    headers: { "content-type": "application/json", ...(key ? { "api-key": key } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(ASK_MS),
+  });
+  if (!res.ok) throw new Error(`answered ${res.status}`);
+  return res.json();
+}
+
+async function qdrant(plan, names, env, per, until) {
+  let url = valueFor(names, env, /URL|HOST|ENDPOINT/);
+  const key = valueFor(names, env, /KEY|TOKEN/);
+  if (!url) return store(plan, "no-store", []);
+  if (!/^https?:\/\//.test(url)) url = `http://${url}`;
+  const base = url.replace(/\/+$/, "");
+  let every;
+  try {
+    every = ((await ask(`${base}/collections`, key)).result?.collections ?? []).map((c) => String(c?.name ?? "")).filter(Boolean);
+  } catch (err) {
+    return store(plan, "unreachable", [], reason(err));
+  }
+  const corpus = every.filter((n) => CORPUS.test(n) && !SENSITIVE.test(n));
+  const named = (corpus.length ? corpus : every.filter((n) => !SENSITIVE.test(n))).sort((a, b) => rank(a).localeCompare(rank(b)));
+  const asking = spread(named).slice(0, COLLECTIONS);
+  const each = Math.max(PER_MIN, Math.min(per, Math.floor(BUDGET / ROW_BYTES / Math.max(1, asking.length))));
+  const rows = [];
+  let read = 0;
+  // Where each collection that had rows left off. On ulaim a third of the 177 collections are
+  // empty, so the even split left half the answer unspent at three pages a cell.
+  const more = new Map();
+  const scroll = async (name, limit, offset) => {
+    const got = await ask(`${base}/collections/${encodeURIComponent(name)}/points/scroll`, key, { limit, with_payload: true, with_vector: false, ...(offset != null ? { offset } : {}) });
+    let kept = 0;
+    for (const point of got.result?.points ?? []) {
+      const fields = short(point?.payload ?? {});
+      if (Object.keys(fields).length) { rows.push({ where: `${name}#${point?.id}`, fields }); kept += 1; }
+    }
+    if (kept && got.result?.next_page_offset != null) more.set(name, got.result.next_page_offset);
+  };
+  for (const name of asking) {
+    if (Date.now() > until) break;
+    try { await scroll(name, each); } catch { continue; }
+    read += 1;
+  }
+  // The second sweep spends what the first left, evenly over the collections that had more.
+  const rowBytes = rows.length ? JSON.stringify(rows).length / rows.length : ROW_BYTES;
+  const extra = Math.min(PER_STORE_MAX - each, Math.floor((BUDGET - JSON.stringify(rows).length) / rowBytes / Math.max(1, more.size)));
+  if (extra > 0) {
+    for (const [name, offset] of more) {
+      if (Date.now() > until) break;
+      try { await scroll(name, extra, offset); } catch { /* the first sweep's rows stand */ }
+    }
+  }
+  return store(plan, rows.length ? "sampled" : "empty", rows, `${read} of ${named.length} collections`);
+}
+
+// A document folder their own code ingests from, named by its variable and walked from your root.
+function files(plan, names, env, root) {
+  const name = names.find((n) => env[n]);
+  const set = name ? env[name] : "";
+  const dir = set && !set.startsWith("/") ? join(root, set) : set;
+  if (!dir || !existsSync(dir) || !statSync(dir).isDirectory()) return store(plan, "no-store", []);
+  const rows = [];
+  const walk = (at, depth) => {
+    if (rows.length >= ROWS || depth > 8) return;
+    let entries;
+    try { entries = readdirSync(at, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (rows.length >= ROWS) return;
+      if (entry.isDirectory()) { if (!SKIP_DIR.has(entry.name) && !entry.name.startsWith(".")) walk(join(at, entry.name), depth + 1); continue; }
+      if (!DOC.test(entry.name)) continue;
+      rows.push({ where: `${name}#${relative(dir, join(at, entry.name))}`, fields: { file: entry.name, heading: heading(join(at, entry.name)) } });
+    }
+  };
+  walk(dir, 0);
+  return store(plan, rows.length ? "sampled" : "empty", rows);
+}
+
+// What the file calls itself: its first line that says something.
+function heading(path) {
+  try {
+    for (const line of readFileSync(path, "utf8").slice(0, 4000).split("\n").slice(0, 60)) {
+      const said = line.trim().replace(/^#+/, "").trim();
+      if (said) return said.slice(0, STRING_MAX);
+    }
+  } catch { /* unreadable is no heading */ }
+  return "";
+}
+
+// Halved until the report fits what one answer carries, pages first and every store together, so a
+// store read late is not the only one cut.
+function fitted(report) {
+  while (JSON.stringify(report).length > BUDGET && report.stores.some((s) => s.rows.length > 1)) {
+    for (const s of report.stores) s.rows = s.rows.slice(0, Math.max(1, Math.floor(s.rows.length / 2)));
+  }
+  return report;
+}
+
+// ponytail: a database on this machine is not read yet; the table choice needs the read's own list
+// of the tables their AI code names, which the control plane holds and this program does not.
+const NO_DATABASE = "we do not read a database from your own machine yet, so nothing here is written from its rows";
+
+export async function sampleHere(plan, env, root) {
+  const until = Date.now() + READ_MS;
+  const wanted = Number(plan?.perStore);
+  const per = Number.isInteger(wanted) && wanted > 0 ? Math.min(wanted, PER_STORE_MAX) : PER_STORE;
+  const stores = [];
+  for (const asked of (plan?.stores ?? []).slice(0, STORES_MAX)) {
+    if (!ROAD.test(String(asked?.road ?? "")) || !KINDS.has(asked?.kind)) continue;
+    const named = { road: asked.road, kind: asked.kind };
+    const names = (asked.env ?? []).filter((n) => typeof n === "string" && NAME.test(n));
+    try {
+      if (asked.kind === "qdrant") stores.push(await qdrant(named, names, env, per, until));
+      else if (asked.kind === "files") stores.push(files(named, names, env, root));
+      else stores.push(store(named, "no-reader", [], NO_DATABASE));
+    } catch (err) {
+      stores.push(store(named, "unreachable", [], reason(err)));
+    }
+  }
+  return fitted({ stores });
+}

package/lib/start.mjs

@@ -10,36 +10,55 @@ const SERVER = /^(?:express|fastify|hono|koa|@nestjs\/core|@strapi\/strapi|next|
 const PY_MODEL = /^\s*["']?(?:openai|anthropic|langchain|langgraph|litellm|llama[-_]index|google-generativeai|google-genai|groq|cohere|mistralai|ollama|fireworks-ai|together)\b/im;
 const PY_SERVER = /^\s*["']?(?:fastapi|flask|django|starlette|quart|litestar|sanic|aiohttp|uvicorn|gunicorn)\b/im;
 const ENTRIES = ["main.py", "app.py", "server.py", "run.py", "api.py", "wsgi.py", "asgi.py", "src/main.py", "app/main.py", "src/app.py", "backend/main.py", "api/main.py"];
+// A twelve-name list is not how apps name their entry file: agent-service-toolkit's is
+// src/run_service.py, and asking a person how their app starts because of a filename is asking
+// them to do our job. Every plausibly named file beside the manifest is a candidate.
+const ENTRY_NAME = /^(?:main|app|server|serve|api|run|start|service|web|backend|wsgi|asgi)[\w-]*\.py$/i;
+const entriesIn = (dir) => ["", "src", "app", "backend", "api"].flatMap((sub) => {
+  try { return readdirSync(join(dir, sub)).filter((f) => ENTRY_NAME.test(f)).map((f) => (sub ? `${sub}/${f}` : f)); }
+  catch { return []; }
+});
+// What tells an entry file from a script that also runs itself: this one brings a server up.
+const SERVES = /uvicorn\.run|FastAPI\(|Flask\(|Starlette\(|Litestar\(|Quart\(|app\.run\(|run_server|serve\(/;
+// The same question of a package script: does this command put something on a port, or run a task
+// and exit. `crewai run` and `python main.py` are tasks; `next dev` and `nodemon server.js` serve.
+const SERVES_JS = /\b(?:next|nuxt|vite|nest|remix|astro|sveltekit|serve|nodemon|ts-node-dev|uvicorn|gunicorn|rails|strapi)\b/;
+// The manager this repository was installed with, named by its lockfile.
+const manager = (dir) => (existsSync(join(dir, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(dir, "yarn.lock")) ? "yarn" : existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")) ? "bun" : "npm");
 
 function nodeStart(dir, onPath) {
   const pkg = json(join(dir, "package.json"));
   if (!pkg) return null;
   const script = ["dev", "develop", "start:dev", "serve", "start"].find((s) => pkg.scripts?.[s]);
   if (!script) return null;
-  const locked = existsSync(join(dir, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(dir, "yarn.lock")) ? "yarn" : existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")) ? "bun" : "npm";
+  const locked = manager(dir);
+  const deps = Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) });
   // A lockfile names the manager the repository was installed with, not one this machine has.
-  return `${onPath(locked) ? locked : "npm"} run ${script}`;
+  return { cmd: `${onPath(locked) ? locked : "npm"} run ${script}`, serves: deps.some((d) => SERVER.test(d)) || SERVES_JS.test(pkg.scripts[script]) };
 }
 
 function pythonStart(dir, onPath) {
   if (!["requirements.txt", "pyproject.toml", "manage.py", "Pipfile", "uv.lock"].some((f) => existsSync(join(dir, f)))) return null;
   const venv = [".venv/bin/python", "venv/bin/python", "env/bin/python"].map((p) => join(dir, p)).find(existsSync);
   const py = venv ? JSON.stringify(venv) : existsSync(join(dir, "uv.lock")) && onPath("uv") ? "uv run python" : existsSync(join(dir, "poetry.lock")) && onPath("poetry") ? "poetry run python" : "python3";
-  if (existsSync(join(dir, "manage.py"))) return `${py} manage.py runserver`;
-  for (const entry of ENTRIES) {
-    const text = read(join(dir, entry));
-    if (!text) continue;
+  if (existsSync(join(dir, "manage.py"))) return { cmd: `${py} manage.py runserver`, serves: true };
+  const named = [...new Set([...ENTRIES, ...entriesIn(dir)])].map((entry) => [entry, read(join(dir, entry))]).filter(([, text]) => text);
+  // The file that serves before the file that merely runs: src/run_agent.py runs a conversation in
+  // the terminal and src/run_service.py is the app, and they sit in one folder.
+  for (const [entry, text] of [...named.filter(([, text]) => SERVES.test(text)), ...named]) {
     // Their own way of starting it carries their own port and settings.
-    if (/if\s+__name__\s*==\s*["']__main__["']/.test(text)) return `${py} ${entry}`;
+    if (/if\s+__name__\s*==\s*["']__main__["']/.test(text)) return { cmd: `${py} ${entry}`, serves: SERVES.test(text) };
     const module = entry.replace(/\.py$/, "").split("/").join(".");
     const fast = /^(\w+)\s*=\s*(?:FastAPI|Starlette|Litestar|Quart)\(/m.exec(text);
-    if (fast) return `${py} -m uvicorn ${module}:${fast[1]} --host 127.0.0.1 --port 8000`;
+    if (fast) return { cmd: `${py} -m uvicorn ${module}:${fast[1]} --host 127.0.0.1 --port 8000`, serves: true };
     const flask = /^(\w+)\s*=\s*Flask\(/m.exec(text);
-    if (flask) return `${py} -m flask --app ${module} run --port 5000`;
+    if (flask) return { cmd: `${py} -m flask --app ${module} run --port 5000`, serves: true };
   }
   return null;
 }
 
+const KNOWN = ["package.json", "pyproject.toml", "requirements.txt", "manage.py", "Pipfile", "uv.lock"];
+
 const startOf = (dir, onPath) => nodeStart(dir, onPath) ?? pythonStart(dir, onPath);
 
 // How much a folder looks like the thing that serves the AI.
@@ -53,7 +72,7 @@ function weight(dir, name) {
 }
 
 const SKIP = /^(?:node_modules|\.git|dist|build|\.next|coverage|\.venv|venv|__pycache__|\.turbo|\.cache)$/;
-function workspaces(root) {
+export function workspaces(root) {
   const found = [];
   const visit = (dir, depth) => {
     let names = [];
@@ -75,11 +94,47 @@ export function startPlan({ root, typed, onPath }) {
   const pkg = json(join(root, "package.json"));
   const mono = Boolean(pkg?.workspaces) || existsSync(join(root, "pnpm-workspace.yaml")) || existsSync(join(root, "turbo.json")) || existsSync(join(root, "lerna.json"));
   const own = mono ? null : startOf(root, onPath);
-  if (own) return { cmd: own, cwd: root };
-  const ranked = workspaces(root).map((dir) => ({ dir, cmd: startOf(dir, onPath), weight: weight(dir, relative(root, dir)) })).filter((w) => w.cmd).sort((a, b) => b.weight - a.weight);
+  if (own) return { cmd: own.cmd, cwd: root };
+  const ranked = workspaces(root).map((dir) => ({ dir, start: startOf(dir, onPath), weight: weight(dir, relative(root, dir)) })).filter((w) => w.start).sort((a, b) => b.weight - a.weight);
   const best = ranked[0];
-  if (best && best.weight > 0 && (ranked.length === 1 || best.weight > ranked[1].weight)) return { cmd: best.cmd, cwd: best.dir, within: relative(root, best.dir) };
+  const at = (w) => ({ cmd: w.start.cmd, cwd: w.dir, within: relative(root, w.dir) });
+  if (best && best.weight > 0 && (ranked.length === 1 || best.weight > ranked[1].weight)) return at(best);
   // A root that does have a start of its own after all (a monorepo whose root script runs everything).
   const rootStart = startOf(root, onPath);
-  return rootStart ? { cmd: rootStart, cwd: root } : best ? { cmd: best.cmd, cwd: best.dir, within: relative(root, best.dir), unsure: true } : null;
+  if (rootStart) return { cmd: rootStart.cmd, cwd: root };
+  // Nothing at all that we know how to start. A repository written in a language we read, holding
+  // no way to serve, is a package rather than an app: camel is one. Anything else is a start
+  // command we have not learned.
+  if (!best) return KNOWN.some((f) => existsSync(join(root, f))) ? { cmd: null, cwd: root, noServer: true } : null;
+  // Nothing here stands out, so the one that serves wins. A file that only runs in a terminal is
+  // not an app: camel is a package people import, swarm and the crewai examples are scripts that
+  // print to a terminal, and starting one of them puts a chat loop where nothing can knock on it.
+  const serving = ranked.find((w) => w.start.serves);
+  return serving ? { ...at(serving), unsure: true } : { cmd: null, cwd: root, noServer: true };
+}
+
+// What an app says when its dependencies are not installed on this machine, in every runtime we
+// start, and the name of the one it named first.
+const MISSING = /Cannot find module ['"]?([@\w./-]+)|Cannot find package ['"]?([@\w./-]+)|ModuleNotFoundError: No module named ['"]?([\w.]+)|ImportError: No module named ['"]?([\w.]+)|(?:^|[:/ ])([\w.-]+): (?:command )?not found|command not found: ?([\w.-]+)/m;
+export const missingDependency = (said) => MISSING.exec(String(said ?? ""))?.slice(1).find(Boolean) ?? "";
+
+// One install, with the manager the project locked. Never a global one: a Python project without an
+// interpreter of its own gets a virtual environment beside its code, so nothing installed here
+// reaches the rest of the machine.
+export function installPlan(dir, onPath) {
+  if (json(join(dir, "package.json"))) {
+    // The manager the repository locked, fetched for the job when this machine has not got it: npm
+    // refuses vercel's ai-chatbot outright over a peer range pnpm resolves without a word.
+    const locked = manager(dir);
+    if (locked !== "npm") return onPath(locked) ? `${locked} install` : `npx --yes ${locked} install`;
+    return existsSync(join(dir, "package-lock.json")) ? "npm ci || npm install --legacy-peer-deps" : "npm install || npm install --legacy-peer-deps";
+  }
+  if (existsSync(join(dir, "uv.lock")) && onPath("uv")) return "uv sync";
+  if (existsSync(join(dir, "poetry.lock")) && onPath("poetry")) return "poetry install";
+  const venv = [".venv/bin/python", "venv/bin/python", "env/bin/python"].map((p) => join(dir, p)).find(existsSync);
+  const py = venv ? JSON.stringify(venv) : null;
+  const into = (what) => (py ? `${py} -m pip install ${what}` : `python3 -m venv .venv && .venv/bin/python -m pip install --upgrade pip && .venv/bin/python -m pip install ${what}`);
+  if (existsSync(join(dir, "requirements.txt"))) return into("-r requirements.txt");
+  if (existsSync(join(dir, "pyproject.toml"))) return into("-e .");
+  return null;
 }

package/lib/trace.cjs

@@ -1,8 +1,10 @@
 // Loaded into your app by the command that started it (node --require), and only then. It watches
-// for one thing: a request to your app during which your app called a model. That request is your
-// AI's door, with the exact body it takes and the sign-in it carried, learned from a message you sent
-// yourself rather than guessed from code. What it sees is written to a file only you can read, in the
-// command's own folder on this machine. Nothing here talks to a network.
+// for two things. First, a request to your app during which your app called a model: that request is
+// your AI's door, with the exact body it takes and the sign-in it carried, learned from a message you
+// sent yourself rather than guessed from code. Second, every model call your app makes: the host, the
+// model it asked for, the status and the token counts the provider sent back, so a run can say which
+// model answered and what it cost you. Reply text is never written down. Both go to a file only you
+// can read, in the command's own folder on this machine. Nothing here talks to a network.
 "use strict";
 const FILE = process.env.CORTAD_TRACE_FILE;
 if (FILE) {
@@ -13,10 +15,15 @@ if (FILE) {
     const https = require("node:https");
     const als = new AsyncLocalStorage();
     // Said once, so the command knows a message sent to this app can be seen arriving.
-    try { fs.appendFileSync(FILE, JSON.stringify({ hello: "node", pid: process.pid }) + "\n", { mode: 0o600 }); } catch { /* the command is gone */ }
+    const row = (value) => { try { fs.appendFileSync(FILE, JSON.stringify(value) + "\n", { mode: 0o600 }); } catch { /* the command is gone */ } };
+    const isBun = typeof Bun !== "undefined" && typeof Bun.serve === "function";
+    row({ hello: isBun ? "bun" : "node", pid: process.pid });
+    // Which port this process serves. Every process the start command spawns loads this file, turbo's
+    // own launcher included, so "loaded" is not "watching your app": only a listener on the app's port is.
+    const listening = (port) => { if (Number.isInteger(port) && port > 0) row({ listen: port, pid: process.pid }); };
     const MAX = 65536;
     // Where models are served, by host, and the paths every OpenAI-shaped or vendor endpoint ends with.
-    const MODEL_HOST = /(?:^|\.)(?: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|googleapis\.com|openai\.azure\.com|cognitiveservices\.azure\.com|amazonaws\.com|replicate\.com|huggingface\.co|cerebras\.ai|deepinfra\.com|novita\.ai|moonshot\.cn|dashscope\.aliyuncs\.com|bigmodel\.cn)$/i;
+    const MODEL_HOST = /(?:^|\.)(?: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|googleapis\.com|openai\.azure\.com|cognitiveservices\.azure\.com|amazonaws\.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)$/i;
     const MODEL_PATH = /\/(?:chat\/completions|completions|responses|messages|embeddings)$|:(?:generateContent|streamGenerateContent)|\/invoke(?:-with-response-stream)?$|\/api\/(?:chat|generate)$/i;
     const isModelCall = (host, path) => {
       const h = String(host || "").replace(/:\d+$/, "");
@@ -32,14 +39,16 @@ if (FILE) {
       const key = `${ctx.method} ${ctx.path.split("?")[0]}`;
       if (said.has(key)) return;
       said.add(key);
-      const record = { at: Date.now(), method: ctx.method, path: ctx.path, headers: ctx.headers, body: Buffer.concat(ctx.chunks).toString("utf8").slice(0, MAX), sent: String(sent || "").slice(0, MAX) };
-      try { fs.appendFileSync(FILE, JSON.stringify(record) + "\n", { mode: 0o600 }); } catch { /* the command is gone */ }
+      const write = (chunks) => row({ at: Date.now(), method: ctx.method, path: ctx.path, headers: ctx.headers, body: Buffer.concat(chunks).toString("utf8").slice(0, MAX), sent: String(sent || "").slice(0, MAX) });
+      if (ctx.body) ctx.body.then((b) => write([b]));
+      else write(ctx.chunks);
     };
 
     // Inbound: each request is handled inside its own context, and its body is seen as it arrives
     // without reading it, so your own body parser is untouched.
     const emit = http.Server.prototype.emit;
     http.Server.prototype.emit = function (type, req, ...rest) {
+      if (type === "listening") { try { listening(this.address()?.port); } catch { /* not a TCP server */ } }
       if (type !== "request" || !req || !req.method || /^(?:GET|HEAD|OPTIONS)$/.test(req.method)) return emit.call(this, type, req, ...rest);
       const ctx = { method: req.method, path: req.url || "/", headers: { ...req.headers }, chunks: [], size: 0, noted: false };
       const push = req.push;
@@ -67,16 +76,160 @@ if (FILE) {
       return als.run(ctx, () => emit.call(this, type, req, ...rest));
     };
 
+    // Bun serves through Bun.serve, never node:http, so the patch above saw no request at all: databuddy's
+    // Elysia API on Bun took the customer's messages and nothing was written. Bun.serve is wrapped
+    // instead, both the fetch handler and the per-route handlers Bun can dispatch to directly. The body
+    // is read from a clone, so the app's own reader is untouched.
+    if (isBun) {
+      const inside = (handler, self) => function (req, server) {
+        if (!req || /^(?:GET|HEAD|OPTIONS)$/.test(req.method)) return handler.call(self, req, server);
+        let path = "/";
+        try { const u = new URL(req.url); path = u.pathname + u.search; } catch { /* keep "/" */ }
+        const ctx = { method: req.method, path, headers: Object.fromEntries(req.headers), chunks: [], size: 0, noted: false };
+        // ponytail: a body is copied only when it is small or says it is text; an upload is left alone.
+        const size = Number(req.headers.get("content-length") || 0);
+        if (size <= MAX || /json|text|form/i.test(req.headers.get("content-type") || "")) {
+          try { ctx.body = req.clone().arrayBuffer().then((b) => Buffer.from(b).subarray(0, MAX), () => Buffer.alloc(0)); } catch { /* unread */ }
+        }
+        return als.run(ctx, () => handler.call(self, req, server));
+      };
+      const routes = (table) => {
+        if (!table || typeof table !== "object") return table;
+        const out = {};
+        for (const [route, value] of Object.entries(table)) {
+          if (typeof value === "function") out[route] = inside(value, table);
+          else if (value && typeof value === "object" && !(value instanceof Response)) {
+            out[route] = {};
+            for (const [verb, fn] of Object.entries(value)) out[route][verb] = typeof fn === "function" ? inside(fn, value) : fn;
+          } else out[route] = value;
+        }
+        return out;
+      };
+      const serve = Bun.serve;
+      Bun.serve = function (options, ...rest) {
+        let wrapped = options;
+        try {
+          if (options && typeof options === "object") {
+            wrapped = Object.assign(Object.create(Object.getPrototypeOf(options)), options);
+            if (typeof options.fetch === "function") wrapped.fetch = inside(options.fetch, options);
+            if (options.routes) wrapped.routes = routes(options.routes);
+          }
+        } catch { wrapped = options; }
+        const server = serve.call(this, wrapped, ...rest);
+        try { listening(server && server.port); } catch { /* not ours to fail */ }
+        return server;
+      };
+    }
+
+    // The meter. One row per model call: host, model id, status, and the provider's own token counts.
+    const zlib = require("node:zlib");
+    const REPLY_MAX = 8 * 1024 * 1024;
+    const decoded = (buf, encoding) => {
+      try {
+        const e = String(encoding || "").toLowerCase();
+        return (e === "gzip" ? zlib.gunzipSync(buf) : e === "br" ? zlib.brotliDecompressSync(buf) : e === "deflate" ? zlib.inflateSync(buf) : buf).toString("utf8");
+      } catch { return ""; }
+    };
+    const parse = (text) => { try { return JSON.parse(text); } catch { return null; } };
+    const n = (v) => (Number.isInteger(v) && v > 0 ? v : 0);
+    // The shapes the providers answer in. promptTokens is the whole input, cache included, so totals add up.
+    const tokensOf = (u) => {
+      if (!u || typeof u !== "object") return null;
+      if (u.tokens && typeof u.tokens === "object") return tokensOf(u.tokens);
+      if ("prompt_tokens" in u) return { promptTokens: n(u.prompt_tokens), cachedTokens: n(u.prompt_tokens_details && u.prompt_tokens_details.cached_tokens), completionTokens: n(u.completion_tokens) };
+      if ("input_tokens" in u && u.input_tokens_details) return { promptTokens: n(u.input_tokens), cachedTokens: n(u.input_tokens_details.cached_tokens), completionTokens: n(u.output_tokens) };
+      if ("input_tokens" in u) { const read = n(u.cache_read_input_tokens); return { promptTokens: n(u.input_tokens) + read + n(u.cache_creation_input_tokens), cachedTokens: read, completionTokens: n(u.output_tokens) }; }
+      if ("inputTokens" in u) { const read = n(u.cacheReadInputTokens); return { promptTokens: n(u.inputTokens) + read + n(u.cacheWriteInputTokens), cachedTokens: read, completionTokens: n(u.outputTokens) }; }
+      if ("promptTokenCount" in u) return { promptTokens: n(u.promptTokenCount), cachedTokens: n(u.cachedContentTokenCount), completionTokens: n(u.candidatesTokenCount) };
+      return null;
+    };
+    // A stream spreads its counts over events (Anthropic's input in the first, output in the last);
+    // later values win, so the fold ends on the final figures.
+    const readReply = (type, text) => {
+      const events = /event-stream/i.test(type || "")
+        ? text.split("\n").filter((l) => l.startsWith("data:")).map((l) => parse(l.slice(5).trim()))
+        : [].concat(parse(text));
+      const usage = {};
+      let model = null;
+      for (const e of events) {
+        if (!e || typeof e !== "object") continue;
+        const part = e.usage || (e.message && e.message.usage) || (e.response && e.response.usage) || e.usageMetadata;
+        if (part && typeof part === "object") Object.assign(usage, part);
+        model = e.model || (e.message && e.message.model) || (e.response && e.response.model) || e.modelVersion || model;
+      }
+      return { tokens: tokensOf(Object.keys(usage).length ? usage : null), model };
+    };
+    // The model asked for, from what was sent; Gemini and Bedrock put it in the path instead.
+    const askedFor = (path, sent) => {
+      const body = parse(sent);
+      if (body && typeof body.model === "string") return body.model;
+      const m = /\/models\/([^/:]+):|\/model\/([^/]+)\/(?:invoke|converse)/.exec(path || "");
+      return m ? decodeURIComponent(m[1] || m[2]) : "";
+    };
+    const meter = ({ host, path, sent, status, type, body }) => {
+      try {
+        const reply = readReply(type, String(body || "").slice(0, REPLY_MAX));
+        const row = { at: Date.now(), host: String(host).replace(/:443$/, ""), model: String(askedFor(path, sent) || reply.model || "").slice(0, 160), status, ...(reply.tokens || { promptTokens: 0, cachedTokens: 0, completionTokens: 0 }), usage: Boolean(reply.tokens) };
+        fs.appendFileSync(FILE, JSON.stringify({ call: row }) + "\n", { mode: 0o600 });
+      } catch { /* the command is gone */ }
+    };
+
+    // Outbound to a service their own settings name (a vector store, a database API, a search
+    // host): which setting, which host and whether it answered. No body, no headers, no query. A
+    // run that tested ulaim while every curriculum lookup failed inside Node never knew; this is
+    // the witness that lets the run say retrieval was not tested instead of grading without it.
+    let depHosts = null, depSeen = -1;
+    const depOf = (input) => {
+      try {
+        const keys = Object.keys(process.env);
+        if (keys.length !== depSeen) {
+          depSeen = keys.length; depHosts = new Map();
+          for (const k of keys) {
+            const v = process.env[k];
+            if (!v || !/^https?:\/\//i.test(v) || /(^|_)(KEY|TOKEN|SECRET|PASSWORD)$/i.test(k)) continue;
+            try { depHosts.set(new URL(v).host.replace(/:443$/, ""), k); } catch { /* not a URL */ }
+          }
+        }
+        const u = new URL(typeof input === "string" ? input : input && input.url ? input.url : String(input));
+        const name = depHosts.get(u.host.replace(/:443$/, "")) || depHosts.get(u.hostname);
+        return name ? { env: name, host: u.hostname } : null;
+      } catch { return null; }
+    };
+    const depRow = (dep, status, code) => {
+      try { fs.appendFileSync(FILE, JSON.stringify({ dep: { at: Date.now(), env: dep.env, host: dep.host, status, code: code ? String(code).slice(0, 40) : undefined } }) + "\n", { mode: 0o600 }); } catch { /* the command is gone */ }
+    };
+
     // Outbound: the model call your app makes while it handles that request.
     const bodyText = (body) => (typeof body === "string" ? body : Buffer.isBuffer(body) ? body.toString("utf8") : body instanceof Uint8Array ? Buffer.from(body).toString("utf8") : "");
     if (typeof globalThis.fetch === "function") {
       const realFetch = globalThis.fetch;
       globalThis.fetch = function (input, init) {
+        let url = null;
         try {
-          const url = new URL(typeof input === "string" ? input : input && input.url ? input.url : String(input));
-          if (isModelCall(url.host, url.pathname)) note(als.getStore(), bodyText(init && init.body));
+          const u = new URL(typeof input === "string" ? input : input && input.url ? input.url : String(input));
+          if (isModelCall(u.host, u.pathname)) url = u;
         } catch { /* not a URL we can read */ }
-        return realFetch.apply(this, arguments);
+        if (!url) {
+          const dep = depOf(input);
+          if (!dep) return realFetch.apply(this, arguments);
+          return realFetch.apply(this, arguments).then(
+            (res) => { depRow(dep, res.status); return res; },
+            (err) => { depRow(dep, 0, err && err.cause && err.cause.code); throw err; },
+          );
+        }
+        const sent = bodyText(init && init.body);
+        note(als.getStore(), sent);
+        const call = { host: url.host, path: url.pathname, sent };
+        return realFetch.apply(this, arguments).then((res) => {
+          try {
+            // A clone is a tee: your app's branch gets every byte as fast as it reads, this one is read to the end.
+            res.clone().text().then(
+              (text) => meter({ ...call, status: res.status, type: res.headers.get("content-type"), body: text }),
+              () => meter({ ...call, status: res.status, type: "", body: "" }),
+            );
+          } catch { meter({ ...call, status: res.status, type: "", body: "" }); }
+          return res;
+        }, (err) => { meter({ ...call, status: 0, type: "", body: "" }); throw err; });
       };
     }
     for (const mod of [http, https]) {
@@ -90,10 +243,29 @@ if (FILE) {
           if (isModelCall(host, path)) {
             const ctx = als.getStore();
             const parts = [];
+            let sent = "";
             const write = req.write;
             const end = req.end;
             req.write = function (chunk, ...r) { if (chunk && typeof chunk !== "function") parts.push(Buffer.from(chunk)); return write.call(this, chunk, ...r); };
-            req.end = function (chunk, ...r) { if (chunk && typeof chunk !== "function") parts.push(Buffer.from(chunk)); note(ctx, Buffer.concat(parts).toString("utf8")); return end.call(this, chunk, ...r); };
+            req.end = function (chunk, ...r) { if (chunk && typeof chunk !== "function") parts.push(Buffer.from(chunk)); sent = Buffer.concat(parts).toString("utf8"); note(ctx, sent); return end.call(this, chunk, ...r); };
+            const call = { host: String(host || ""), path: String(path || "").split("?")[0] };
+            let done = false;
+            const once = (row) => { if (!done) { done = true; meter({ ...call, sent, ...row }); } };
+            req.once("error", () => once({ status: 0, type: "", body: "" }));
+            req.once("response", (res) => {
+              // The reply's bytes as the parser hands them over, without reading the stream: your
+              // app's own listeners and pipes see exactly what they would have.
+              const got = [];
+              let size = 0;
+              const push = res.push;
+              res.push = function (chunk, encoding) {
+                if (chunk && size < REPLY_MAX) { const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding); got.push(b); size += b.length; }
+                return push.call(this, chunk, encoding);
+              };
+              const finish = () => once({ status: res.statusCode || 0, type: res.headers["content-type"] || "", body: decoded(Buffer.concat(got), res.headers["content-encoding"]) });
+              res.once("end", finish);
+              res.once("close", finish);
+            });
           }
         } catch { /* leave the request alone */ }
         return req;