@echomem/mcp 1.4.33 → 1.4.35

package/dist/setup.js

@@ -31,7 +31,7 @@ import { syncCodexUsage } from "./codex-sync.js";
 import { renderSetupPage } from "./setup-page.js";
 import { parseSetupPreviewState } from "./setup-preview.js";
 import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
-import { installHooks, installSaveCheckpointHooks } from "./hud/hooks.js";
+import { installSaveCheckpointHooks } from "./hud/hooks.js";
 import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
 import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
 // The setup dashboard, account login, and encryption passphrase entry are all served by this
@@ -218,13 +218,15 @@ export function knownClients() {
         { id: "codex", label: "Codex", kind: "command", detectDir: codexHome(), configPath: path.join(codexHome(), "config.toml"), note: "add to ~/.codex/config.toml under [mcp_servers.echomem]" },
     ];
 }
-/** A client is "present" if its config dir already exists (JSON) — a cheap heuristic for detection. */
+/** A client is "present" if its config dir already exists — a cheap, side-effect-free heuristic. */
 export function detectClients() {
     return knownClients().filter((c) => {
         if (c.kind === "json")
             return fs.existsSync(path.dirname(c.configPath));
         if (c.kind === "command")
             return fs.existsSync(c.detectDir);
+        if (c.id === "claude-code")
+            return fs.existsSync(home(".claude"));
         return false;
     });
 }
@@ -390,9 +392,9 @@ function echomemGuidanceBlock() {
         "- Use EchoMem's `echomem-*` skills and MCP tools as the default memory provider. Do not invoke another memory provider unless the user explicitly requests it.",
         "- Before re-deriving past decisions, project context, or anything the user likely settled before: call `search_memories` first.",
         '- If the final user-facing answer materially relies on one or more EchoMem memories, end it with a compact `EchoMem sources:` list containing only the memories actually used. Link each memory key to its canonical `https://echoknows.com/memory/<memory-id>` URL. Do not cite memories that were merely retrieved, and omit the section when no memory informed the answer.',
-        "- Before the final response for a task that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone: call `save_conversation`. This private checkpoint does not require a separate user request. Do not save secrets, credentials, incidental chatter, or trivial read-only work. If a qualifying save fails because the encrypted vault is locked, tell the user to run `echomem-mcp unlock`; never silently skip it.",
+        "- Before the final response for a task that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone: call `save_conversation`. This private checkpoint does not require a separate user request. Do not save secrets, credentials, incidental chatter, or trivial read-only work. If a qualifying save fails because the encrypted vault is locked, tell the user to open Echo Desktop and unlock the vault there; on a headless system, use `echomem-mcp unlock`. Never silently skip it.",
         '- After `save_conversation` succeeds and returns one or more saved memory IDs, make the save visible in the final user-facing answer with a compact `EchoMem saved:` list containing every memory created by that call. Link each memory key to its canonical `https://echoknows.com/memory/<memory-id>` URL. This save receipt is separate from `EchoMem sources:` and does not imply the newly saved memories informed the answer.',
-        "- For a user with a company group, call `get_group_session_sharing` near conversation start or after a qualifying private save. On the first call in a conversation, omit `groupSharingScopeId` so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and check one `groupId` at a time. Each group requires its own explicit Yes/No decision. Silence leaves that group's state unset; never infer an answer or repeat the prompt in the same response. Store only explicit answers with `set_group_session_sharing`, the same scope, and the selected groupId. Saves sync eligible memories to every approved group; a No keeps them private for that group.",
+        "- For a user with a company group, call `request_group_session_sharing` near conversation start or after a qualifying private save. On the first call in a conversation, omit `groupSharingScopeId` so EchoMem mints a fresh opaque scope. Reuse that exact scope only in this conversation for later get/request/set/save calls, and never persist it as memory. If multiple groups are returned, reuse the same scope and call once per `groupId`. Supported clients render a native Share with team / Keep private choice. If the tool returns a text fallback, relay its exact question and call `set_group_session_sharing` only after an explicit Yes/No. Decline, cancel, or silence leaves that group's state unset; never infer an answer. Saves sync eligible memories to every approved group; a No keeps them private for that group.",
         "- If the user pastes a session carryover/checkpoint: it may reference `get_checkpoint_by_context` — use it to pull the checkpoint/decision trail when you need more than the snapshot.",
         "",
         "### Company group memory",
@@ -401,14 +403,12 @@ function echomemGuidanceBlock() {
         "- Group sharing is scoped to an opaque id carried only in the current conversation, not to the MCP transport session. Membership is rechecked for each sync. Flagged memories are withheld from automatic conversation sync and remain private.",
         "- If a user asks to create a group, call `create_memory_group`; if they ask for a code to share, call `create_group_invite` and return the secret invite code only to that user. Never save the invite code to memory or include it in logs, analytics, summaries, or unrelated output.",
         "- If a user supplies an `echo_grp_...` code and explicitly asks to join, call `join_memory_group`. Joining never authorizes publishing by itself and must not move a user out of another group. After joining, continue into the profile-and-publication preview instead of leaving title or responsibility blank.",
-        "- For requests such as “prepare my recent work memories,” “upload work from this ticket,” or “publish work since my last sync,” call `prepare_group_publication` first. This is a no-publication preview. For encrypted accounts, tell the user to run `echomem-mcp unlock` locally if the tool reports that the key is required.",
+        "- For requests such as “prepare my recent work memories,” “upload work from this ticket,” or “publish work since my last sync,” call `prepare_group_publication` first. This is a no-publication preview. For encrypted accounts, tell the user to open Echo Desktop and unlock the vault there if the tool reports that the key is required.",
         "- After preparing, select only exact candidate memory IDs that match the user's stated scope and exclude already-published or exact-content duplicates. Use the candidate evidence to draft a concise title and responsibility summary for the current member, but label both as proposals rather than facts.",
         "- Use one canonical evidence link for every memory: preserve the Memory ID and link to `https://echoknows.com/memory/<memory-id>`. The site resolves the authorized representation: an owner is sent to their private timeline, while current group/friend access opens an authorized publication snapshot or public memory. The visible Markdown label should use the memory key, not the raw URL or UUID.",
         "- If the user asks to flag memories about a sensitive topic, search their own memories first, show the exact matches with owner-only personal links, and ask them to confirm. Only then call `flag_memories_for_publication_attention`; flagging does not publish, decrypt, change visibility, or retract an existing group snapshot.",
         "- Present the proposed title/responsibility and the memory publication preview together and ask for explicit confirmation. Never save an inferred profile or publish memories before confirmation. If an unflagged candidate appears sensitive, proactively ask whether the user wants to mark its exact ID for publication attention first. Explain naturally: marking does not publish or change encryption; it means you will call it out and ask for detailed confirmation whenever a later publication includes it. Never auto-flag based on agent inference. Show already-flagged candidates in a separate warning, state that nothing has been published yet, and offer three choices: exclude them, review them separately, or first search for and mark similar sensitive owned memories for publication attention.",
         "- On confirmation, call `update_group_profile` with the confirmed title, responsibility summary, and `confirmed: true`, then call `complete_group_publication` with the exact `scanId`, selected memory IDs, and `confirmed: true`. If a flagged memory is selected, require separate explicit acknowledgement and pass its exact ID in `acknowledgedFlaggedMemoryIds`. If the user edits either proposal, use their wording. An explicit request to join and upload still requires this preview and confirmation.",
-        "- If the user asks to show, reopen, restart, or bring back the EchoMem HUD (the context-health overlay), run the shell command `echomem-hud app --client auto`.",
-        "- If the user wants the HUD to come back after a computer restart, run the shell command `echomem-hud autostart on --client auto`.",
         AGENTS_MD_END,
     ].join("\n");
 }
