agy-insights 0.3.0 → 0.7.0

package/docs/how-it-works.md

@@ -0,0 +1,102 @@
+# How it works
+
+For whoever maintains or extends agy-insights.
+
+## Principles
+
+Every change must respect them:
+
+1. **Read-only.** Nothing is written to `~/.gemini` or to the developer's projects. The history is copied to a temp folder before opening it, because `agy` keeps those databases open. The only thing written is the report.
+2. **The developer decides.** The tool proposes text to paste; it never applies it.
+3. **Only official Antigravity mechanisms** for exclusions: permissions (`read_file` in `permissions.deny`), `.antigravityignore` and rules in `AGENTS.md`. No hooks, plugins, `.gitignore` or `.ignore`.
+4. **Fail visibly.** If the history format changes, the report must say so instead of showing wrong data.
+5. **Nothing to install.** Only Node 20 or later; SQLite ships in `vendor/`.
+
+## Layout
+
+```
+agy-insights.js       command: options, configuration, writes the report and opens the browser
+lib/history.js        reads the history and aggregates reads, commands, projects and sessions
+lib/findings.js       turns the analysis into findings (the 5 detectors)
+lib/fixes.js          builds the text of each exclusion; writes nothing
+lib/map.js            project map for AGENTS.md (--map); writes nothing
+lib/i18n.js           every user-facing message, in English and Spanish, and language detection
+lib/report.js         HTML report (static, copy buttons only) and text summary
+vendor/sql.js/        SQLite in WebAssembly (version in VERSION, MIT license in LICENSE)
+test/fake-history.js  generates fake histories in the same format as real ones
+test/*.test.js        tests (node --test)
+```
+
+## The Antigravity CLI history
+
+It is undocumented; this is what has been observed in `agy` 1.4.x.
+
+- One SQLite database per conversation: `~/.gemini/antigravity-cli/conversations/<uuid>.db`, in WAL mode.
+- Table `steps`: one row per step. `step_payload` is a protobuf message. Tool calls store the name (`view_file`, `run_command`, `grep_search`…) followed by their JSON arguments, for example `{"AbsolutePath":"C:\\dev\\...\\X.cs","StartLine":301,"EndLine":380}`, preceded by a `call_NNN` id.
+- Each call takes two steps with the same id: the model response that requests it (`step_type` 15) and the result (`step_type` 132), which repeats name and arguments and adds the file content or command output. `lib/history.js` counts the call once per id and adds the size of both steps, which approximates what entered the context.
+- Table `gen_metadata`: one row per model call, in the same order as the transcript's `PLANNER_RESPONSE` lines. Each row holds the model's display name with the effort level in brackets (`Gemini 3.8 Flash (High)`) and its id (`gemini-3.8-flash-high`). `modelOf()` takes the model and effort from whole strings only, so prose in the system prompt that mentions a model is ignored, and the n-th row is matched to the n-th call to get tokens per model and effort.
+- Next to the history, `../brain/<id>/.system_generated/logs/transcript.jsonl`: one JSON line per step. `PLANNER_RESPONSE` lines are model calls and carry `input_tokens`, `cache_read_tokens` and `output_tokens`; failed steps have `status: "ERROR"`. Subagents have their own conversation and transcript. `realUsage()` in `lib/history.js` adds those figures up (it only reads the file). The total printed by `agy -p --output-format json` does not include subagents; this one does.
+
+Each `transcript.jsonl` line also has `created_at` (ISO time). A conversation is dated by the first and last of those; without a transcript, by the `.db` file's last write. `--since` / `--days` keep a conversation when its last activity falls inside the period, and skip the rest before opening them. `../conversation_summaries.db` also has `last_modified_time` per conversation, but it is not used. Each model call's `created_at` also puts its tokens on a local day (`r.daily`), which feeds the usage chart.
+
+The HTML report holds one view per period (whole history, last 90, 30 and 7 days): `agy-insights.js` runs `analyze()` and `findings()` once per period and `report.htmlViews()` renders them all, so switching in the browser needs no analysis code in the page and every number agrees with its period. The chart is inline SVG; its color (`--series`) is checked for contrast, chroma and lightness against both surfaces.
+
+`lib/history.js` does not depend on a protobuf schema. It walks the message, collects every string, and treats as a tool call any JSON preceded (within 3 strings) by a `snake_case` name. That way it survives minor format changes. If there are more than 50 steps and no recognized call, it sets `formatUnrecognized` and the report warns about it.
+
+### SQLite
+
+- With Node 22.13 or later, `node:sqlite` is used, which also reads the `-wal` file.
+- With earlier versions, `sql.js` from `vendor/` is used. It doesn't read the `-wal`, so the last steps of an open conversation may be missing.
+
+To update `sql.js`: copy `dist/sql-wasm.js`, `dist/sql-wasm.wasm` and `LICENSE` from the new version of the npm package and update `VERSION`.
+
+### Projects
+
+The project of each file is detected by walking up its path until a folder with `.git` is found, if the path exists on the machine. With `--project`, that folder is used directly. Windows paths (`C:\...`) are normalized to `/` internally and returned with `\` in exclusions, because `agy` matches permission paths literally.
+
+## Languages
+
+All user-facing text lives in `lib/i18n.js`, in an `en` and an `es` table with the same keys (a test checks it). Modules read it through `t`, which always points at the current language. The language comes from `--lang`, then the `lang` config key, then the system locale (`LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`, or `Intl`): Spanish if it starts with `es`, English otherwise. Numbers follow it too (`en-US` / `es-ES`).
+
+Built-in file kinds are stable ids (`build`, `logs`, `generated`, `code .cs`…) and are only turned into text when shown, with `kindLabel()`. Kinds from `customKinds` are shown as the user wrote them.
+
+To add a message, add it to both tables. To add a language, add a table and teach `detect()` to pick it.
+
+## Adding a file type
+
+In `lib/history.js`, function `kind()`, returning a new id and its label in both tables of `lib/i18n.js`. If it is a type that rarely needs to be read, also add it to `NON_SOURCE`, and its `.antigravityignore` patterns to `KIND_PATTERNS` in `lib/findings.js`. Each developer can add their own types without touching the code with `customKinds` in their configuration.
+
+## Adding a detector
+
+In `lib/findings.js`. A finding is `{ id, level: 'info' | 'warn', title, why, suggestion, tokens, items }`, and each `item` is `{ label, tokens, detail, fixes }`. `fixes` are built with `lib/fixes.js`. Never propose excluding source code: the agent needs it.
+
+Add a case to `test/fake-history.js` and a test.
+
+## Tests
+
+```sh
+npm test
+```
+
+They cover the analysis with a fake history, the five detectors, the rule format, that excluding source code is never proposed, that the history is not changed, project detection through `.git`, the unknown-format warning, HTML escaping, the project map and the full command. CI runs them on Linux, Windows and macOS with Node 20 (sql.js) and Node 22 (node:sqlite).
+
+To generate a sample history and try the report by hand:
+
+```sh
+node test/fake-history.js test/tmp/history
+node agy-insights.js --dir test/tmp/history
+```
+
+## npm package
+
+`package.json` defines the command (`bin`) and which files go into the package (`files`: the command, `lib/`, `vendor/`, `docs/` and the sample configuration; not the tests). It is published on the public npm registry as `agy-insights`. The package only contains the tool; the histories it analyzes stay on each user's machine.
+
+- **Try the package locally**: `npm pack`, then `npx --yes --package=./agy-insights-<version>.tgz agy-insights --help`.
+- **From the repository**, unpublished: `npx --yes github:migohe14/agy-insights`. With no dependencies and no build step, npm installs it straight from git.
+- **Release a version**: `npm version <patch|minor|major>` (updates `package.json` and creates the `v…` tag) and `git push --follow-tags`. The `.github/workflows/publish.yml` workflow runs the tests and `npm publish --provenance`. It needs the `NPM_TOKEN` secret in the GitHub repository (an npm *Automation* or *Granular* token with publish permission).
+
+## To do
+
+- Confirm with `agy` that a `read_file` `deny` rule blocks the read.
+- Test with real histories from several developers (Windows and macOS).
+- Also read the history of the Antigravity app and IDE, if they use the same format.

package/lib/findings.js

@@ -2,122 +2,108 @@
 // matters, and which official Antigravity mechanism could address it. Findings only describe and propose
 // (see fixes.js); applying anything is always the developer's decision.
 const fixes = require('./fixes');
+const { t, num, kindLabel } = require('./i18n');
 
 const DEFAULTS = { crossSessionMin: 3, heavyOutputTokens: 2000, longSessionTokens: 100000 };
 
 // Suggested .antigravityignore patterns for the built-in non-source types.
 const KIND_PATTERNS = {
   'node_modules': ['node_modules/'],
-  'build output (dist, bin, obj…)': ['bin/', 'obj/', 'dist/', 'build/', 'out/', 'target/', 'coverage/'],
+  'build': ['bin/', 'obj/', 'dist/', 'build/', 'out/', 'target/', 'coverage/'],
   'lockfiles': ['*.lock', 'package-lock.json', 'pnpm-lock.yaml', 'packages.lock.json'],
-  'logs, maps, minificados': ['*.log', '*.map', '*.min.js', '*.min.css'],
-  'código generado / migraciones': ['*.designer.cs', '*.g.cs', 'Migrations/'],
+  'logs': ['*.log', '*.map', '*.min.js', '*.min.css'],
+  'generated': ['*.designer.cs', '*.g.cs', 'Migrations/'],
 };
 
 const sum = (xs, f) => xs.reduce((s, x) => s + f(x), 0);
-const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
 const where = (x) => (x.project ? `${x.project} › ${x.rel}` : x.abs);
 
 function findings(r, opts = {}) {
-  const t = { ...DEFAULTS, ...opts };
+  const o = { ...DEFAULTS, ...opts };
+  const f = t.findings;
   const nonSourceKinds = new Set(r.kinds.filter((k) => k.nonSource).map((k) => k.key));
   const out = [];
 
   if (r.formatUnrecognized) {
-    out.push({
-      id: 'format', level: 'warn', title: 'No se reconoce el formato del historial',
-      why: `Hay ${r.steps} pasos pero ninguna llamada a herramienta reconocible. Probablemente agy ha cambiado cómo guarda las conversaciones.`,
-      suggestion: 'Los resultados de abajo no son fiables. Actualiza agy-insights (git pull) o abre una incidencia en el repo.',
-      items: [],
-    });
+    out.push({ id: 'format', level: 'warn', title: f.formatTitle, why: f.formatWhy(r.steps), suggestion: f.formatSuggestion, items: [] });
   }
 
   // 1. Same chunk read again within a session: the content is paid twice. The file itself is usually needed.
-  const reread = r.files.filter((f) => f.rereads > 0).sort((a, b) => b.rereadTokens - a.rereadTokens);
+  const reread = r.files.filter((x) => x.rereads > 0).sort((a, b) => b.rereadTokens - a.rereadTokens);
   if (reread.length) {
     out.push({
-      id: 'rereads', level: 'info', title: 'El agente vuelve a leer lo que ya tenía',
-      tokens: r.rereadTokens,
-      why: `${plural(r.rereads, 'lectura repite', 'lecturas repiten')} un trozo que ya se había leído en la misma sesión. Ese contenido entra dos veces en el contexto.`,
-      suggestion: 'Suele pasar en sesiones largas o después de editar. Sesiones más cortas por tarea, o /compact, lo reducen. No conviene excluir estos ficheros: el agente los necesita.',
-      items: reread.slice(0, 10).map((f) => ({ label: where(f), tokens: f.rereadTokens, detail: plural(f.rereads, 'relectura', 'relecturas'), fixes: [] })),
+      id: 'rereads', level: 'info', title: f.rereadsTitle, tokens: r.rereadTokens,
+      why: f.rereadsWhy(r.rereads), suggestion: f.rereadsSuggestion,
+      items: reread.slice(0, 10).map((x) => ({ label: where(x), tokens: x.rereadTokens, detail: f.rereads(x.rereads), fixes: [] })),
     });
   }
 
   // 2. Generated, build output, vendor, lockfiles and logs: rarely needed, and candidates for exclusion.
-  const nonSource = r.files.filter((f) => nonSourceKinds.has(f.kind));
+  const nonSource = r.files.filter((x) => nonSourceKinds.has(x.kind));
   if (nonSource.length) {
     const byFolder = new Map();
-    for (const f of nonSource) {
-      const abs = f.abs.slice(0, f.abs.lastIndexOf('/'));
-      const e = byFolder.get(abs) || { abs, rel: f.rel.slice(0, f.rel.lastIndexOf('/')), root: f.root, project: f.project, kind: f.kind, tokens: 0, calls: 0 };
-      e.tokens += f.tokens;
-      e.calls += f.calls;
+    for (const x of nonSource) {
+      const abs = x.abs.slice(0, x.abs.lastIndexOf('/'));
+      const e = byFolder.get(abs) || { abs, rel: x.rel.slice(0, x.rel.lastIndexOf('/')), root: x.root, project: x.project, kind: x.kind, tokens: 0, calls: 0 };
+      e.tokens += x.tokens;
+      e.calls += x.calls;
       byFolder.set(abs, e);
     }
     const items = [...byFolder.values()].sort((a, b) => b.tokens - a.tokens).slice(0, 10).map((e) => ({
-      label: `${where(e)}/`, tokens: e.tokens, detail: `${e.kind} · ${plural(e.calls, 'lectura', 'lecturas')}`,
+      label: `${where(e)}/`, tokens: e.tokens, detail: `${kindLabel(e.kind)} · ${f.reads(e.calls)}`,
       fixes: [
         fixes.deny(e.abs),
         e.root && fixes.ignore(e.root, [`${e.rel}/`]),
-        e.root && fixes.rule(e.root, `No leas \`${e.rel}/\`: es ${e.kind}; trabaja con el código fuente.`),
+        e.root && fixes.rule(e.root, f.ruleFolder(e.rel, kindLabel(e.kind))),
       ].filter(Boolean),
     }));
     // One pattern-based item per project and type, for folders that have not been read yet.
     const perProject = new Map();
