evrex-mcp 0.6.0 → 0.8.0

package/README.md

@@ -41,8 +41,18 @@ Reload Cursor afterwards so it picks up the new server.
 | Tool | Use it for |
 |---|---|
 | `evrex_why` | Why a specific file is built the way it is, and what was already rejected for it. Call it before a nontrivial edit. |
-| `evrex_search` | Open-ended questions across session and commit history — "have we discussed this", "when did we start doing X". |
+| `evrex_search` | Open-ended questions across session and commit history. Returns an index: a gist and a handle per line, dated, source-labelled, and priced by what the conversation behind it cost. |
+| `evrex_expand` | The full record behind index handles you pick — excerpt plus decisions, constraints, rejected approaches. Batch what matters; never expand everything. |
+| `evrex_bottle` | A session's conversation replayed with tool traffic wrung out — for continuing unfinished work, yours or a teammate's. |
 | `evrex_commit_context` | The session behind a commit: what was being attempted and what it decided. Takes a full or abbreviated sha. |
+| `evrex_timeline` | What happened in the repo in the last N days, newest first — sessions and commits interleaved, each line a handle for `evrex_expand`. Search ranks by relevance and cannot answer "what is recent"; this can. |
+
+The package also ships four hook binaries, registered by `install.sh`:
+`evrex-capture` (session recording on lifecycle events), `evrex-hook`
+(recovered context on every prompt), `evrex-pretool` (the record for a file at
+the moment an agent edits it), `evrex-account` (reads the model's one-line accounting of whether it used the recovered context, and records it), and `evrex-continuity` (the most recent
+recorded session at startup; after a compaction, the conversation itself,
+re-rendered from the transcript and marked authoritative over the summary).
 
 ## Configuration
 

