@echomem/mcp 1.4.3 → 1.4.4

package/README.md

@@ -49,18 +49,22 @@ your editor and you're done.
 |---|---|
 | `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and run setup in one explicit step |
 | `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
-| `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop]` | Write client config + log in |
-| `echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|codex]` | Write client config without opening the browser or changing credentials |
-| `npx -y @echomem/mcp@latest update [--client cursor\|windsurf\|claude-desktop\|codex]` | One-shot update: repoint the client config to the latest bridge, with no browser login |
+| `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config + log in |
+| `echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config without opening the browser or changing credentials |
+| `npx -y @echomem/mcp@latest update --all` | One-shot update: repoint detected client configs to the latest bridge, with no browser login |
+| `npx -y @echomem/mcp@latest update --client codex` | Update one client only |
 | `echomem-mcp setup --with-hud [--client codex]` | Write client config + log in + launch the EchoMem context HUD |
 | `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
 | `echomem-mcp unlock` | Re-derive the encryption key after its TTL (or `--passphrase`) |
-| `echomem-mcp status` | Show token / key / detected clients |
+| `echomem-mcp status` | Show token / key / detected clients, configured bridge versions, and update guidance |
+| `echomem-mcp doctor [--no-network]` | Diagnose configured client bridge versions |
 | `echomem-mcp logout` | Remove stored credentials |
 
-The bridge reports its package version in MCP server instructions and in the `search_memories`
-tool description. Agents should use that version signal to update once when stale, not auto-update
-on every MCP startup.
+The bridge reports its package version in MCP server instructions and in tool descriptions. It also
+checks npm for a newer published bridge using a cached, non-blocking check. Agents can call
+`echomem_update_status` to show the user whether an update exists and then run
+`npx -y @echomem/mcp@latest update --all` if the user agrees. The bridge does not auto-update on
+every MCP startup.
 
 ## EchoMem Context HUD
 
@@ -185,6 +189,7 @@ ECHO_API_TOKEN="your_token" ECHO_API_BASE_URL="http://localhost:3000" npm run st
 * **`search_memories_by_keywords`**: Retrieve memories by matching the `keys` field.
 * **`search_others_memories`**: Search other users' public memories through MemoryFeed public search.
 * **`delete_memory`**: Delete a single personal memory through a two-step confirmation flow. First call with `memoryId` only to preview the target and receive `confirmationToken`; after the user explicitly confirms, call again with `confirmed: true` and that exact token. This deletes the memory row only and preserves raw `source_of_truth` conversation records.
+* **`echomem_update_status`**: Check the installed bridge against the latest published npm version. Works without login, uses cached background checks in normal operation, and returns the update command to show the user when a newer bridge exists.
 * **`echo_context_health`**: Return the local Codex/Claude context-health score as markdown. Works without login and uploads no transcript content.
 
 Legacy aliases are preserved for compatibility:

package/dist/hud/capsule.js

@@ -9,10 +9,13 @@ import { formatTokens } from "./metric.js";
 const MAX_TURN_CHARS = 280;
 const MAX_FILES = 10;
 export function buildCapsuleText(score) {
-    const { turns, edited } = scanSession(score.sourcePath);
+    const { turns, edited, cwd } = scanSession(score.sourcePath);
     const goal = turns[0];
     const lastAsk = turns.length > 1 ? turns[turns.length - 1] : undefined;
-    const reads = readFiles(score, edited);
+    // Normalize every path to repo-relative so "editing" (recorded absolute) and "read"
+    // (recorded relative) dedupe correctly and the capsule isn't bloated by the cwd prefix.
+    const editedRel = edited.map((f) => relToCwd(f, cwd));
+    const reads = readFiles(score, editedRel, cwd);
     const sat = score.saturationPct !== null
         ? ` · ${score.saturationPct}% of ${formatTokens(score.modelContextWindow || 0)} window`
         : "";
@@ -25,21 +28,23 @@ export function buildCapsuleText(score) {
     ];
     if (lastAsk)
         lines.push("", "## Most recent instruction", lastAsk);
-    if (edited.length)
-        lines.push("", "## Files being edited", ...edited.slice(0, MAX_FILES).map((f) => `- ${f}`));
+    if (editedRel.length)
+        lines.push("", "## Files being edited", ...editedRel.slice(0, MAX_FILES).map((f) => `- ${f}`));
     if (reads.length)
         lines.push("", "## Other files read", ...reads.slice(0, MAX_FILES).map((f) => `- ${f}`));
     lines.push("", "## Where things stand", `- Turns ${score.turn} · reads ${score.reads} · edits ${score.stats?.patchEdits ?? 0} · compactions ${score.stats?.compactMarkers ?? 0}`, `- Tracked dead-weight ≥ ${formatTokens(score.pollutionTok)} (${score.pollutionPct}% pollution, lower bound)`, "", "---", "Start a fresh session and paste this capsule (or call search_memories) so the new window begins clean — you keep the goal, the working set, and your last instruction without re-reading everything. This is a clean recompose, not a provider compaction.");
     return lines.join("\n");
 }
 // Read files the scorer already tracked, minus anything we know was edited (shown separately).
-function readFiles(score, edited) {
-    const editedSet = new Set(edited);
+// Both sides are relativized to cwd first so the edited/read dedupe actually matches.
+function readFiles(score, editedRel, cwd) {
+    const editedSet = new Set(editedRel);
     const seen = new Set();
     for (const files of Object.values(score.filesByTool || {})) {
         for (const file of files) {
-            if (file && !editedSet.has(file))
-                seen.add(file);
+            const rel = relToCwd(file, cwd);
+            if (rel && !editedSet.has(rel))
+                seen.add(rel);
         }
     }
     return [...seen];
@@ -47,45 +52,83 @@ function readFiles(score, edited) {
 function scanSession(file) {
     const turns = [];
     const edited = new Set();
+    let cwd = "";
     let records = [];
     try {
         records = readJsonl(file);
     }
     catch {
-        return { turns, edited: [] };
+        return { turns, edited: [], cwd };
     }
     for (const record of records) {
         if (!isRecord(record))
             continue;
+        if (!cwd)
+            cwd = recordCwd(record);
         const text = userTextFromRecord(record);
         if (text)
             turns.push(text);
         collectEdited(record, edited);
     }
-    return { turns, edited: [...edited] };
+    return { turns, edited: [...edited], cwd };
 }
-// Tolerant across Codex (payload.role/payload.content) and Claude (message.role/message.content)
-// shapes. Skips tool results, assistant turns, and injected <context> wrappers; degrades to nothing
-// rather than throwing, so the capsule still renders from the working set + health.
+function recordCwd(record) {
+    if (typeof record.cwd === "string")
+        return record.cwd;
+    const payload = isRecord(record.payload) ? record.payload : null;
+    if (payload && typeof payload.cwd === "string")
+        return payload.cwd;
+    return "";
+}
+function relToCwd(file, cwd) {
+    if (!file)
+        return file;
+    if (cwd && (file === cwd || file.startsWith(`${cwd}/`)))
+        return file.slice(cwd.length + 1) || file;
+    return file;
+}
+// Reads the user's real turns, matching the same sources assembleCodex/assembleClaude use so the
+// goal/last-instruction can't be the injected preamble:
+//   - Codex: the `user_message` EVENT (payload.message is a plain string). The AGENTS.md preamble is a
+//     separate `message`/role:user ITEM, so reading events excludes it by construction — no blocklist.
+//   - Claude: the top-level `type:"user"` turn with message.content text blocks.
+// Degrades to nothing rather than throwing, so the capsule still renders from the working set + health.
 function userTextFromRecord(record) {
     const payload = isRecord(record.payload) ? record.payload : record;
-    const message = isRecord(payload.message) ? payload.message : isRecord(record.message) ? record.message : null;
-    let role = "";
-    if (typeof payload.role === "string")
-        role = payload.role;
-    else if (message && typeof message.role === "string")
-        role = message.role;
-    else if (typeof record.type === "string")
-        role = record.type;
-    const ptype = typeof payload.type === "string" ? payload.type : "";
-    if (role !== "user" && ptype !== "user_message")
+    // Codex user input.
+    if (payload.type === "user_message" && typeof payload.message === "string") {
+        return finishTurn(clean(stripCodexScaffolding(payload.message)));
+    }
+    // Claude user turn (top-level type:"user"). Codex `message`/role:user items are NOT type:"user",
+    // so they never reach here — that's what keeps the AGENTS.md item and duplicate turns out.
+    if (record.type !== "user")
         return null;
-    const raw = (message ? message.content : undefined) ?? payload.content ?? payload.text;
+    const message = isRecord(record.message) ? record.message : null;
+    const raw = message ? message.content : undefined;
     const text = clean(flatten(raw));
-    if (!text || text.startsWith("<") || text.length < 3)
+    if (!text || text.startsWith("<"))
+        return null;
+    if (isInstructionsPreamble(text))
+        return null; // Claude project-rules / caveat injections
+    return finishTurn(text);
+}
+function finishTurn(text) {
+    if (!text || text.length < 3)
         return null;
     return text.length > MAX_TURN_CHARS ? `${text.slice(0, MAX_TURN_CHARS)}…` : text;
 }
+// Strip Codex's synthetic wrapper blocks from a user message (mirrors migrate.ts cleanCodexUser).
+function stripCodexScaffolding(msg) {
+    return String(msg || "")
+        .replace(/<(environment_context|user_instructions|permissions|app-context)>[\s\S]*?<\/\1>/g, "")
+        .trim();
+}
+// Claude-side injected preambles (project rules / harness caveats). Anchored to the START so a real
+// instruction that merely mentions these words isn't dropped. Codex's AGENTS.md is handled
+// structurally above, so it isn't listed here.
+function isInstructionsPreamble(text) {
+    return /^#\s*claudeMd\b/i.test(text) || text.startsWith("Caveat:");
+}
 function collectEdited(record, set) {
     const payload = isRecord(record.payload) ? record.payload : record;
     if (payload.type === "patch_apply_end" && isRecord(payload.changes)) {

package/dist/hud/metric.js

@@ -7,6 +7,10 @@ export const BUCKETS = {
 };
 const SHELL_READ_BINS = new Set(["cat", "head", "tail", "sed", "nl", "less", "more", "bat"]);
 const EXT = /\.[A-Za-z0-9]{1,8}$/;
+// A re-read counts as redundant only if a prior read substantially re-covers THIS read. A shared
+// boundary line (sequential paging, e.g. sed 1,260p then 260,620p) is not a re-read; requiring ≥50%
+// of the new range to be already-seen keeps paging out while still catching genuine sub-range re-reads.
+const REDUNDANT_OVERLAP_FRACTION = 0.5;
 export function newMetricState() {
     return {
         turn: 0,
@@ -45,7 +49,13 @@ export function recordRead(state, file, start = 1, end = 1e9) {
     const tokens = estimateReadTokens(safeStart, safeEnd);
     const previous = state.readHist.get(file) || [];
     const lastEdit = state.editTurn.get(file) ?? -1;
-    const redundant = previous.some((read) => read.turn >= lastEdit && safeStart <= read.end && safeEnd >= read.start);
+    const newLines = Math.max(1, safeEnd - safeStart + 1);
+    const redundant = previous.some((read) => {
+        if (read.turn < lastEdit)
+            return false; // an edit since this read invalidated it — re-read is fresh
+        const overlap = Math.min(safeEnd, read.end) - Math.max(safeStart, read.start) + 1;
+        return overlap > 0 && overlap / newLines >= REDUNDANT_OVERLAP_FRACTION;
+    });
     state.reads += 1;
     if (redundant) {
         addBucket(state, BUCKETS.rangeRedundant, tokens, 1);
@@ -132,9 +142,12 @@ function estimateReadTokens(start, end) {
     return Math.min(8000, Math.max(40, lines * 12));
 }
 function qualityColor(pollutionPct, saturationPct) {
-    if (pollutionPct > 40 || (saturationPct !== null && saturationPct >= 95))
+    if (pollutionPct >= 35 ||
+        (saturationPct !== null && saturationPct >= 95) ||
+        (saturationPct !== null && saturationPct >= 85 && pollutionPct >= 20)) {
         return "red";
-    if (pollutionPct >= 25 || (saturationPct !== null && saturationPct >= 90))
+    }
+    if (pollutionPct >= 18 || (saturationPct !== null && saturationPct >= 75))
         return "amber";
     return "green";
 }

package/dist/hud/monitor.js

@@ -1,17 +1,27 @@
 import { execFileSync } from "node:child_process";
 import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
 import { adapterList } from "./adapters.js";
-import { statSignature } from "./fs.js";
+import { homePath, newestFile, walkFiles } from "./fs.js";
+const LIVE_WINDOW_MS = 45_000;
+const ONGOING_WINDOW_MS = 300_000; // a thread counts as "ongoing" if its log was written in the last 5 min
+const FOCUS_GRACE_MS = 8_000; // keep the last-known frontmost client this long when detection momentarily misses
 export class HudMonitor extends EventEmitter {
     mode;
     pollMs;
     timer = null;
     signatures = new Map();
     scores = new Map();
+    mtimes = new Map();
+    labelCache = new Map();
     missing = [];
     frontmostCheckedAt = 0;
+    frontmostSeenAt = 0;
     frontmostClient = null;
     lastActiveClient = null;
+    threadCounts = {};
+    threadCountsAt = 0;
     constructor(mode = "auto", pollMs = 750) {
         super();
         this.mode = mode;
@@ -30,45 +40,116 @@ export class HudMonitor extends EventEmitter {
         this.timer = null;
     }
     snapshot() {
-        const preferred = this.frontmostPreferredClient();
-        const scores = [...this.scores.values()].sort((a, b) => {
-            if (preferred && a.client === preferred && b.client !== preferred)
-                return -1;
-            if (preferred && b.client === preferred && a.client !== preferred)
-                return 1;
-            return Date.parse(b.updatedAt) - Date.parse(a.updatedAt);
+        const focused = this.frontmostPreferredClient();
+        this.refreshThreadCounts();
+        const now = Date.now();
+        const sessions = [...this.scores.values()].map((score) => {
+            // Liveness uses file mtime (real last write), not score.updatedAt — the Claude cache stamps
+            // updatedAt = now on every read, which would make an idle session look permanently live.
+            const mtimeMs = this.mtimes.get(score.client) ?? (Date.parse(score.updatedAt) || now);
+            const lastActiveMs = Math.max(0, now - mtimeMs);
+            return {
+                ...score,
+                live: lastActiveMs < LIVE_WINDOW_MS,
+                focused: focused === score.client,
+                label: this.labelFor(score),
+                lastActiveMs,
+            };
+        });
+        // focused first, then live (most-recent first), then idle (most-recent first).
+        sessions.sort((a, b) => {
+            if (a.focused !== b.focused)
+                return a.focused ? -1 : 1;
+            if (a.live !== b.live)
+                return a.live ? -1 : 1;
+            return a.lastActiveMs - b.lastActiveMs;
         });
         return {
             mode: this.mode,
-            active: scores[0] || null,
-            scores,
+            active: sessions[0] || null,
+            scores: sessions,
+            sessions,
+            threadCounts: this.threadCounts,
             missing: this.missing,
             updatedAt: new Date().toISOString(),
         };
     }
+    labelFor(score) {
+        const cached = this.labelCache.get(score.sourcePath);
+        if (cached)
+            return cached;
+        const label = sessionLabel(score.sourcePath, score.client);
+        this.labelCache.set(score.sourcePath, label);
+        return label;
+    }
     frontmostPreferredClient() {
         if (this.mode !== "auto" && this.mode !== "both")
             return null;
         const now = Date.now();
         if (now - this.frontmostCheckedAt > 1500) {
             this.frontmostCheckedAt = now;
-            this.frontmostClient = detectFrontmostClient();
+            const detected = detectFrontmostClient();
+            if (detected) {
+                // Positive detection wins immediately (real focus switch, e.g. Codex → Claude Desktop).
+                this.frontmostClient = detected;
+                this.frontmostSeenAt = now;
+            }
+            else if (now - this.frontmostSeenAt > FOCUS_GRACE_MS) {
+                // Detection missed (osascript timeout, or a non-agent app like a browser is front). Hold the
+                // last-known focus for a grace window so the active slot doesn't flip to a background client
+                // just because it's writing — then release once the grace expires.
+                this.frontmostClient = null;
+            }
         }
         return this.frontmostClient && this.scores.has(this.frontmostClient) ? this.frontmostClient : null;
     }
+    // Count each client's "ongoing" threads = session files written within ONGOING_WINDOW_MS. Throttled,
+    // since it walks every session file per client (cheap at a few-second cadence, wasteful at 750ms).
+    refreshThreadCounts() {
+        const now = Date.now();
+        if (now - this.threadCountsAt < 2500 && Object.keys(this.threadCounts).length)
+            return;
+        this.threadCountsAt = now;
+        const counts = {};
+        for (const adapter of adapterList(this.mode)) {
+            let n = 0;
+            for (const file of adapter.findAll()) {
+                try {
+                    if (now - fs.statSync(file).mtimeMs < ONGOING_WINDOW_MS)
+                        n += 1;
+                }
+                catch {
+                    /* ignore files that vanish mid-walk */
+                }
+            }
+            counts[adapter.client] = n;
+        }
+        this.threadCounts = counts;
+    }
     tick() {
         const missing = [];
         let changed = false;
         for (const adapter of adapterList(this.mode)) {
             const file = adapter.findActive();
-            if (!file) {
+            let stat = null;
+            if (file) {
+                try {
+                    stat = fs.statSync(file);
+                }
+                catch {
+                    stat = null;
+                }
+            }
+            if (!file || !stat) {
                 missing.push(adapter.client);
                 if (this.scores.delete(adapter.client))
                     changed = true;
+                this.mtimes.delete(adapter.client);
                 continue;
             }
-            const signature = statSignature(file);
-            if (!signature || signature === this.signatures.get(adapter.client))
+            this.mtimes.set(adapter.client, liveMtime(adapter.client, file, stat.mtimeMs));
+            const signature = `${file}:${stat.size}:${stat.mtimeMs}`;
+            if (signature === this.signatures.get(adapter.client))
                 continue;
             this.signatures.set(adapter.client, signature);
             try {
@@ -104,3 +185,60 @@ function detectFrontmostClient() {
     }
     return null;
 }
+function defaultLabel(client) {
+    if (client === "codex")
+        return "Codex";
+    if (client === "claude-code")
+        return "Claude Code";
+    return "Claude Desktop";
+}
+// Recognizable label = basename of the session's cwd. Both Codex rollouts and Claude transcripts
+// carry a "cwd" field; the Claude Code active source is the echo-ctx cache (<sessionId>.json, no cwd),
+// so resolve its transcript by sessionId first. Falls back to the client name when cwd is absent.
+function sessionLabel(file, client) {
+    const target = resolveClaudeTranscript(file) ?? file;
+    const cwd = peekCwd(target);
+    return cwd ? path.basename(cwd) : defaultLabel(client);
+}
+// The Claude Code active source is the echo-ctx cache (<sessionId>.json), whose mtime only bumps when
+// the statusline re-renders — stale during a long turn. The transcript grows every tool call, so it's
+// the true liveness signal. Take the fresher of the two. Cached per cache-file (paths are stable).
+function liveMtime(client, file, cacheMtimeMs) {
+    const transcript = client === "claude-code" ? resolveClaudeTranscript(file) : null;
+    if (!transcript)
+        return cacheMtimeMs;
+    try {
+        return Math.max(cacheMtimeMs, fs.statSync(transcript).mtimeMs);
+    }
+    catch {
+        return cacheMtimeMs;
+    }
+}
+const transcriptCache = new Map();
+function resolveClaudeTranscript(cacheFile) {
+    if (!cacheFile.endsWith(".json") || !cacheFile.includes(`${path.sep}echo-ctx${path.sep}`))
+        return null;
+    if (transcriptCache.has(cacheFile))
+        return transcriptCache.get(cacheFile) ?? null;
+    const sessionId = path.basename(cacheFile, ".json");
+    const transcript = newestFile(walkFiles(homePath(".claude", "projects"), (f) => path.basename(f) === `${sessionId}.jsonl`));
+    transcriptCache.set(cacheFile, transcript);
+    return transcript;
+}
+function peekCwd(file) {
+    try {
+        const fd = fs.openSync(file, "r");
+        try {
+            const buf = Buffer.alloc(256 * 1024);
+            const bytes = fs.readSync(fd, buf, 0, buf.length, 0);
+            const match = buf.toString("utf8", 0, bytes).match(/"cwd"\s*:\s*"([^"]+)"/);
+            return match ? match[1].replace(/\\\//g, "/") : null;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+}