-    for (const f of nonSource) {
-      if (!f.root || !KIND_PATTERNS[f.kind]) continue;
-      const k = `${f.root}|${f.kind}`;
-      const e = perProject.get(k) || { root: f.root, project: f.project, kind: f.kind, tokens: 0 };
-      e.tokens += f.tokens;
+    for (const x of nonSource) {
+      if (!x.root || !KIND_PATTERNS[x.kind]) continue;
+      const k = `${x.root}|${x.kind}`;
+      const e = perProject.get(k) || { root: x.root, project: x.project, kind: x.kind, tokens: 0 };
+      e.tokens += x.tokens;
       perProject.set(k, e);
     }
     for (const e of perProject.values()) {
       items.push({
-        label: `${e.project} › todo lo de tipo «${e.kind}»`, tokens: e.tokens, detail: 'patrón para cualquier carpeta del proyecto',
+        label: f.kindPattern(e.project, kindLabel(e.kind)), tokens: e.tokens, detail: f.kindPatternDetail,
         fixes: [
           fixes.ignore(e.root, KIND_PATTERNS[e.kind]),
-          fixes.rule(e.root, `No leas ${e.kind} (${KIND_PATTERNS[e.kind].join(', ')}) salvo que la tarea lo pida.`),
+          fixes.rule(e.root, f.ruleKind(kindLabel(e.kind), KIND_PATTERNS[e.kind].join(', '))),
         ],
       });
     }
     out.push({
-      id: 'non-source', level: 'warn', title: 'Se leen ficheros generados, compilados o de dependencias',
-      tokens: sum(nonSource, (f) => f.tokens),
-      why: 'Salidas de build, código generado, dependencias, lockfiles y logs casi nunca hacen falta para entender o cambiar el código, y suelen ser grandes.',
-      suggestion: 'Revisa si alguna de estas lecturas era necesaria. Si no, puedes impedirlas con un permiso de Antigravity.',
-      items,
+      id: 'non-source', level: 'warn', title: f.nonSourceTitle, tokens: sum(nonSource, (x) => x.tokens),
+      why: f.nonSourceWhy, suggestion: f.nonSourceSuggestion, items,
     });
   }
 
   // 3. Same file entering many different sessions: repeated context across conversations.