package/dist/account.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+// src/account.ts
+import { statSync, openSync, readSync, closeSync } from "node:fs";
+
+// src/client.ts
+var DEFAULT_API_BASE_URL = "https://api.evrex.ai";
+var API_BASE_URL = (process.env.EVREX_API_BASE_URL ?? process.env.EVREX_API_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+var EVREX_TOKEN = process.env.EVREX_TOKEN ?? process.env.EVREX_API_TOKEN ?? null;
+function headers() {
+  const base = { "Content-Type": "application/json" };
+  if (EVREX_TOKEN) base.Authorization = `Bearer ${EVREX_TOKEN}`;
+  return base;
+}
+function describeFailure(method, path, status, statusText) {
+  if (status === 401 || status === 403) {
+    return EVREX_TOKEN ? `${method} ${path} -> ${status}: the EVREX_TOKEN this server was started with was rejected. It may be revoked or expired.` : `${method} ${path} -> ${status}: this evrex backend requires a credential, but no EVREX_TOKEN is set for this MCP server.`;
+  }
+  return `${method} ${path} -> ${status} ${statusText}`;
+}
+async function request(method, path, { body, absentIsAnswer } = {}) {
+  const res = await fetch(`${API_BASE_URL}${path}`, {
+    method,
+    headers: headers(),
+    ...body === void 0 ? {} : { body: JSON.stringify(body) }
+  });
+  if (res.status === 404 && absentIsAnswer) return null;
+  if (!res.ok) throw new Error(describeFailure(method, path, res.status, res.statusText));
+  return await res.json();
+}
+var get = (path) => request("GET", path);
+var getOrNull = (path) => request("GET", path, { absentIsAnswer: true });
+var post = (path, body) => request("POST", path, { body });
+var evrexApi = {
+  baseUrl: API_BASE_URL,
+  repos: () => get("/repos"),
+  commits: (repoPath) => get(`/commits?repoPath=${encodeURIComponent(repoPath)}`),
+  // Abbreviated shas resolve server-side, so a value pasted from `git log`
+  // works here (apps/backend/src/reads/reads.service.ts#resolveSha).
+  commit: (sha) => getOrNull(`/commits/${encodeURIComponent(sha)}`),
+  sessions: (repoPath) => get(`/sessions?repoPath=${encodeURIComponent(repoPath)}`),
+  session: (id) => getOrNull(`/sessions/${encodeURIComponent(id)}`),
+  // The paginated transcript — see reads.service.ts#getSessionTurns. `ts, id`
+  // ordering server-side makes offsets stable across requests.
+  sessionTurns: (id, offset, limit) => getOrNull(
+    `/sessions/${encodeURIComponent(id)}/turns?offset=${offset}&limit=${limit}`
+  ),
+  ask: (repoPath, text, filePaths) => post("/ask", { repoPath, text, filePaths }),
+  // Evidence-only retrieval (BM25 + embedding), no LLM synthesis call — see
+  // apps/backend/src/query/query.service.ts#search. Used by evrex_search,
+  // which wants ranked hits fast, not a synthesized paragraph.
+  search: (repoPath, text, filePaths) => post("/search", { repoPath, text, filePaths }),
+  // Everything that happened in a repo, newest first, bounded by days — the
+  // same query the desktop Timeline screen makes. Sessions and commits
+  // interleaved, each with the handle evrex_expand takes.
+  feedback: (body) => post("/feedback", body),
+  timeline: (repoPath, days) => get(
+    `/timeline?repoPath=${encodeURIComponent(repoPath)}&days=${encodeURIComponent(String(days))}`
+  )
+};
+
+// src/hook-runtime.ts
+function readStdin() {
+  return new Promise((resolve) => {
+    let raw = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => raw += chunk);
+    process.stdin.on("end", () => resolve(raw));
+    process.stdin.on("error", () => resolve(""));
+  });
+}
+function withDeadline(work, ms) {
+  return Promise.race([
+    work.catch(() => null),
+    new Promise((resolve) => setTimeout(() => resolve(null), ms))
+  ]);
+}
+
+// src/hook-state.ts
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+function statePath(home = homedir()) {
+  return join(home, ".evrex", "hook-state.json");
+}
+function readState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || typeof parsed.sessions !== "object") {
+      return { sessions: {} };
+    }
+    const sessions = {};
+    for (const [id, s] of Object.entries(parsed.sessions ?? {})) {
+      if (!s || typeof s !== "object") continue;
+      sessions[id] = {
+        at: typeof s.at === "string" ? s.at : (/* @__PURE__ */ new Date(0)).toISOString(),
+        files: Array.isArray(s.files) ? s.files.filter((f) => typeof f === "string") : [],
+        shown: Array.isArray(s.shown) ? s.shown.filter((f) => typeof f === "string") : []
+      };
+    }
+    return { sessions };
+  } catch {
+    return { sessions: {} };
+  }
+}
+function shownIn(state, sessionId) {
+  return new Set(state.sessions[sessionId]?.shown ?? []);
+}
+
+// src/account.ts
+var DEADLINE_MS = 3e3;
+var TAIL_BYTES = 256 * 1024;
+var HANDLE = /\b(session:[0-9a-f-]{8,}|commit:[0-9a-f]{7,40})\b/gi;
+function parseAccounting(text) {
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  for (const line of lines) {
+    if (!/evrex|recovered[- ]context/i.test(line)) continue;
+    const lower = line.toLowerCase();
+    const negative = /\b(did not use|didn't use|not used|skipp?ed|ignored|nothing (relevant|useful)|no use)\b/.test(lower);
+    const positive = /\b(used|applied|relied on|drew on|built on)\b/.test(lower);
+    const handles = [...line.matchAll(HANDLE)].map((m) => m[1].toLowerCase());
+    if (negative && !positive) {
+      return { used: [], skipped: line.replace(/^[-*•\s]+/, "").slice(0, 300) };
+    }
+    if (positive) return { used: [...new Set(handles)], skipped: null };
+  }
+  return null;
+}
+function lastAssistantText(transcriptPath) {
+  let size;
+  try {
+    size = statSync(transcriptPath).size;
+  } catch {
+    return null;
+  }
+  const start = Math.max(0, size - TAIL_BYTES);
+  const fd = openSync(transcriptPath, "r");
+  const buf = Buffer.alloc(size - start);
+  try {
+    readSync(fd, buf, 0, buf.length, start);
+  } finally {
+    closeSync(fd);
+  }
+  const lines = buf.toString("utf-8").split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let rec;
+    try {
+      rec = JSON.parse(lines[i]);
+    } catch {
+      continue;
+    }
+    if (rec.type !== "assistant") continue;
+    const content = rec.message?.content;
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      const text = content.filter((b) => !!b && b.type === "text").map((b) => b.text).join("\n");
+      if (text.trim()) return text;
+    }
+  }
+  return null;
+}
+function feedbackFor(accounting, shown) {
+  const full = (handle) => {
+    if (shown.has(handle)) return handle;
+    if (handle.startsWith("commit:")) {
+      for (const s of shown) if (s.startsWith(handle)) return s;
+    }
+    return null;
+  };
+  if (accounting.skipped) {
+    return [...shown].slice(-8).map((target) => ({ target, signal: "not_helpful", note: accounting.skipped }));
+  }
+  const out = [];
+  for (const h of accounting.used) {
+    const target = full(h);
+    if (target) out.push({ target, signal: "helpful" });
+  }
+  return out;
+}
+async function main() {
+  const raw = await withDeadline(readStdin(), DEADLINE_MS);
+  if (!raw) return;
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  const sessionId = input.session_id ?? "";
+  if (!sessionId) return;
+  const shown = shownIn(readState(statePath()), sessionId);
+  if (shown.size === 0) return;
+  const text = input.last_assistant_message ?? (input.transcript_path ? lastAssistantText(input.transcript_path) : null);
+  if (!text) return;
+  const accounting = parseAccounting(text);
+  if (!accounting) return;
+  const started = Date.now();
+  for (const body of feedbackFor(accounting, shown)) {
+    if (Date.now() - started > DEADLINE_MS) break;
+    await withDeadline(evrexApi.feedback(body).catch(() => null), DEADLINE_MS);
+  }
+}
+if (process.argv[1] && /account\.(js|ts)$/.test(process.argv[1])) {
+  main().catch(() => void 0);
+}
+export {
+  feedbackFor,
+  lastAssistantText,
+  parseAccounting
+};