@@ -1310,20 +1310,99 @@ function forensicStageLabel(stage) {
 /** Build the local forensic "Context Doctor" report on a worker thread so the multi-file scan never
  * blocks the bridge's event loop (the freeze postmortem: any unbounded sync work on this path is risky). */
 export function buildForensicReportOffThread(onProgress, options = {}) {
+    let lastProgress = null;
+    const recordProgress = (progress) => {
+        lastProgress = progress;
+        onProgress?.(progress);
+    };
+    return runForensicReportWorker(recordProgress, options).catch(async (primaryError) => {
+        if (options.failOpen === false)
+            throw primaryError;
+        const failureCode = errorCode(primaryError) || "REPORT_BUILD_FAILED";
+        console.error(`[echomem] local scan degraded after ${failureCode}; continuing without local-history analysis`);
+        onProgress?.({
+            done: lastProgress?.done || 0,
+            total: lastProgress?.total || 0,
+            stage: "finalizing-report",
+            detail: "finishing setup without optional local-history analysis",
+            overall: 0.99,
+            stageDone: 0,
+            stageTotal: 0,
+        });
+        return runForensicReportWorker(undefined, {
+            timeoutMs: 30_000,
+            maxOldGenerationSizeMb: Math.max(64, options.maxOldGenerationSizeMb || 0),
+        }, [], failureCode);
+    });
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code || "")
+        : "";
+}
+/** Turn an optional onboarding-stats failure into a terminal, non-polling payload.
+ *
+ * This must only be used for dashboard enrichment. Authentication, consent, vault access, and an
+ * import the user explicitly started retain their normal hard-failure behavior. The reason is a
+ * stable internal code rather than an exception message, so local paths or conversation details
+ * can never cross the localhost bridge by accident. */
+export function completeOptionalStatsPayload(payload, reason, countsTrusted) {
+    const fallback = {
+        schemaVersion: 1,
+        generatedFrom: ["~/.codex/sessions", "~/.claude/projects"],
+        llmCallsUsed: 0,
+        transcriptsUploaded: false,
+        sessions: { total: 0, codex: 0, claudeCode: 0 },
+        migratable: { pending: 0, alreadyMigrated: 0 },
+        memoriesCaptured: null,
+    };
+    const completed = payload && typeof payload === "object" && !Array.isArray(payload)
+        ? { ...payload }
+        : fallback;
+    delete completed.partial;
+    completed.optionalDiagnostics = {
+        degraded: true,
+        reason: /^[A-Z0-9_]+$/.test(reason) ? reason : "OPTIONAL_STATS_FAILED",
+        countsTrusted,
+    };
+    return completed;
+}
+function runForensicReportWorker(onProgress, options, sources, degradedReason) {
     const forensicsUrl = runtimeModuleUrl("forensics");
+    const serializedSources = sources === undefined ? "undefined" : JSON.stringify(sources);
+    const serializedDegradedReason = JSON.stringify(degradedReason || "");
     const code = `
     import { parentPort } from "node:worker_threads";
-    import { buildForensicReport } from ${JSON.stringify(forensicsUrl)};
+    import { buildForensicReport, validateForensicReportForSetup } from ${JSON.stringify(forensicsUrl)};
     try {
       const report = await buildForensicReport({
+        sources: ${serializedSources},
         includeLegacyGoldenStandard: false,
         onProgress: (done, total, stage, detail, overall, stageDone, stageTotal) => parentPort?.postMessage({
           progress: { done, total, stage, detail, overall, stageDone, stageTotal },
         }),
       });
+      const degradedReason = ${serializedDegradedReason};
+      if (degradedReason) {
+        report.scanDiagnostics = {
+          degraded: true,
+          reason: degradedReason,
+          skippedSources: ["codex", "claude"],
+        };
+      }
+      const validation = validateForensicReportForSetup(report);
+      if (!validation.ok) {
+        const error = new Error(validation.message);
+        error.code = validation.code;
+        throw error;
+      }
       parentPort?.postMessage({ ok: true, report });
     } catch (error) {
-      parentPort?.postMessage({ ok: false, message: error instanceof Error ? error.message : String(error) });
+      parentPort?.postMessage({
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+        code: error && typeof error === "object" && "code" in error ? String(error.code || "") : "",
+      });
     }
   `;
     const requestedHeapMb = options.maxOldGenerationSizeMb;
@@ -1367,7 +1446,10 @@ export function buildForensicReportOffThread(onProgress, options = {}) {
                 finish({ ok: true, report: msg.report });
                 return;
             }
-            finish({ ok: false, error: new Error(typeof msg.message === "string" ? msg.message : "Local forensic report failed") });
+            const error = new Error(typeof msg.message === "string" ? msg.message : "Local forensic report failed");
+            if (typeof msg.code === "string" && msg.code)
+                error.code = msg.code;
+            finish({ ok: false, error });
         });
         worker.once("error", (error) => {
             finish({ ok: false, error });
@@ -2620,19 +2702,20 @@ async function cmdSetup(flags) {
     else {
         await cmdLogin(flags);
     }
-    if (flags["with-hud"])
-        await cmdSetupHud(flags);
+    if (flags["with-hud"]) {
+        console.log("ℹ️  The standalone EchoMem HUD has been retired. Echo Desktop now owns setup and status.");
+    }
 }
 /**
  * `echomem-mcp init` — the one-command install. Configures EVERY coding agent installed on this
  * machine (Codex + Claude Code + Claude Desktop, not just auto-detected ones), installs EchoMem's
- * Codex skills, writes the AGENTS.md memory guidance, and launches the context HUD. One browser
+ * Codex skills and writes the AGENTS.md memory guidance. One browser
  * bridge then runs permission → report → login → plan if needed → extraction in that order.
  * `setup`/`login`/`update` remain granular primitives; init picks the full product defaults.
  */
 async function cmdInit(flags) {
-    console.log("Setting up EchoMem — shared memory for all your coding agents, plus the live context HUD.\n");
-    // 1. Configure every installed agent + write AGENTS.md. Hold login + HUD so we control ordering.
+    console.log("Setting up EchoMem — shared memory for all your coding agents.\n");
+    // 1. Configure every installed agent + write AGENTS.md. Hold login so we control ordering.
     await cmdSetup({
         ...flags,
         all: true,
@@ -2641,10 +2724,7 @@ async function cmdInit(flags) {
         "init-quiet": true,
         "install-save-hooks": flags["no-save-hooks"] !== true,
     });
-    // 2. Bring the HUD up NOW (non-blocking) so everything is already running while onboarding proceeds.
-    if (!flags["no-hud"])
-        await cmdSetupHud(flags);
-    // 3. Start one ordered onboarding bridge. A fresh device logs in only after consent + report.
+    // 2. Start one ordered onboarding bridge. A fresh device logs in only after consent + report.
     console.log("");
     if (!flags["skip-login"] && !flags["no-login"] && !await cmdOnboarding(flags)) {
         console.log("\nEchoMem is configured, but onboarding did not finish. Run `echomem-mcp init` again when you are ready.");
@@ -2653,13 +2733,7 @@ async function cmdInit(flags) {
     console.log("");
     console.log("🎉 EchoMem is ready.");
     console.log("   • MCP memory is configured for every coding agent installed on this machine.");
-    if (!flags["no-hud"]) {
-        console.log('   • The context HUD is running (top-right). Right-click it → "Show after restart" to keep it,');
-        console.log('     or just tell your agent "open the EchoMem HUD" anytime (it runs: echomem-hud app).');
-    }
-    else {
-        console.log('   • Start the context HUD anytime with: echomem-hud app');
-    }
+    console.log("   • Echo Desktop shows connection status and manages this device credential.");
     console.log('   • Try it now: ask your agent — "search my EchoMem for what I\'ve been working on and recap it."');
 }
 /**
@@ -2742,55 +2816,6 @@ function selectSetupTargets(requested, all) {
     }
     return requested ? knownClients().filter((client) => client.id === requested) : detectClients();
 }
-async function cmdSetupHud(flags) {
-    const client = parseHudClient(flags["hud-client"] || "auto");
-    const hudCli = resolveHudCliPath();
-    console.log("");
-    console.log(`✅ EchoMem HUD available: ${process.execPath} ${hudCli}`);
-    if (flags["install-hud-hooks"]) {
-        const paths = installHooks(client === "claude-desktop" ? "auto" : client);
-        console.log(`✅ Installed EchoMem HUD hook support:\n${paths.map((p) => `   - ${p}`).join("\n")}`);
-        console.log("   Codex users: run /hooks in a new Codex session to review and trust changed hooks.");
-    }
-    else {
-        console.log("ℹ️  HUD hooks not installed. Add --install-hud-hooks if you want lifecycle wakeups.");
-    }
-    if (!flags["no-launch-hud"]) {
-        try {
-            spawn(process.execPath, [hudCli, "app", "--client", client], { stdio: "ignore", detached: true }).unref();
-            console.log("✅ Launched EchoMem HUD app.");
-        }
-        catch {
-            console.log(`ℹ️  Could not auto-launch HUD. Run: echomem-hud app --client ${client}`);
-        }
-    }
-    else {
-        console.log(`Run the HUD later with: echomem-hud app --client ${client}`);
-    }
-}
-function resolveHudCliPath() {
-    const entry = fs.realpathSync(process.argv[1] || "");
-    const compiledEntry = compiledDistPathForSource(entry);
-    if (compiledEntry) {
-        const compiledHud = path.join(path.dirname(compiledEntry), "hud", "cli.js");
-        if (fs.existsSync(compiledHud))
-            return compiledHud;
-    }
-    const base = path.dirname(entry);
-    const candidate = path.join(base, "hud", "cli.js");
-    if (fs.existsSync(candidate))
-        return candidate;
-    const sourceCandidate = path.join(base, "hud", "cli.ts");
-    if (fs.existsSync(sourceCandidate)) {
-        throw new Error("The local HUD CLI is not built. Run npm --prefix packages/mcp-server run build and retry.");
-    }
-    return candidate;
-}
-function parseHudClient(value) {
-    return value === "codex" || value === "claude-code" || value === "claude-desktop" || value === "both" || value === "auto"
-        ? value
-        : "auto";
-}
 function localBridgeOptions(flags) {
     const port = typeof flags["dev-port"] === "string" ? Number(flags["dev-port"]) : undefined;
     if (port !== undefined && (!Number.isInteger(port) || port < 1024 || port > 65535)) {
@@ -3063,7 +3088,23 @@ async function cmdOnboarding(flags) {
             extracted: 0,
         });
     };
-    const refreshLocalStatsForToken = async (activeToken) => {
+    const publishOptionalStatsFallback = (generation, reason, countsTrusted) => {
+        if (generation !== refreshGeneration)
+            return;
+        stats = completeOptionalStatsPayload(stats, reason, countsTrusted);
+        srv.setStats(stats);
+        const pending = countsTrusted ? latestPendingEstimate : 0;
+        srv.setProgress({
+            status: "idle",
+            total: pending,
+            completed: 0,
+            running: 0,
+            queued: pending,
+            failed: 0,
+            extracted: 0,
+        });
+    };
+    const refreshLocalStatsForTokenCore = async (activeToken) => {
         const generation = ++refreshGeneration;
         lastProcessedImportKeys = null; // shared with /migrate so it can assemble only the pending sessions
         let importStatusUnavailable = false;
@@ -3268,15 +3309,31 @@ async function cmdOnboarding(flags) {
                     return;
                 stats = fullPayload;
                 srv.setStats(fullPayload);
-            })();
+            })().catch((e) => {
+                if (generation !== refreshGeneration)
+                    return;
+                console.error(`[echomem] optional full local-history stats unavailable; continuing (${errorCode(e) || "FULL_STATS_FAILED"})`);
+                publishOptionalStatsFallback(generation, "FULL_STATS_FAILED", true);
+            });
             return initialExact;
         }).catch((e) => {
             if (generation === refreshGeneration) {
-                console.error(`Could not finish exact local extraction estimate: ${e instanceof Error ? e.message : String(e)}`);
+                console.error(`[echomem] optional exact local-history discovery unavailable; continuing (${errorCode(e) || "EXACT_DISCOVERY_FAILED"})`);
+                publishOptionalStatsFallback(generation, "EXACT_DISCOVERY_FAILED", false);
             }
             return disc;
         });
     };
+    const refreshLocalStatsForToken = async (activeToken) => {
+        const expectedGeneration = refreshGeneration + 1;
+        try {
+            await refreshLocalStatsForTokenCore(activeToken);
+        }
+        catch (e) {
+            console.error(`[echomem] optional local-history stats unavailable; continuing (${errorCode(e) || "OPTIONAL_STATS_FAILED"})`);
+            publishOptionalStatsFallback(expectedGeneration, "OPTIONAL_STATS_FAILED", false);
+        }
+    };
     srv.setLogoutHandler(resetLocalLoginState);
     srv.setTokenRefreshHandler(async ({ token: nextToken, key: nextKey }) => {
         if (!await verifyAndPrint({ token: nextToken, key: nextKey }))
@@ -3712,14 +3769,13 @@ function cmdLogout() {
 const HELP = `EchoMem MCP — local memory bridge
 
 Usage:
-  echomem-mcp init                  One command: configure agents + HUD + login + local-history onboarding
+  echomem-mcp init                  Legacy/headless setup: configure agents + login + local-history onboarding
   echomem-mcp                       Run the MCP server (stdio; default — used by your editor)
   echomem-mcp setup [--client X]    Detect editor, write its MCP config, then connect this device
   echomem-mcp setup --skip-login    Write MCP config without opening login/browser
   echomem-mcp setup --no-codex-skills  Skip installing the bundled EchoMem Codex skills
   echomem-mcp update --all          Install this bridge durably + repoint detected clients; no login/browser
   echomem-mcp update --client X     Repoint one MCP client; no login/browser
-  echomem-mcp setup --with-hud      Configure MCP, then launch the EchoMem context HUD
   echomem-mcp login                 Connect this device only; never scans or imports local history
   echomem-mcp login --force         Reconnect this device with a different account
   echomem-mcp unlock                Privately unlock the vault on this trusted device
@@ -3742,7 +3798,6 @@ Manual / headless:
   ${MCP_UPDATE_ALL_COMMAND}     # one-shot latest update for detected clients, no browser login
   ${MCP_UPDATE_COMMAND} --client codex   # update one client only
   echomem-mcp setup --dev /abs/path/dist/index.js   # point clients at a local checkout
-  echomem-mcp setup --with-hud --install-hud-hooks --install-save-hooks --client codex [--hud-client auto]
   echomem-mcp setup --install-save-hooks --all  Install proactive private-save completion checks
   echomem-mcp sync-usage --days 7 --limit 50 --dry-run
 

package/dist/v1-contract.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { MEMORY_CITATION_INSTRUCTION, SAVED_MEMORY_RECEIPT_INSTRUCTION, withMcpVersion, } from "./package-metadata.js";
+import { MCP_DESKTOP_MANAGED, MCP_VAULT_UNLOCK_INSTRUCTION, MEMORY_CITATION_INSTRUCTION, SAVED_MEMORY_RECEIPT_INSTRUCTION, withMcpVersion, } from "./package-metadata.js";
 export const canonicalToolNames = {
     search: "search_memories",
     save: "save_conversation",
@@ -13,6 +13,7 @@ export const canonicalToolNames = {
     recordCitations: "record_memory_citations",
     groupContext: "get_group_context",
     getGroupSessionSharing: "get_group_session_sharing",
+    requestGroupSessionSharing: "request_group_session_sharing",
     setGroupSessionSharing: "set_group_session_sharing",
     createGroup: "create_memory_group",
     createGroupInvite: "create_group_invite",
@@ -38,6 +39,127 @@ export const legacyAliasToCanonical = {
 export function resolveCanonicalToolName(toolName) {
     return legacyAliasToCanonical[toolName] ?? toolName;
 }
+export const TOOL_DESCRIPTION_BYTE_LIMIT = 2_000;
+const READ_ONLY_TOOL_NAMES = new Set([
+    canonicalToolNames.search,
+    "search_memories_by_description_semantic",
+    canonicalToolNames.timeRange,
+    "search_memories_by_time_range",
+    canonicalToolNames.keywords,
+    canonicalToolNames.friends,
+    canonicalToolNames.searchUsers,
+    canonicalToolNames.others,
+    canonicalToolNames.publicMemory,
+    canonicalToolNames.groupContext,
+    canonicalToolNames.getGroupSessionSharing,
+    canonicalToolNames.getByContext,
+    canonicalToolNames.checkpointByContext,
+    canonicalToolNames.report,
+    canonicalToolNames.updateStatus,
+    canonicalToolNames.contextHealth,
+    canonicalToolNames.recompose,
+]);
+const IDEMPOTENT_WRITE_TOOL_NAMES = new Set([
+    canonicalToolNames.recordCitations,
+    canonicalToolNames.requestGroupSessionSharing,
+    canonicalToolNames.setGroupSessionSharing,
+    canonicalToolNames.updateGroupProfile,
+    canonicalToolNames.completeGroupPublication,
+    canonicalToolNames.publishToGroup,
+    canonicalToolNames.publishBatchToGroup,
+]);
+const REQUIRES_USER_INTERACTION_TOOL_NAMES = new Set([
+    canonicalToolNames.requestGroupSessionSharing,
+    canonicalToolNames.setGroupSessionSharing,
+    canonicalToolNames.flagPublicationAttention,
+    canonicalToolNames.updateGroupProfile,
+    canonicalToolNames.completeGroupPublication,
+    canonicalToolNames.publishToGroup,
+    canonicalToolNames.publishBatchToGroup,
+    canonicalToolNames.delete,
+]);
+const ALWAYS_LOAD_TOOL_NAMES = new Set([
+    canonicalToolNames.search,
+    canonicalToolNames.save,
+]);
+const LOCAL_ONLY_TOOL_NAMES = new Set([
+    canonicalToolNames.report,
+    canonicalToolNames.contextHealth,
+    canonicalToolNames.recompose,
+]);
+function truncateToByteBudget(value, limit) {
+    if (Buffer.byteLength(value, "utf8") <= limit)
+        return value;
+    const ellipsis = "…";
+    const contentBudget = limit - Buffer.byteLength(ellipsis, "utf8");
+    if (contentBudget <= 0)
+        return "";
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(value.slice(0, middle), "utf8") <= contentBudget)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    const safeEnd = low > 0
+        && /[\uD800-\uDBFF]/.test(value.charAt(low - 1))
+        && /[\uDC00-\uDFFF]/.test(value.charAt(low))
+        ? low - 1
+        : low;
+    const candidate = value.slice(0, safeEnd);
+    const boundary = Math.max(candidate.lastIndexOf("\n"), candidate.lastIndexOf(" "));
+    const body = boundary >= Math.floor(candidate.length * 0.8) ? candidate.slice(0, boundary) : candidate;
+    return `${body.trimEnd()}${ellipsis}`;
+}
+function boundToolDescription(description) {
+    if (Buffer.byteLength(description, "utf8") <= TOOL_DESCRIPTION_BYTE_LIMIT)
+        return description;
+    const versionMarker = "\n\nEchoMem MCP bridge:";
+    const versionIndex = description.lastIndexOf(versionMarker);
+    if (versionIndex < 0) {
+        return truncateToByteBudget(description, TOOL_DESCRIPTION_BYTE_LIMIT);
+    }
+    const suffix = description.slice(versionIndex + 2);
+    const separator = "\n\n";
+    const bodyLimit = TOOL_DESCRIPTION_BYTE_LIMIT
+        - Buffer.byteLength(suffix, "utf8")
+        - Buffer.byteLength(separator, "utf8");
+    if (bodyLimit <= 0)
+        return truncateToByteBudget(suffix, TOOL_DESCRIPTION_BYTE_LIMIT);
+    return `${truncateToByteBudget(description.slice(0, versionIndex), bodyLimit)}${separator}${suffix}`;
+}
+function compactGroupRoster(groupMap) {
+    const labels = groupMap
+        .split("\n")
+        .map((line) => line.trim().replace(/^-\s*/, ""))
+        .filter(Boolean)
+        .map((line) => line.split(/\s+—\s+/u, 1)[0] ?? line)
+        .map((label) => truncateToByteBudget(label, 48));
+    return labels.length ? `Team roster: ${labels.join("; ")}.` : "";
+}
+function decorateLocalToolSpec(tool) {
+    const readOnly = READ_ONLY_TOOL_NAMES.has(tool.name);
+    const decorated = {
+        ...tool,
+        description: boundToolDescription(tool.description),
+        annotations: {
+            readOnlyHint: readOnly,
+            destructiveHint: tool.name === canonicalToolNames.delete,
+            idempotentHint: readOnly || IDEMPOTENT_WRITE_TOOL_NAMES.has(tool.name),
+            openWorldHint: !LOCAL_ONLY_TOOL_NAMES.has(tool.name),
+        },
+    };
+    const meta = {};
+    if (ALWAYS_LOAD_TOOL_NAMES.has(tool.name)) {
+        meta["anthropic/alwaysLoad"] = true;
+    }
+    if (REQUIRES_USER_INTERACTION_TOOL_NAMES.has(tool.name)) {
+        meta["anthropic/requiresUserInteraction"] = true;
+    }
+    return Object.keys(meta).length > 0 ? { ...decorated, _meta: meta } : decorated;
+}
 const triggerMetadataSchema = {
     triggerMessage: z.string().optional(),
     triggerMessageRole: z.string().optional(),
@@ -129,6 +251,7 @@ export const getGroupSessionSharingSchema = z.object({
     groupSharingScopeId: z.string().uuid().optional(),
     groupId: z.string().uuid().optional(),
 });
+export const requestGroupSessionSharingSchema = getGroupSessionSharingSchema;
 export const setGroupSessionSharingSchema = z.object({
     ...triggerMetadataSchema,
     groupSharingScopeId: z.string().uuid(),
@@ -224,9 +347,9 @@ export function listToolSpecs(opts = {}) {
     // Same device as the personal map, aimed at the group surface: the agent judges whether teammates
     // have covered the topic before searching, instead of never calling the group tools at all.
     const groupMapSection = groupMap
-        ? `\n\nThis user's company group currently shares work in these areas (a relevance guide — search the group when the task relates to one of these people or topics):\n${groupMap}\n`
+        ? `\n\nThis user's company group currently shares work in these areas (a relevance guide — search the group when the task relates to one of these people or topics):\n${compactGroupRoster(groupMap)}\n${groupMap}\n`
         : "";
-    return [
+    const tools = [
         {
             name: canonicalToolNames.search,
             description: withMcpVersion(`Recall the user's prior decisions, preferences, and project context from EchoMem — their long-term memory across ALL their AI tools, not just this session. Use it instead of re-deriving or re-asking what the user already settled. ${recallPlanNote} ${searchBillingReplyInstruction} ${memoryCitationInstruction}${mapSection}\nReturns ranked memories only; the MCP host model writes the final answer. Current time: ${currentTime}.${updateSection}`),
@@ -265,7 +388,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.save,
-            description: `Save durable knowledge from this conversation into the user's private EchoMem (durable memories are extracted automatically). Call before the final response when work produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone; this private checkpoint does not require a separate user request. Omit secrets, incidental chatter, and trivial read-only work. If the encrypted vault is locked, tell the user to run \`echomem-mcp unlock\` and never silently skip a qualifying checkpoint. Private persistence happens first. For group sharing, reuse the exact groupSharingScopeId returned by get_group_session_sharing or an earlier save in this conversation. Never reuse it in another conversation or save it as memory. Each group has an independent decision under the same conversation scope; eligible memories sync automatically to every approved group, while flagged memories stay private. If a selected group has no decision yet, ask whether to share with that named group. Silence leaves it unset; never infer the answer. New extraction input uses the plan's weekly processing allowance; if the limit is reached, nothing is saved. passthrough=true stores the text verbatim as a session capsule. ${SAVED_MEMORY_RECEIPT_INSTRUCTION}`,
+            description: `Save durable knowledge from this conversation into the user's private EchoMem (durable memories are extracted automatically). Call before the final response when work produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone; this private checkpoint does not require a separate user request. Omit secrets, incidental chatter, and trivial read-only work. If the encrypted vault is locked, tell the user to ${MCP_VAULT_UNLOCK_INSTRUCTION} and never silently skip a qualifying checkpoint. Private persistence happens first. For group sharing, reuse the exact groupSharingScopeId returned by get_group_session_sharing, request_group_session_sharing, or an earlier save in this conversation. Never reuse it in another conversation or save it as memory. Each group has an independent decision under the same conversation scope; eligible memories sync automatically to every approved group, while flagged memories stay private. If a selected group has no decision yet, call request_group_session_sharing so supported hosts render a choice UI; its fallback tells you when a text Yes/No prompt is required. Silence leaves consent unset; never infer the answer. New extraction input uses the plan's weekly processing allowance; if the limit is reached, nothing is saved. passthrough=true stores the text verbatim as a session capsule. ${SAVED_MEMORY_RECEIPT_INSTRUCTION}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -513,7 +636,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.getGroupSessionSharing,
-            description: "Read the confirmed sharing decision for one group in this exact conversation. On the first call, omit groupSharingScopeId; EchoMem returns a new opaque scope. Reuse that scope only in this conversation. If the user belongs to multiple groups and groupId is omitted, EchoMem returns the available groups; call again with the same scope and one groupId at a time. Each group requires an independent explicit Yes/No decision. Silence leaves that group's state unset; never infer the answer.",
+            description: "Read the confirmed sharing decision for one group in this exact conversation. On the first call, omit groupSharingScopeId; EchoMem returns a new opaque scope. Reuse that scope only in this conversation. If the user belongs to multiple groups and groupId is omitted, EchoMem returns the available groups. If a decision is unset, call request_group_session_sharing with this scope and the selected groupId so supported hosts render a choice UI. Silence leaves that group's state unset; never infer the answer.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -532,6 +655,27 @@ export function listToolSpecs(opts = {}) {
                 },
             },
         },
+        {
+            name: canonicalToolNames.requestGroupSessionSharing,
+            description: "Check one group's sharing decision for this exact conversation and, only when it is unset, ask the user through the MCP client's native choice UI. Omit groupSharingScopeId only on the first call so EchoMem can mint a fresh scope; reuse the returned scope only in this conversation. When multiple groups are returned, call again with the same scope and one groupId at a time. An accepted Share choice backfills eligible private memories and syncs later saves; Keep private records No. Decline or cancel records nothing. If the client cannot render MCP elicitation, relay the returned fallback question and call set_group_session_sharing only after the user explicitly answers.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    groupSharingScopeId: {
+                        type: "string",
+                        format: "uuid",
+                        description: "Reuse the opaque scope returned in this conversation. Omit only on the first sharing check.",
+                    },
+                    groupId: {
+                        type: "string",
+                        format: "uuid",
+                        description: "Group to confirm. Required when the user belongs to multiple groups.",
+                    },
+                    triggerMessage: { type: "string" },
+                    triggerMessageRole: { type: "string", default: "user" },
+                },
+            },
+        },
         {
             name: canonicalToolNames.setGroupSessionSharing,
             description: "Store the user's explicit Yes/No sharing decision for one group in this exact conversation scope. Pass the exact groupSharingScopeId returned in this conversation and the selected groupId when the user belongs to multiple groups. EchoMem validates membership server-side. Decisions are independent per group: share=true backfills that group and later saves sync to every approved group; share=false keeps this conversation private for that group. Flagged memories remain private.",
@@ -574,7 +718,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.joinGroup,
-            description: "Join a company memory group using an invite code after the user explicitly asks to join. Joining never publishes memories. Next call prepare_group_publication, infer a proposed title and responsibility summary from the user's own candidate memories, and ask the user to confirm the profile together with the publication preview. Also call get_group_session_sharing without a scope to mint one for this conversation and, if unset, ask whether memories saved from this conversation should be shared. Silence stays unset and should be prompted again at a later qualifying checkpoint until an explicit Yes or No.",
+            description: "Join a company memory group using an invite code after the user explicitly asks to join. Joining never publishes memories. Next call prepare_group_publication, infer a proposed title and responsibility summary from the user's own candidate memories, and ask the user to confirm the profile together with the publication preview. Also call request_group_session_sharing without a scope so supported hosts render a native sharing choice. Decline or cancel stays unset and should be prompted again at a later qualifying checkpoint.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -765,11 +909,11 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.checkpointByContext,
-            description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. ${recallPlanNote} Use this when the user or EchoMem HUD gives you a contextId for a renewed coding session and you need the session handoff, not a raw memory dump. It deterministically fetches that context and formats it as orientation state: decisions, carryover, constraints, and checkpoints. ${memoryCitationInstruction} Current time: ${currentTime}.`),
+            description: withMcpVersion(`Rebuild a clean-context checkpoint / decision log from one EchoMem contextId. ${recallPlanNote} Use this when the user or EchoMem returns a contextId for a renewed coding session and you need the session handoff, not a raw memory dump. It deterministically fetches that context and formats it as orientation state: decisions, carryover, constraints, and checkpoints. ${memoryCitationInstruction} Current time: ${currentTime}.`),
             inputSchema: {
                 type: "object",
                 properties: {
-                    contextId: { type: "string", description: "The EchoMem contextId shown by the HUD or returned by save_conversation / Renew session." },
+                    contextId: { type: "string", description: "The EchoMem contextId returned by save_conversation or Renew session." },
                     limit: { type: "number", default: 100 },
                     triggerMessage: {
                         type: "string",
@@ -787,7 +931,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.updateStatus,
-            description: `Check whether this installed EchoMem MCP bridge is behind the latest published npm version. Works without login, uploads no user transcript, and normal background checks are cached so EchoMem does not hit npm on every startup. If it reports an update, tell the user and offer to run the returned update command; after updating, the user must start a new agent/MCP session.${updateSection}`,
+            description: `Check whether this installed EchoMem MCP bridge is behind the latest version. Works without login, uploads no user transcript, and normal background checks are cached. ${MCP_DESKTOP_MANAGED ? "Echo Desktop owns updates for this runtime; direct the user back to the desktop app." : "If it reports an update, tell the user and offer to run the returned update command."} After updating, the user must start a new agent/MCP session.${updateSection}`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -801,7 +945,7 @@ export function listToolSpecs(opts = {}) {
         },
         {
             name: canonicalToolNames.contextHealth,
-            description: "Show the current local Codex/Claude context-health score as markdown: clean percentage, tracked lower-bound dead-weight, redundant reads, source client, and token-count source. Use when the user asks about the context HUD, dirty context, context pollution, whether cleanup is worth it, or wants an in-chat fallback to the passive HUD. This reads local agent logs only and needs no login.",
+            description: "Show the current local Codex/Claude context-health score as markdown: clean percentage, tracked lower-bound dead-weight, redundant reads, source client, and token-count source. Use when the user asks about dirty context, context pollution, or whether cleanup is worth it. This on-demand tool reads local agent logs only and needs no login.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -841,4 +985,5 @@ export function listToolSpecs(opts = {}) {
             },
         },
     ];
+    return tools.map(decorateLocalToolSpec);
 }