@echomem/mcp 1.4.49 → 1.4.51

package/README.md

@@ -54,7 +54,7 @@ npx -y @echomem/mcp@latest init
 Windows PowerShell:
 
 ```powershell
-npx.cmd -y @echomem/mcp@latest init
+npx.cmd -y @echomem/mcp@latest connect
 ```
 
 The one-off `npx` command is the recommended install path; it stages a durable per-user runtime
@@ -63,7 +63,9 @@ Node if `npx.cmd` is not found.
 
 | Command | What it does |
 |---|---|
-| `npm i -g @echomem/mcp@latest && echomem-mcp init` | Legacy/headless setup for installed agents + login |
+| `npx -y @echomem/mcp@latest connect` | Open Connect Echo for account readiness, per-host setup, Doctor, repair, and uninstall (use `npx.cmd` in Windows PowerShell) |
+| `npx -y @echomem/mcp@latest init` | One-command setup for installed agents + login (use `npx.cmd` in Windows PowerShell) |
+| `npm i -g @echomem/mcp@latest`, then `echomem-mcp init` | Optional global install for a persistent CLI command |
 | `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and configure just the detected editor |
 | `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
 | `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config + log in |
@@ -75,8 +77,31 @@ Node if `npx.cmd` is not found.
 | `echomem-mcp lock` | Remove the local vault key while keeping the device login |
 | `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 control` / `manage` | Compatibility aliases for the returning-user Connect Echo page |
+| `echomem-mcp reconnect` | Clean-reinstall EchoMem's managed runtime, clear inactive runtime cache, and repair detected host entries |
+| `echomem-mcp uninstall --confirm` | Remove EchoMem MCP host entries/runtime while preserving login, vault credentials, and cloud memories |
 | `echomem-mcp logout` | Remove stored credentials |
 
+### Windows Connect Echo (no desktop app required)
+
+If you installed the optional global CLI, run this from PowerShell:
+
+```powershell
+echomem-mcp connect
+```
+
+For the recommended one-off install, launch the same local control page with:
+
+```powershell
+npx.cmd -y @echomem/mcp@latest connect
+```
+
+The page binds only to `127.0.0.1` and uses a per-launch nonce. It validates account/vault state,
+shows each detected MCP host independently, and provides Connect, Repair, Disconnect, Doctor, and
+clean Reconnect actions. **Uninstall MCP** stays under Advanced controls and removes only EchoMem-owned
+host entries, hooks, guidance, skills, and managed runtime files; it does not remove the local
+EchoMem credential store or any cloud memory. Restart each agent after configuration changes.
+
 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. Standalone installations
 stage compatible updates in the background under `~/.echomem/mcp-runtime` and atomically activate

package/dist/config-files.js

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+function isErrno(error, code) {
+    return error instanceof Error
+        && "code" in error
+        && error.code === code;
+}
+/**
+ * Read a user-owned JSON configuration without treating corruption as an empty file.
+ * Setup must fail closed here: replacing malformed JSON would destroy unrelated client settings.
+ */
+export function readJsonObjectFile(file, label = "configuration") {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return {};
+        throw new Error(`Could not read ${label} at ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Could not safely update ${label} at ${file} because the existing file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Could not safely update ${label} at ${file} because the existing JSON root is not an object.`);
+    }
+    return parsed;
+}
+/** Write beside the destination and rename only after the complete replacement is durable locally. */
+export function atomicWriteTextFile(file, content) {
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true });
+    const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    let mode;
+    try {
+        mode = fs.statSync(file).mode;
+    }
+    catch {
+        /* A fresh file uses the process default mode. */
+    }
+    try {
+        fs.writeFileSync(temporary, content, mode === undefined ? undefined : { mode });
+        fs.renameSync(temporary, file);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch {
+            /* Preserve the original error. */
+        }
+        throw error;
+    }
+}
+export function atomicWriteJsonObject(file, value) {
+    atomicWriteTextFile(file, JSON.stringify(value, null, 2));
+}

package/dist/durable-entry.js

@@ -0,0 +1,122 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation } from "./headless-runtime.js";
+import { MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION } from "./package-metadata.js";
+/**
+ * Resolving a DURABLE path to this package's own files.
+ *
+ * Anything we write into another program's config — an MCP server entry, a lifecycle hook command —
+ * outlives the process that wrote it. Pinning such a path to the npx cache (`…/_npx/<hash>/…`) works
+ * until npm garbage-collects that directory, after which the entry silently points at nothing. So
+ * prefer, in order: the managed runtime under ~/.echomem, the running copy when it is not itself
+ * ephemeral, then a global install.
+ */
+/** True when a resolved entry lives inside npx's throwaway cache (`…/_npx/<hash>/…`). */
+export function isEphemeralNpxPath(entry) {
+    return entry.split(path.sep).includes("_npx");
+}
+/**
+ * Locate a DURABLE global install of the bridge (the one `npm i -g @echomem/mcp` creates). Global
+ * modules sit next to the running node — `<node>/../lib/node_modules` (nvm/unix) or `<node>/node_modules`
+ * (Windows). Returns the realpath'd dist entry, or null when the package isn't globally installed.
+ */
+export function resolveGlobalEntry() {
+    const nodeDir = path.dirname(process.execPath);
+    const pkgParts = MCP_PACKAGE_NAME.split("/"); // ["@echomem", "mcp"]
+    const candidates = [
+        path.join(nodeDir, "..", "lib", "node_modules", ...pkgParts, "dist", "index.js"),
+        path.join(nodeDir, "node_modules", ...pkgParts, "dist", "index.js"),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (fs.existsSync(candidate))
+                return fs.realpathSync(candidate);
+        }
+        catch {
+            /* keep trying */
+        }
+    }
+    return null;
+}
+/** The dist directory this module was loaded from. */
+function runningDistDir() {
+    return fileURLToPath(new URL("./", import.meta.url));
+}
+/**
+ * Absolute path to `dist/<relative>` from the most durable copy of this package available.
+ *
+ * `ephemeral` in the result flags the last-resort case: no durable copy exists, so the caller is
+ * about to persist a path that npm may collect. A working hook now beats no hook at all, but the
+ * caller should say so rather than fail silently.
+ */
+export function resolveDurableDistPath(relative) {
+    const managed = readHeadlessRuntimeInstallation();
+    if (managed?.entry) {
+        const candidate = path.join(path.dirname(managed.entry), relative);
+        if (fs.existsSync(candidate))
+            return { path: candidate, ephemeral: false };
+    }
+    const local = path.join(runningDistDir(), relative);
+    const localIsEphemeral = isEphemeralNpxPath(local);
+    if (!localIsEphemeral && fs.existsSync(local))
+        return { path: local, ephemeral: false };
+    const globalEntry = resolveGlobalEntry();
+    if (globalEntry) {
+        const candidate = path.join(path.dirname(globalEntry), relative);
+        if (fs.existsSync(candidate))
+            return { path: candidate, ephemeral: false };
+    }
+    return { path: local, ephemeral: localIsEphemeral };
+}
+/** Set on the child so a re-exec can never recurse. */
+const REEXEC_GUARD = "ECHO_DURABLE_REEXEC";
+/**
+ * Hand a config-writing command over to the durable runtime before it writes anything.
+ *
+ * `npx @echomem/mcp init` runs from `_npx/<hash>`, a directory npm garbage-collects. Every path such
+ * a process persists into someone else's config — hook commands, MCP entries — inherits that
+ * lifetime. Re-executing from `~/.echomem/mcp-runtime` first makes those writes durable by
+ * construction, instead of relying on each call site to remember.
+ *
+ * Version skew is resolved by upgrading rather than skipping: the durable copy is installed at the
+ * invoking package's version before control passes to it, so a newer `npx` never hands off to an
+ * older runtime. Installation is idempotent, so the child re-verifying costs nothing.
+ *
+ * Returns the child's exit status when it ran (the caller should exit with it), or null when the
+ * command should proceed in this process. Every failure path returns null: a re-exec that cannot
+ * happen must degrade to the old behaviour, never dead-end.
+ */
+export function reexecFromDurableRuntime(argv) {
+    if (process.env[REEXEC_GUARD] === "1")
+        return null;
+    if (process.env.ECHO_DISABLE_RUNTIME_BOOTSTRAP === "1")
+        return null;
+    if (!isEphemeralNpxPath(runningDistDir()))
+        return null;
+    // Version comes from the package.json beside dist/. If that could not be read we would ask the
+    // registry for a version that does not exist, so stay in-process rather than spend the round trip.
+    if (MCP_PACKAGE_VERSION === "0.0.0")
+        return null;
+    let installation = readHeadlessRuntimeInstallation();
+    if (installation?.version !== MCP_PACKAGE_VERSION) {
+        try {
+            installation = installHeadlessRuntimeSync(MCP_PACKAGE_VERSION);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!installation?.entry || !fs.existsSync(installation.entry))
+        return null;
+    console.log(`Running from the durable ${MCP_PACKAGE_NAME}@${installation.version} runtime so configured paths outlive the npx cache.`);
+    const result = spawnSync(process.execPath, [installation.entry, ...argv], {
+        stdio: "inherit",
+        env: { ...process.env, [REEXEC_GUARD]: "1" },
+        windowsHide: true,
+    });
+    if (result.error)
+        return null;
+    return result.status ?? 0;
+}

package/dist/headless-runtime.js

@@ -173,28 +173,79 @@ function finishStaging(staging, destination, version) {
     fs.renameSync(staging, destination);
     return activateRuntime(destination, version);
 }
-export function installHeadlessRuntimeSync(targetVersion = MCP_PACKAGE_VERSION) {
+function pruneInactiveRuntimeVersions(activeVersion) {
+    const removed = [];
+    let entries = [];
+    try {
+        entries = fs.readdirSync(versionsRoot(), { withFileTypes: true });
+    }
+    catch {
+        return removed;
+    }
+    for (const entry of entries) {
+        // A dot-prefixed directory is another install's staging area. Never prune in-flight work.
+        if (entry.name === activeVersion || entry.name.startsWith("."))
+            continue;
+        try {
+            safeVersion(entry.name);
+        }
+        catch {
+            continue;
+        }
+        const target = path.join(versionsRoot(), entry.name);
+        try {
+            fs.rmSync(target, { recursive: true, force: true });
+            removed.push(entry.name);
+        }
+        catch {
+            /* Cache pruning is best effort; the active clean runtime is already safe. */
+        }
+    }
+    return removed;
+}
+export function installHeadlessRuntimeSync(targetVersion = MCP_PACKAGE_VERSION, options = {}) {
     const version = safeVersion(targetVersion);
     const existing = readHeadlessRuntimeInstallation();
-    if (existing?.version === version)
+    if (!options.force && existing?.version === version)
         return existing;
     const destination = path.join(versionsRoot(), version);
-    if (readPackageVersion(destination) === version && fs.existsSync(packageEntryForPrefix(destination))) {
-        return activateRuntime(destination, version);
+    if (!options.force && readPackageVersion(destination) === version && fs.existsSync(packageEntryForPrefix(destination))) {
+        const installation = activateRuntime(destination, version);
+        if (options.prune)
+            pruneInactiveRuntimeVersions(version);
+        return installation;
     }
-    const { staging } = prepareStaging(version);
-    const npm = resolveNpmInvocation();
+    const releaseLock = acquireUpdateLock();
+    if (!releaseLock)
+        throw new Error("Another EchoMem runtime update is already in progress. Retry reconnect in a moment.");
+    let staging = "";
     try {
+        staging = prepareStaging(version).staging;
+        const npm = resolveNpmInvocation();
         execFileSync(npm.command, [...npm.prefixArgs, ...npmInstallArguments(staging, version)], {
             stdio: "inherit",
             windowsHide: true,
         });
-        return finishStaging(staging, destination, version);
+        const installation = finishStaging(staging, destination, version);
+        if (options.prune)
+            pruneInactiveRuntimeVersions(version);
+        return installation;
     }
     catch (error) {
-        fs.rmSync(staging, { recursive: true, force: true });
+        if (staging)
+            fs.rmSync(staging, { recursive: true, force: true });
         throw new Error(`Could not stage ${MCP_PACKAGE_NAME}@${version}: ${error instanceof Error ? error.message : String(error)}`);
     }
+    finally {
+        releaseLock();
+    }
+}
+/** Remove only EchoMem's staged standalone runtime. Credentials and cloud data live elsewhere. */
+export function removeHeadlessRuntime() {
+    const root = headlessRuntimeRoot();
+    const removed = fs.existsSync(root);
+    fs.rmSync(root, { recursive: true, force: true });
+    return { removed, path: root };
 }
 function acquireUpdateLock() {
     const lock = path.join(headlessRuntimeRoot(), "update.lock");

package/dist/hud/hooks.js

@@ -1,7 +1,21 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { atomicWriteJsonObject, readJsonObjectFile } from "../config-files.js";
+import { resolveDurableDistPath } from "../durable-entry.js";
+/**
+ * Hook commands are persisted into another program's settings and must keep working long after this
+ * process exits. Resolving them from `import.meta.url` pins them to whatever copy happens to be
+ * running — under `npx` that is the `_npx/<hash>` cache, which npm garbage-collects, leaving a hook
+ * that points at nothing. Always resolve through the durable-entry helper instead.
+ */
+function hookCommandFor(distRelative, subcommand) {
+    const cli = resolveDurableDistPath(distRelative);
+    if (cli.ephemeral) {
+        console.warn(`⚠️  EchoMem hooks are being pinned to a temporary npx path (${cli.path}). They will stop working once npm clears its cache — install the durable runtime or a global package to make them permanent.`);
+    }
+    return `${JSON.stringify(process.execPath)} ${JSON.stringify(cli.path)} ${subcommand}`;
+}
 export function installHooks(mode) {
     const written = [];
     if (mode === "codex" || mode === "both" || mode === "auto") {
@@ -32,46 +46,81 @@ export function installSourceSessionHooks(mode) {
     }
     return written;
 }
+/** Remove only EchoMem-owned lifecycle hook groups and preserve every unrelated user hook. */
+export function removeLifecycleHooks(mode) {
+    const files = [];
+    let removedGroups = 0;
+    const targets = [];
+    if (mode === "codex" || mode === "both" || mode === "auto") {
+        targets.push(path.join(profileDirectory("CODEX_HOME", ".codex"), "hooks.json"));
+    }
+    if (mode === "claude-code" || mode === "both" || mode === "auto") {
+        targets.push(path.join(profileDirectory("CLAUDE_CONFIG_DIR", ".claude"), "settings.json"));
+    }
+    for (const file of targets) {
+        if (!fs.existsSync(file))
+            continue;
+        const content = readHooksFile(file);
+        const hooks = content.hooks;
+        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+            continue;
+        let changed = false;
+        for (const [event, value] of Object.entries(hooks)) {
+            if (!Array.isArray(value))
+                continue;
+            const kept = value.filter((group) => !isEchoLifecycleGroup(group));
+            const removed = value.length - kept.length;
+            if (removed === 0)
+                continue;
+            removedGroups += removed;
+            changed = true;
+            if (kept.length > 0)
+                hooks[event] = kept;
+            else
+                delete hooks[event];
+        }
+        if (!changed)
+            continue;
+        if (Object.keys(hooks).length === 0)
+            delete content.hooks;
+        atomicWriteJsonObject(file, content);
+        files.push(file);
+    }
+    return { files, removedGroups };
+}
 function installCodexHooks() {
-    const dir = path.join(os.homedir(), ".codex");
+    const dir = profileDirectory("CODEX_HOME", ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
-    const hookCommand = `${JSON.stringify(process.execPath)} ${JSON.stringify(process.argv[1])} summary --client codex --json`;
+    const hookCommand = hookCommandFor("index.js", "summary --client codex --json");
     const content = readHooksFile(file);
     content.hooks = content.hooks || {};
-    content.hooks.PostToolUse = mergeHookGroup(content.hooks.PostToolUse, { matcher: "*", hooks: [{ type: "command", command: hookCommand, timeout: 5 }] });
-    content.hooks.PostCompact = mergeHookGroup(content.hooks.PostCompact, { hooks: [{ type: "command", command: hookCommand, timeout: 5 }] });
-    content.hooks.Stop = mergeHookGroup(content.hooks.Stop, { hooks: [{ type: "command", command: hookCommand, timeout: 5 }] });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    content.hooks.PostToolUse = mergeHookGroup(content.hooks.PostToolUse, { matcher: "*", hooks: [codexCommandHook(hookCommand, 5)] });
+    content.hooks.PostCompact = mergeHookGroup(content.hooks.PostCompact, { hooks: [codexCommandHook(hookCommand, 5)] });
+    content.hooks.Stop = mergeHookGroup(content.hooks.Stop, { hooks: [codexCommandHook(hookCommand, 5)] });
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function saveCheckpointCommand() {
-    const lifecycleCli = fileURLToPath(new URL("./cli.js", import.meta.url));
-    return `${JSON.stringify(process.execPath)} ${JSON.stringify(lifecycleCli)} save-checkpoint`;
+    return hookCommandFor(path.join("hud", "cli.js"), "save-checkpoint");
 }
 function sourceSessionCommand() {
-    const lifecycleCli = fileURLToPath(new URL("./cli.js", import.meta.url));
-    return `${JSON.stringify(process.execPath)} ${JSON.stringify(lifecycleCli)} bind-source-session`;
+    return hookCommandFor(path.join("hud", "cli.js"), "bind-source-session");
 }
 function installCodexSourceSessionHook() {
-    const dir = path.join(os.homedir(), ".codex");
+    const dir = profileDirectory("CODEX_HOME", ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
     content.hooks = content.hooks || {};
     content.hooks.SessionStart = mergeSourceSessionGroup(content.hooks.SessionStart, {
-        hooks: [{
-                type: "command",
-                command: sourceSessionCommand(),
-                timeout: 5,
-                statusMessage: "Binding EchoMem to this conversation",
-            }],
+        hooks: [codexCommandHook(sourceSessionCommand(), 5, "Binding EchoMem to this conversation")],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installClaudeCodeSourceSessionHook() {
-    const dir = path.join(os.homedir(), ".claude");
+    const dir = profileDirectory("CLAUDE_CONFIG_DIR", ".claude");
     const file = path.join(dir, "settings.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
@@ -84,28 +133,23 @@ function installClaudeCodeSourceSessionHook() {
                 statusMessage: "Binding EchoMem to this conversation",
             }],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installCodexSaveCheckpointHook() {
-    const dir = path.join(os.homedir(), ".codex");
+    const dir = profileDirectory("CODEX_HOME", ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
     content.hooks = content.hooks || {};
     content.hooks.Stop = mergeSaveCheckpointGroup(content.hooks.Stop, {
-        hooks: [{
-                type: "command",
-                command: saveCheckpointCommand(),
-                timeout: 10,
-                statusMessage: "Checking whether completed work should be remembered",
-            }],
+        hooks: [codexCommandHook(saveCheckpointCommand(), 10, "Checking whether completed work should be remembered")],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installClaudeCodeSaveCheckpointHook() {
-    const dir = path.join(os.homedir(), ".claude");
+    const dir = profileDirectory("CLAUDE_CONFIG_DIR", ".claude");
     const file = path.join(dir, "settings.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
@@ -118,22 +162,40 @@ function installClaudeCodeSaveCheckpointHook() {
                 statusMessage: "Checking whether completed work should be remembered",
             }],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installClaudeCodeSnippet() {
-    const dir = path.join(os.homedir(), ".claude", "echo-ctx");
+    const dir = path.join(profileDirectory("CLAUDE_CONFIG_DIR", ".claude"), "echo-ctx");
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }
 function readHooksFile(file) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
-        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    return readJsonObjectFile(file, "agent hooks");
+}
+function profileDirectory(envKey, fallbackName) {
+    const home = os.homedir();
+    const configured = process.env[envKey]?.trim();
+    if (!configured)
+        return path.join(home, fallbackName);
+    if (configured === "~")
+        return home;
+    if (configured.startsWith("~/") || configured.startsWith("~\\")) {
+        return path.join(home, configured.slice(2));
     }
-    catch {
-        return {};
+    if (!path.isAbsolute(configured)) {
+        throw new Error(`${envKey} must be an absolute path or start with ~/`);
     }
+    return path.normalize(configured);
+}
+function codexCommandHook(command, timeout, statusMessage) {
+    return {
+        type: "command",
+        command,
+        commandWindows: command,
+        timeout,
+        ...(statusMessage ? { statusMessage } : {}),
+    };
 }
 function mergeHookGroup(existing, group) {
     const groups = Array.isArray(existing) ? existing.filter((item) => !isEchoHudGroup(item)) : [];
@@ -165,3 +227,6 @@ function isEchoSaveCheckpointGroup(value) {
         return false;
     return JSON.stringify(value).includes("save-checkpoint");
 }
+function isEchoLifecycleGroup(value) {
+    return isEchoHudGroup(value) || isEchoSourceSessionGroup(value) || isEchoSaveCheckpointGroup(value);
+}