-  const cross = r.files.filter((f) => f.convs >= t.crossSessionMin).sort((a, b) => b.tokens - a.tokens);
+  const cross = r.files.filter((x) => x.convs >= o.crossSessionMin).sort((a, b) => b.tokens - a.tokens);
   if (cross.length) {
     out.push({
-      id: 'cross-session', level: 'info', title: 'Los mismos ficheros entran en muchas sesiones',
-      tokens: sum(cross, (f) => f.tokens),
-      why: `${plural(cross.length, 'fichero se ha leído', 'ficheros se han leído')} en ${t.crossSessionMin} o más conversaciones distintas.`,
-      suggestion: 'Si son el núcleo del proyecto es normal. Si son grandes y el agente solo necesita una parte, decirle qué trozo mirar ahorra lecturas.',
+      id: 'cross-session', level: 'info', title: f.crossTitle, tokens: sum(cross, (x) => x.tokens),
+      why: f.crossWhy(cross.length, o.crossSessionMin), suggestion: f.crossSuggestion,
       // Exclusion is only offered for non-source files: denying core source code would break the agent's work.
-      items: cross.slice(0, 10).map((f) => ({
-        label: where(f), tokens: f.tokens, detail: `${plural(f.convs, 'sesión', 'sesiones')} · ${plural(f.calls, 'lectura', 'lecturas')}`,
-        fixes: nonSourceKinds.has(f.kind) ? [fixes.deny(f.abs), f.root && fixes.ignore(f.root, [f.rel])].filter(Boolean) : [],
+      items: cross.slice(0, 10).map((x) => ({
+        label: where(x), tokens: x.tokens, detail: `${f.sessions(x.convs)} · ${f.reads(x.calls)}`,
+        fixes: nonSourceKinds.has(x.kind) ? [fixes.deny(x.abs), x.root && fixes.ignore(x.root, [x.rel])].filter(Boolean) : [],
       })),
     });
   }
 
   // 4. Commands whose output is large every time (test suites, builds).
-  const heavy = r.commands.filter((c) => c.tokens / c.calls >= t.heavyOutputTokens).sort((a, b) => b.tokens - a.tokens);
+  const heavy = r.commands.filter((c) => c.tokens / c.calls >= o.heavyOutputTokens).sort((a, b) => b.tokens - a.tokens);
   if (heavy.length) {
     out.push({
-      id: 'heavy-commands', level: 'warn', title: 'Comandos con salidas muy largas',
-      tokens: sum(heavy, (c) => c.tokens),
-      why: 'La salida completa de cada comando entra en el contexto y se reenvía en los turnos siguientes.',
-      suggestion: 'Pide ejecutar solo lo necesario (un test concreto, un proyecto concreto) o filtrar la salida. Si pasa siempre, una regla en el AGENTS.md del proyecto lo recuerda en cada sesión.',
+      id: 'heavy-commands', level: 'warn', title: f.heavyTitle, tokens: sum(heavy, (c) => c.tokens),
+      why: f.heavyWhy, suggestion: f.heavySuggestion,
       items: heavy.slice(0, 8).map((c) => ({
-        label: c.key, tokens: c.tokens, detail: `${plural(c.calls, 'vez', 'veces')} · ~${Math.round(c.tokens / c.calls).toLocaleString('es-ES')} tokens cada una`,
-        example: `- Al ejecutar \`${c.key}\`, limita la salida: solo el test o proyecto afectado, o filtra las líneas relevantes.`,
-        fixes: [],
+        label: c.key, tokens: c.tokens, detail: f.heavyDetail(c.calls, num(c.tokens / c.calls)),
+        example: f.heavyExample(c.key), fixes: [],
       })),
     });
   }
@@ -125,17 +111,15 @@ function findings(r, opts = {}) {
   // 5. Very long sessions: everything accumulated is resent on every turn.
   // Real usage when agy's transcript has it (it includes everything resent on each call), else the estimate.
   const size = (s) => (s.usage ? s.usage.input + s.usage.output : s.tokens);
-  const long = r.sessions.filter((s) => size(s) >= t.longSessionTokens);
+  const long = r.sessions.filter((s) => size(s) >= o.longSessionTokens);
   if (long.length) {
     out.push({
-      id: 'long-sessions', level: 'info', title: 'Sesiones muy largas',
-      tokens: sum(long, (s) => s.tokens),
-      why: `${plural(long.length, 'conversación supera', 'conversaciones superan')} ${t.longSessionTokens.toLocaleString('es-ES')} tokens. En una sesión larga, todo lo acumulado se vuelve a enviar en cada turno.`,
-      suggestion: 'Una conversación nueva por tarea, o /compact cuando cambias de tema.',
+      id: 'long-sessions', level: 'info', title: f.longTitle, tokens: sum(long, (s) => s.tokens),
+      why: f.longWhy(long.length, num(o.longSessionTokens)), suggestion: f.longSuggestion,
       items: long.slice(0, 5).map((s) => ({
-        label: `conversación ${s.id.slice(0, 8)}`, tokens: s.tokens, fixes: [],
-        detail: plural(s.steps, 'paso', 'pasos') + (s.usage
-          ? ` · ${s.usage.calls} llamadas al modelo, ${(s.usage.input + s.usage.output).toLocaleString('es-ES')} tokens reales (${(s.usage.input + s.usage.cache + s.usage.output).toLocaleString('es-ES')} con caché)`
+        label: f.conversation(s.id.slice(0, 8)), tokens: s.tokens, fixes: [],
+        detail: f.steps(s.steps) + (s.usage
+          ? f.longUsage(s.usage.calls, num(s.usage.input + s.usage.output), num(s.usage.input + s.usage.cache + s.usage.output))
           : ''),
       })),
     });

package/lib/fixes.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { t } = require('./i18n');
 
 const AGY_SETTINGS = path.join(os.homedir(), '.gemini', 'antigravity-cli', 'settings.json');
 
@@ -22,10 +23,10 @@ function deniedRules() {
 function deny(absPath) {
   const rule = `read_file(${native(absPath)})`;
   return {
-    how: 'deny', title: 'Denegar la lectura (permiso de Antigravity)',
-    file: AGY_SETTINGS, where: 'dentro de "permissions" → "deny"',
+    how: 'deny', title: t.fixes.denyTitle,
+    file: AGY_SETTINGS, where: t.fixes.denyWhere,
     text: JSON.stringify(rule),
-    note: 'Es lo único que impide la lectura. Afecta a todos tus proyectos, también impide escribir en esa ruta, y hay que reiniciar agy.',
+    note: t.fixes.denyNote,
     applied: deniedRules().includes(rule),
   };
 }
@@ -38,10 +39,10 @@ function ignore(root, patterns) {
   try { current = fs.readFileSync(file, 'utf8').split(/\r?\n/).map((l) => l.trim()); } catch { /* not there yet */ }
   const missing = patterns.filter((p) => !current.includes(p));
   return {
-    how: 'ignore', title: 'Añadir a .antigravityignore',
-    file, where: 'al final del fichero (créalo si no existe)',
+    how: 'ignore', title: t.fixes.ignoreTitle,
+    file, where: t.fixes.ignoreWhere,
     text: missing.join('\n'),
-    note: 'Lo oculta del autocompletado con @; no está documentado que impida leerlo.',
+    note: t.fixes.ignoreNote,
     applied: missing.length === 0,
   };
 }
@@ -53,10 +54,10 @@ function rule(root, text) {
   let present = false;
   try { present = fs.readFileSync(file, 'utf8').split(/\r?\n/).some((l) => l.trim() === line); } catch { /* none */ }
   return {
-    how: 'rule', title: 'Añadir una regla a AGENTS.md',
-    file, where: 'al final del fichero',
+    how: 'rule', title: t.fixes.ruleTitle,
+    file, where: t.fixes.ruleWhere,
     text: line,
-    note: 'Es una indicación al modelo, no un bloqueo. Se envía en cada petición: mantenla corta. AGENTS.md suele estar en el repo del equipo.',
+    note: t.fixes.ruleNote,
     applied: present,
   };
 }

package/lib/history.js

@@ -10,7 +10,23 @@ const DEFAULT_DIR = path.join(os.homedir(), '.gemini', 'antigravity-cli', 'conve
 const BYTES_PER_TOKEN = 4;
 const TOOL_RE = /^[a-z][a-z0-9_]{2,40}$/;
 const FILE_KEYS = ['AbsolutePath', 'TargetFile', 'FilePath', 'File', 'Path'];
-const MODEL_RE = /\b(gemini-[\w.-]+|Gemini \d[\w. ]*\((?:Low|Medium|High)\)|Claude \w+ [\d.]+ \(\w+\))/g;
+// Model of a call, as agy names it in gen_metadata: "Gemini 3.8 Flash (High)" (name and effort level), or
+// the id "gemini-3.8-flash-high" when the display name is missing.
+// Whole strings only, so that prose in the system prompt that mentions a model is not taken for one.
+const MODEL_NAME_RE = /^((?:Gemini|Claude|GPT)[\w .-]*?) \(([A-Za-z][A-Za-z ]{1,15})\)$/;
+const MODEL_ID_RE = /^((?:gemini|claude|gpt)-[\w.-]*?)-(minimal|low|medium|high|xhigh|max)$/;
+
+function modelOf(strs) {
+  for (const s of strs) {
+    const m = s.length < 200 && MODEL_NAME_RE.exec(s);
+    if (m) return { model: m[1].trim(), effort: m[2].trim() };
+  }
+  for (const s of strs) {
+    const m = s.length < 200 && MODEL_ID_RE.exec(s);
+    if (m) return { model: m[1], effort: m[2] };
+  }
+  return { model: null, effort: null };
+}
 
 // --- SQLite access: node:sqlite when the runtime has it (Node >= 22.13), sql.js (WASM) otherwise. ---
 
@@ -106,18 +122,18 @@ const norm = (p) => p.replace(/[\\/]+/g, '/');
 const key = (p) => norm(p).toLowerCase().replace(/\/+$/, '');
 
 // Types that are rarely needed in the context: their reads are reported as findings.
-const NON_SOURCE = new Set(['node_modules', 'build output (dist, bin, obj…)', 'lockfiles',
-  'logs, maps, minificados', 'código generado / migraciones']);
+// Kinds are stable ids; i18n.kindLabel() turns them into text.
+const NON_SOURCE = new Set(['node_modules', 'build', 'lockfiles', 'logs', 'generated']);
 
 function kind(p) {
   if (/(^|\/)node_modules\//.test(p)) return 'node_modules';
-  if (/(^|\/)(dist|build|out|target|coverage|\.next|bin|obj)\//i.test(p)) return 'build output (dist, bin, obj…)';
+  if (/(^|\/)(dist|build|out|target|coverage|\.next|bin|obj)\//i.test(p)) return 'build';
   if (/(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|packages\.lock\.json|\.lock)$/.test(p)) return 'lockfiles';
-  if (/\.(log|map)$|\.min\.(js|css)$/.test(p)) return 'logs, maps, minificados';
+  if (/\.(log|map)$|\.min\.(js|css)$/.test(p)) return 'logs';
   if (/(^|\/)(tests?|__tests__|specs?)\//i.test(p) || /\.(test|spec|tests?)\.\w+$/i.test(p) || /Tests?\//.test(p)) return 'tests';
-  if (/\.designer\.cs$|\.g\.cs$|\.generated\.\w+$|(^|\/)(generated|Migrations)\//i.test(p)) return 'código generado / migraciones';
+  if (/\.designer\.cs$|\.g\.cs$|\.generated\.\w+$|(^|\/)(generated|Migrations)\//i.test(p)) return 'generated';
   const ext = path.extname(p).toLowerCase();
-  return ext ? `código ${ext}` : 'otros';
+  return ext ? `code ${ext}` : 'other';
 }
 
 // Project root of a file: an explicit workspace containing it, or else the nearest folder with a .git
@@ -154,6 +170,9 @@ function locate(file, workspaces, depth = 3) {
 
 // --- Real usage ---
 
+// Local calendar day of a time, as YYYY-MM-DD.
+const dayKey = (ms) => { const d = new Date(ms); return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`; };
+
 // What the model was actually billed for in a conversation, from the transcript agy keeps next to the
 // history (<conversations>/../brain/<id>/.system_generated/logs/transcript.jsonl): one line per step,
 // and model calls carry input, cache-read and output tokens. Subagents have their own conversation and
@@ -162,16 +181,28 @@ function realUsage(dir, id) {
   const file = path.join(dir, '..', 'brain', id, '.system_generated', 'logs', 'transcript.jsonl');
   let text;
   try { text = fs.readFileSync(file, 'utf8'); } catch { return null; }
-  const u = { calls: 0, input: 0, cache: 0, output: 0, errors: 0 };
+  // `days`: the same figures per local day of each model call (calls without a time go under null).
+  // `perCall`: each call's figures, in order (they match gen_metadata's rows one to one).
+  const u = { calls: 0, input: 0, cache: 0, output: 0, errors: 0, start: null, end: null, days: new Map(), perCall: [] };
   for (const line of text.split('\n')) {
     let e;
     try { e = JSON.parse(line); } catch { continue; }
+    const at = Date.parse(e.created_at);
+    if (at) { u.start = Math.min(u.start ?? at, at); u.end = Math.max(u.end ?? at, at); }
     if (e.status === 'ERROR') u.errors++;
     if (e.type !== 'PLANNER_RESPONSE') continue;
     u.calls++;
     u.input += Number(e.input_tokens) || 0;
     u.cache += Number(e.cache_read_tokens) || 0;
     u.output += Number(e.output_tokens) || 0;
+    u.perCall.push({ input: Number(e.input_tokens) || 0, cache: Number(e.cache_read_tokens) || 0, output: Number(e.output_tokens) || 0 });
+    const k = at ? dayKey(at) : null;
+    const d = u.days.get(k) || { calls: 0, input: 0, cache: 0, output: 0 };
+    d.calls++;
+    d.input += Number(e.input_tokens) || 0;
+    d.cache += Number(e.cache_read_tokens) || 0;
+    d.output += Number(e.output_tokens) || 0;
+    u.days.set(k, d);
   }
   return u;
 }
@@ -194,23 +225,34 @@ class Counter {
  * @param {string} [opts.dir] conversations directory
  * @param {string[]} [opts.workspaces] only count conversations that touched these folders (all if empty)
  * @param {Object<string,string>} [opts.customKinds] regex -> label, checked before the built-in types
+ * @param {number} [opts.since] only conversations whose last activity is at or after this time (ms)
  */
-async function analyze({ dir = DEFAULT_DIR, workspaces = [], customKinds = {} } = {}) {
+async function analyze({ dir = DEFAULT_DIR, workspaces = [], customKinds = {}, since = null } = {}) {
   const custom = Object.entries(customKinds).map(([re, label]) => [new RegExp(re, 'i'), label]);
   const classify = (p) => custom.find(([re]) => re.test(p))?.[1] || kind(p);
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agy-insights-'));
   const r = {
     dir, backend: nodeSqlite ? 'node:sqlite' : 'sql.js', conversations: 0, unreadable: 0, steps: 0, tokens: 0,
+    since, period: null, olderSkipped: 0,
     toolCallsFound: 0, reads: 0, rangedReads: 0, linesRead: 0, rereads: 0, rereadTokens: 0, sessions: [],
     usage: { conversations: 0, calls: 0, input: 0, cache: 0, output: 0, errors: 0 },
   };
   const tools = new Counter(), kinds = new Counter(), folders = new Counter(), files = new Counter();
-  const commands = new Counter(), models = new Counter(), projects = new Counter();
+  const commands = new Counter(), projects = new Counter();
+  const models = new Map(); // "model|effort" -> calls and real tokens
+  const daily = new Map(); // YYYY-MM-DD -> real usage that day
+  const firstDay = since ? dayKey(since) : '';
   const wsKeys = workspaces.map(key);
 
   try {
     const dbs = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => /^[0-9a-f-]{36}\.db$/i.test(f)) : [];
     for (const f of dbs) {
+      // When it happened: the transcript's step times, else the database's last write.
+      const id = f.replace(/\.db$/, '');
+      const usage = realUsage(dir, id);
+      const end = usage?.end ?? fs.statSync(path.join(dir, f)).mtimeMs;
+      const start = usage?.start ?? end;
+      if (since && end < since) { r.olderSkipped++; continue; }
       let db;
       try { db = await openDb(path.join(dir, f), tmp); } catch { r.unreadable++; continue; }
       try {
@@ -223,6 +265,7 @@ async function analyze({ dir = DEFAULT_DIR, workspaces = [], customKinds = {} }
         }
 
         r.conversations++;
+        r.period = { from: Math.min(r.period?.from ?? start, start), to: Math.max(r.period?.to ?? end, end) };
         let convBytes = 0;
         const seenRanges = new Set(), seenFiles = new Set(), seenFolders = new Set(), seenKinds = new Set(), seenProjects = new Set();
         const seenCalls = new Map(); // call id -> 1 if that call re-read a range already read, else 0
@@ -268,17 +311,38 @@ async function analyze({ dir = DEFAULT_DIR, workspaces = [], customKinds = {} }
             files.add(key(file), { ...fields, convs: once(seenFiles, key(file)) }, { abs: file, rel, root, project, kind: k });
           });
         }
-        const id = f.replace(/\.db$/, '');
-        const usage = realUsage(dir, id);
         if (usage) {
           r.usage.conversations++;
           for (const k of ['calls', 'input', 'cache', 'output', 'errors']) r.usage[k] += usage[k];
+          for (const [k, v] of usage.days) {
+            const day = k || dayKey(end);
+            if (day < firstDay) continue;
+            const d = daily.get(day) || { day, calls: 0, input: 0, cache: 0, output: 0 };
+            for (const f of ['calls', 'input', 'cache', 'output']) d[f] += v[f];
+            daily.set(day, d);
+          }
         }
-        r.sessions.push({ id, steps: steps.length, tokens: convBytes / BYTES_PER_TOKEN, usage });
-        r.tokens += convBytes / BYTES_PER_TOKEN;
-        for (const [blob] of db.all('select data from gen_metadata')) {
-          for (const s of collect(blob)) for (const m of s.matchAll(MODEL_RE)) models.add(m[1], { calls: 1 });
+        // One gen_metadata row per model call, in the transcript's order: the n-th row's model made the n-th call.
+        const callModels = db.all('select data from gen_metadata order by idx').map(([blob]) => modelOf(collect(blob)));
+        const n = Math.max(callModels.length, usage ? usage.perCall.length : 0);
+        const seenModels = new Set();
+        for (let i = 0; i < n; i++) {
+          const { model, effort } = callModels[i] || { model: null, effort: null };
+          const k = `${model}|${effort}`;
+          const e = models.get(k) || { model, effort, calls: 0, convs: 0, input: 0, cache: 0, output: 0, known: 0 };
+          e.calls++;
+          if (!seenModels.has(k)) { seenModels.add(k); e.convs++; }
+          const c = usage?.perCall[i];
+          if (c) { e.known++; e.input += c.input; e.cache += c.cache; e.output += c.output; }
+          models.set(k, e);
         }
+        // The session's model: the one that made most of its calls.
+        const counts = new Map();
+        for (const m of callModels) counts.set(`${m.model}|${m.effort}`, (counts.get(`${m.model}|${m.effort}`) || 0) + 1);
+        const main = [...counts].sort((a, b) => b[1] - a[1])[0];
+        const model = main ? callModels.find((m) => `${m.model}|${m.effort}` === main[0]) : null;
+        r.sessions.push({ id, start, end, steps: steps.length, tokens: convBytes / BYTES_PER_TOKEN, usage, model: model?.model ? model : null, models: counts.size });
+        r.tokens += convBytes / BYTES_PER_TOKEN;
       } catch { r.unreadable++; } finally { db.close(); }
     }
   } finally {
@@ -293,8 +357,10 @@ async function analyze({ dir = DEFAULT_DIR, workspaces = [], customKinds = {} }
   return {
     ...r,
     tools: tools.all(), kinds: kinds.all(), folders: folders.all(), files: files.all(), projects: projects.all(),
-    commands: commands.all(), models: models.all(),
+    commands: commands.all(),
+    models: [...models.values()].sort((a, b) => b.input + b.output - (a.input + a.output) || b.calls - a.calls),
+    daily: [...daily.values()].sort((a, b) => (a.day < b.day ? -1 : 1)),
   };
 }
 
-module.exports = { analyze, DEFAULT_DIR, kind, NON_SOURCE, realUsage };
+module.exports = { analyze, DEFAULT_DIR, kind, NON_SOURCE, realUsage, dayKey, modelOf };