@echomem/mcp 1.4.40 → 1.4.42

package/dist/index.js

@@ -4,18 +4,20 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import { ZodError } from "zod";
-import { canonicalToolNames, completeGroupPublicationSchema, createGroupInviteSchema, createGroupSchema, deleteMemorySchema, flagPublicationAttentionSchema, getGroupSessionSharingSchema, getByContextSchema, groupContextSchema, joinGroupSchema, keywordsSchema, listFriendsSchema, listToolSpecs, othersSchema, publishBatchToGroupSchema, publishToGroupSchema, prepareGroupPublicationSchema, publicMemorySchema, recordMemoryCitationsSchema, requestGroupSessionSharingSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, searchUsersSchema, sendFriendRequestSchema, timeRangeSchema, updateGroupProfileSchema, setGroupSessionSharingSchema, } from "./v1-contract.js";
+import { bindSourceSessionSchema, canonicalToolNames, completeGroupPublicationSchema, createGroupInviteSchema, createGroupSchema, deleteMemorySchema, flagPublicationAttentionSchema, getGroupSessionSharingSchema, getByContextSchema, groupContextSchema, joinGroupSchema, keywordsSchema, listFriendsSchema, listToolSpecs, othersSchema, publishBatchToGroupSchema, publishToGroupSchema, prepareGroupPublicationSchema, publicMemorySchema, recordMemoryCitationsSchema, requestGroupSessionSharingSchema, resolveCanonicalToolName, saveConversationSchema, searchMemoriesSchema, searchUsersSchema, sendFriendRequestSchema, timeRangeSchema, updateGroupProfileSchema, setGroupSessionSharingSchema, } from "./v1-contract.js";
 import { KeyStore } from "./keystore.js";
 import { EventLogger, hashText } from "./events.js";
 import { buildReportText } from "./report.js";
 import { contextHealthMarkdown, recomposeCapsuleMarkdown } from "./hud/api.js";
 import { createHash, randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { fetchEncryptionConfig, decryptMemoryFields, verifyKeyB64, } from "./encryption.js";
 import { runCli } from "./setup.js";
 import { MCP_PACKAGE_VERSION, MCP_SERVER_INSTRUCTIONS, MEMORY_CITATION_INSTRUCTION, SAVED_MEMORY_RECEIPT_INSTRUCTION, } from "./package-metadata.js";
 import { clearBillingAlert, writeBillingAlert } from "./billing-alert.js";
 import { checkLatestUpdateStatus, formatUpdateNotice, formatUpdateStatusText, startBackgroundUpdateCheck, } from "./update-check.js";
 import { autoUpdateHeadlessRuntime } from "./headless-runtime.js";
+import { resolveSourceSessionFromMcpContext, resolveSourceSessionFromBindingToken, } from "./source-session.js";
 const ECHO_API_BASE_URL = process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app";
 const ECHO_PRICING_URL = process.env.ECHO_PRICING_URL || "https://echoknows.com/account";
 const ECHO_MEMORY_WEB_URL = (process.env.ECHO_MEMORY_WEB_URL || "https://echoknows.com/memory").replace(/\/$/, "");
@@ -611,6 +613,9 @@ function toolEventName(canonicalName, status) {
 class EchoMemApiClient {
     store;
     axios;
+    boundSourceSession = null;
+    requestSourceSession = new AsyncLocalStorage();
+    sourceSessionsByCanonicalKey = new Map();
     whoamiCache = null;
     /** One id per bridge process — groups all saves from this coding session under a single EchoMem context. */
     sessionId = randomUUID();
@@ -630,6 +635,10 @@ class EchoMemApiClient {
             const token = this.store.getToken();
             if (token)
                 config.headers.set("Authorization", `Bearer ${token}`);
+            const sourceSession = this.getBoundSourceSession();
+            if (sourceSession) {
+                config.headers.set("X-EchoMem-Context-Id", sourceSession.contextId);
+            }
             return config;
         });
     }
@@ -641,6 +650,43 @@ class EchoMemApiClient {
     getSessionId() {
         return this.sessionId;
     }
+    getBoundSourceSession() {
+        return this.requestSourceSession.getStore() ?? this.boundSourceSession;
+    }
+    async withSourceSession(sourceSession, operation) {
+        return sourceSession ? this.requestSourceSession.run(sourceSession, operation) : operation();
+    }
+    async bindSourceSession(verified, persistForBridge = true) {
+        const cached = this.sourceSessionsByCanonicalKey.get(verified.canonicalKey);
+        if (cached) {
+            if (persistForBridge)
+                this.boundSourceSession = cached;
+            return { ...cached, created: false };
+        }
+        const response = await this.axios.post("/api/extension/source-sessions/bind", {
+            provider: verified.provider,
+            providerSessionId: verified.providerSessionId,
+            evidence: verified.evidence,
+        });
+        const contextId = readString(response.data, "contextId");
+        const canonicalKey = readString(response.data, "canonicalKey");
+        if (response.data?.success !== true || !contextId || canonicalKey !== verified.canonicalKey) {
+            throw new Error("EchoMem returned an invalid source-session binding receipt");
+        }
+        const bound = { ...verified, contextId };
+        this.sourceSessionsByCanonicalKey.set(verified.canonicalKey, bound);
+        if (this.sourceSessionsByCanonicalKey.size > 64) {
+            const oldestKey = this.sourceSessionsByCanonicalKey.keys().next().value;
+            if (oldestKey)
+                this.sourceSessionsByCanonicalKey.delete(oldestKey);
+        }
+        if (persistForBridge)
+            this.boundSourceSession = bound;
+        return {
+            ...bound,
+            created: response.data?.created === true,
+        };
+    }
     async trackMcpAnalyticsEvent(eventType, eventProperties, insertId) {
         if (!this.hasToken())
             return;
@@ -900,9 +946,10 @@ class EchoMemApiClient {
                 sourceUrl: parsed.url,
                 source: parsed.source || "mcp_server",
                 title: parsed.title,
-                // The MCP transport can outlive a host conversation. Group saves only by the opaque
-                // scope carried in that conversation, never by the bridge process id.
-                conversationKey: groupSharingScopeId,
+                // A verified source session owns the memory context. The independent opaque scope still
+                // governs group-sharing consent and never becomes the source-session identity.
+                conversationKey: this.getBoundSourceSession()?.canonicalKey ?? groupSharingScopeId,
+                groupSharingScopeId,
                 passthrough: parsed.passthrough || false,
                 triggerMessage: parsed.triggerMessage ||
                     lastUserMessageFromMessages(parsed.messages) ||
@@ -1049,6 +1096,8 @@ class EchoMemApiClient {
                 kPerUser: parsed.kPerUser,
                 similarityThreshold: parsed.similarityThreshold,
                 timeFrameDays: parsed.timeFrameDays,
+                workspaceId: parsed.workspaceId ?? parsed.groupId,
+                scope: parsed.scope,
                 requestId: this.sessionId,
                 source: "mcp_friend_public_memory_search",
             });
@@ -1061,7 +1110,14 @@ class EchoMemApiClient {
     async getPublicMemory(args) {
         const parsed = publicMemorySchema.parse(args ?? {});
         try {
-            const response = await this.axios.get(`/api/extension/social/public-memories/${encodeURIComponent(parsed.memoryId)}?requestId=${encodeURIComponent(this.sessionId)}&source=mcp_friend_public_memory_fetch`);
+            const workspaceId = parsed.workspaceId ?? parsed.groupId;
+            const query = new URLSearchParams({
+                requestId: this.sessionId,
+                source: "mcp_friend_public_memory_fetch",
+            });
+            if (workspaceId)
+                query.set("workspaceId", workspaceId);
+            const response = await this.axios.get(`/api/extension/social/public-memories/${encodeURIComponent(parsed.memoryId)}?${query.toString()}`);
             return response.data;
         }
         catch (error) {
@@ -1084,9 +1140,13 @@ class EchoMemApiClient {
         }
     }
     async getGroupContext(args) {
-        groupContextSchema.parse(args ?? {});
+        const parsed = groupContextSchema.parse(args ?? {});
         try {
-            const response = await this.axios.get("/api/extension/social/groups/current");
+            const workspaceId = parsed.workspaceId ?? parsed.groupId;
+            const path = workspaceId
+                ? `/api/extension/social/groups/current?workspaceId=${encodeURIComponent(workspaceId)}`
+                : "/api/extension/social/groups/current";
+            const response = await this.axios.get(path);
             return response.data;
         }
         catch (error) {
@@ -1150,6 +1210,7 @@ class EchoMemApiClient {
         const enc = await this.encState();
         try {
             const response = await this.axios.post(`/api/extension/social/groups/current/memories/${encodeURIComponent(parsed.memoryId)}/publish`, {
+                workspaceId: parsed.workspaceId ?? parsed.groupId,
                 acknowledgedFlaggedMemoryIds: parsed.acknowledgedFlaggedMemoryIds,
             }, {
                 headers: enc.enabled && enc.key ? { "X-Encryption-Key": enc.key } : undefined,
@@ -1165,6 +1226,7 @@ class EchoMemApiClient {
         const enc = await this.encState();
         try {
             const response = await this.axios.post("/api/extension/social/groups/current/memories/publish-batch", {
+                workspaceId: parsed.workspaceId ?? parsed.groupId,
                 memoryIds: parsed.memoryIds,
                 contextId: parsed.contextId,
                 selectionReason: parsed.selectionReason,
@@ -1297,7 +1359,7 @@ class EchoMemMCPServer {
             const updateNotice = DESKTOP_MANAGED ? undefined : formatUpdateNotice(this.updateStatus);
             return { tools: listToolSpecs({ map, groupMap, updateNotice }) };
         });
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             const resolvedCanonicalName = resolveCanonicalToolName(request.params.name);
             const recallRoute = routePersonalRecallInvocation(resolvedCanonicalName, request.params.arguments);
             const canonicalName = recallRoute.canonicalName;
@@ -1307,258 +1369,277 @@ class EchoMemMCPServer {
             const clientVersion = this.server.getClientVersion();
             this.mcpClientName = clientVersion?.name ?? this.mcpClientName;
             this.mcpClientVersion = clientVersion?.version ?? this.mcpClientVersion;
-            const t0 = Date.now();
-            const analyticsBase = {
-                surface: "mcp",
-                event_family: "mcp",
-                integration: "echomem_mcp",
-                telemetry_source: "local_bridge",
-                ...this.getMcpClientAnalytics(),
-                codex_session_id: this.client.getSessionId(),
-                conversation_id: this.client.getSessionId(),
-                tool_name: request.params.name,
-                canonical_tool_name: canonicalName,
-                ...triggerAnalyticsForTool(canonicalName, toolArgs),
-                ...inputAnalyticsForTool(canonicalName, toolArgs),
-            };
-            const analyticsCallId = randomUUID();
-            // One event per call. Handlers enrich `rec` with tool-specific detail; we finalize + log in `finally`.
-            const rec = {
-                type: "tool_call",
-                tool: canonicalName,
-                map_injected: this.mapInjected,
-                group_map_injected: this.groupMapInjected,
-            };
+            let requestSourceSession = this.client.getBoundSourceSession();
+            let inferred = null;
             try {
-                if (recallRoute.error) {
-                    throw new McpError(ErrorCode.InvalidParams, recallRoute.error);
-                }
-                // The usage report is a local, $0 audit — works with no login (value before signup).
-                if (canonicalName === canonicalToolNames.report) {
-                    return { content: [{ type: "text", text: await buildReportText(false) }] };
+                inferred = resolveSourceSessionFromMcpContext(extra._meta, { hostPlatform: this.getMcpClientAnalytics().host_platform });
+            }
+            catch {
+                // Malformed host metadata is not model input. Ignore it and retain the explicit fallback.
+            }
+            // Verified request metadata always wins over a bridge-level compatibility fallback. The
+            // startup hook performs the eager write; this path attaches the exact context to the current
+            // request and retries the backend write if startup raced login.
+            if (inferred && this.client.hasToken()) {
+                requestSourceSession = await this.client.bindSourceSession(inferred, false);
+            }
+            return this.client.withSourceSession(requestSourceSession, async () => {
+                const t0 = Date.now();
+                const analyticsBase = {
+                    surface: "mcp",
+                    event_family: "mcp",
+                    integration: "echomem_mcp",
+                    telemetry_source: "local_bridge",
+                    ...this.getMcpClientAnalytics(),
+                    codex_session_id: this.client.getBoundSourceSession()?.canonicalKey ?? this.client.getSessionId(),
+                    conversation_id: this.client.getBoundSourceSession()?.canonicalKey ?? this.client.getSessionId(),
+                    context_id: this.client.getBoundSourceSession()?.contextId,
+                    tool_name: request.params.name,
+                    canonical_tool_name: canonicalName,
+                    ...triggerAnalyticsForTool(canonicalName, toolArgs),
+                    ...inputAnalyticsForTool(canonicalName, toolArgs),
+                };
+                const analyticsCallId = randomUUID();
+                // One event per call. Handlers enrich `rec` with tool-specific detail; we finalize + log in `finally`.
+                const rec = {
+                    type: "tool_call",
+                    tool: canonicalName,
+                    map_injected: this.mapInjected,
+                    group_map_injected: this.groupMapInjected,
+                };
+                try {
+                    if (recallRoute.error) {
+                        throw new McpError(ErrorCode.InvalidParams, recallRoute.error);
+                    }
+                    // The usage report is a local, $0 audit — works with no login (value before signup).
+                    if (canonicalName === canonicalToolNames.report) {
+                        return { content: [{ type: "text", text: await buildReportText(false) }] };
+                    }
+                    if (canonicalName === canonicalToolNames.updateStatus) {
+                        if (DESKTOP_MANAGED) {
+                            return {
+                                content: [{
+                                        type: "text",
+                                        text: `Echo Desktop manages this MCP runtime (${MCP_PACKAGE_VERSION}). Install app updates from Echo Desktop, then start a new agent session.`,
+                                    }],
+                            };
+                        }
+                        const force = isRecord(request.params.arguments) && request.params.arguments.force === true;
+                        const status = await checkLatestUpdateStatus({ force });
+                        this.handleUpdateStatus(status);
+                        return { content: [{ type: "text", text: formatUpdateStatusText(this.updateStatus ?? status) }] };
+                    }
+                    if (canonicalName === canonicalToolNames.contextHealth) {
+                        const client = isRecord(request.params.arguments) && typeof request.params.arguments.client === "string"
+                            ? request.params.arguments.client
+                            : "auto";
+                        const mode = client === "codex" || client === "claude-code" || client === "claude-desktop" || client === "auto"
+                            ? client
+                            : "auto";
+                        return { content: [{ type: "text", text: await contextHealthMarkdown(mode) }] };
+                    }
+                    if (canonicalName === canonicalToolNames.recompose) {
+                        const client = isRecord(request.params.arguments) && typeof request.params.arguments.client === "string"
+                            ? request.params.arguments.client
+                            : "auto";
+                        const mode = client === "codex" || client === "claude-code" || client === "claude-desktop" || client === "auto"
+                            ? client
+                            : "auto";
+                        const capsuleText = await recomposeCapsuleMarkdown(mode);
+                        // If logged in, persist the capsule via passthrough so it's retrievable by contextId.
+                        if (this.client.hasToken()) {
+                            try {
+                                const saveResult = await this.client.saveConversation({
+                                    conversation: capsuleText,
+                                    title: "Session capsule (recompose)",
+                                    source: "mcp_recompose",
+                                    passthrough: true,
+                                });
+                                const ctxId = saveResult?.contextId;
+                                const capId = saveResult?.capsuleId;
+                                const persistLine = ctxId
+                                    ? `\n\n---\nCapsule persisted${capId ? ` (${capId})` : ""}. To reload in a fresh session:\nget_memories_by_context({ contextId: "${ctxId}" })`
+                                    : "";
+                                return { content: [{ type: "text", text: capsuleText + persistLine }] };
+                            }
+                            catch {
+                                // Persistence is best-effort; return the capsule text regardless.
+                            }
+                        }
+                        return { content: [{ type: "text", text: capsuleText }] };
+                    }
+                    if (!this.client.hasToken())
+                        throw new NoTokenError();
+                    if (canonicalName !== canonicalToolNames.save) {
+                        void this.client.trackMcpAnalyticsEvent("[MCP] EchoMem Tool Called", analyticsBase, `${analyticsCallId}:generic-called`);
+                        void this.client.trackMcpAnalyticsEvent(toolEventName(canonicalName, "Called"), analyticsBase, `${analyticsCallId}:called`);
+                    }
+                    if (canonicalName !== canonicalToolNames.save && analyticsBase.trigger_message_available === true) {
+                        void this.client.trackMcpAnalyticsEvent("[MCP] EchoMem Triggered By User Turn", analyticsBase);
+                    }
+                    switch (canonicalName) {
+                        case canonicalToolNames.bindSourceSession:
+                            return await this.handleBindSourceSession(request.params.arguments);
+                        case canonicalToolNames.search:
+                            return await this.handleSearch(toolArgs, rec);
+                        case canonicalToolNames.save:
+                            return await this.handleSave(request.params.arguments, rec);
+                        case canonicalToolNames.timeRange:
+                            return await this.handleTimeRange(toolArgs);
+                        case canonicalToolNames.getByContext:
+                            return await this.handleGetByContext(request.params.arguments);
+                        case canonicalToolNames.checkpointByContext:
+                            return await this.handleGetCheckpointByContext(request.params.arguments);
+                        case canonicalToolNames.keywords:
+                            return await this.handleKeywords(toolArgs);
+                        case canonicalToolNames.friends:
+                            return await this.handleFriends(request.params.arguments);
+                        case canonicalToolNames.searchUsers:
+                            return await this.handleSearchUsers(request.params.arguments);
+                        case canonicalToolNames.sendFriendRequest:
+                            return await this.handleSendFriendRequest(request.params.arguments);
+                        case canonicalToolNames.others:
+                            return await this.handleOthers(toolArgs);
+                        case canonicalToolNames.publicMemory:
+                            return await this.handlePublicMemory(request.params.arguments);
+                        case canonicalToolNames.recordCitations:
+                            return await this.handleRecordMemoryCitations(request.params.arguments);
+                        case canonicalToolNames.groupContext:
+                            return await this.handleGroupContext(request.params.arguments);
+                        case canonicalToolNames.getGroupSessionSharing:
+                            return await this.handleGetGroupSessionSharing(request.params.arguments);
+                        case canonicalToolNames.requestGroupSessionSharing:
+                            return await this.handleRequestGroupSessionSharing(request.params.arguments);
+                        case canonicalToolNames.setGroupSessionSharing:
+                            return await this.handleSetGroupSessionSharing(request.params.arguments);
+                        case canonicalToolNames.createGroup:
+                            return await this.handleCreateGroup(request.params.arguments);
+                        case canonicalToolNames.createGroupInvite:
+                            return await this.handleCreateGroupInvite(request.params.arguments);
+                        case canonicalToolNames.joinGroup:
+                            return await this.handleJoinGroup(request.params.arguments);
+                        case canonicalToolNames.prepareGroupPublication:
+                            return await this.handlePrepareGroupPublication(request.params.arguments);
+                        case canonicalToolNames.flagPublicationAttention:
+                            return await this.handleFlagPublicationAttention(request.params.arguments);
+                        case canonicalToolNames.updateGroupProfile:
+                            return await this.handleUpdateGroupProfile(request.params.arguments);
+                        case canonicalToolNames.completeGroupPublication:
+                            return await this.handleCompleteGroupPublication(request.params.arguments);
+                        case canonicalToolNames.publishToGroup:
+                            return await this.handlePublishToGroup(request.params.arguments);
+                        case canonicalToolNames.publishBatchToGroup:
+                            return await this.handlePublishBatchToGroup(request.params.arguments);
+                        case canonicalToolNames.delete:
+                            return await this.handleDelete(request.params.arguments, rec);
+                        default:
+                            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+                    }
                 }
-                if (canonicalName === canonicalToolNames.updateStatus) {
-                    if (DESKTOP_MANAGED) {
+                catch (error) {
+                    rec.error_kind = classifyError(error);
+                    if (error instanceof NoTokenError) {
+                        // Not isError: a normal "not connected yet" state. Once `login` runs, the next call works.
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `🔌 EchoMem isn't connected yet. ${CONNECT_DEVICE_INSTRUCTION} No editor restart is needed.`,
+                                },
+                            ],
+                        };
+                    }
+                    if (error instanceof LockedError) {
+                        // Not isError: this is a normal "needs unlock" state the model should relay to the user.
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: [
+                                        "🔒 EchoMem vault is locked.",
+                                        "This encrypted account has no usable local decryption key. Once unlocked, this trusted device stays unlocked until you explicitly lock it or log out.",
+                                        `Action required from the user: ${UNLOCK_VAULT_INSTRUCTION}`,
+                                        ...(DESKTOP_MANAGED ? [] : [
+                                            "At `Vault passphrase (typing is hidden):`, type the passphrase and press Return. No characters will appear while you type; that is expected.",
+                                        ]),
+                                        "After the success message, retry this EchoMem action in the current session — no editor restart is needed.",
+                                    ].join("\n"),
+                                },
+                            ],
+                        };
+                    }
+                    if (error instanceof EncryptionStatusUnavailableError) {
                         return {
                             content: [{
                                     type: "text",
-                                    text: `Echo Desktop manages this MCP runtime (${MCP_PACKAGE_VERSION}). Install app updates from Echo Desktop, then start a new agent session.`,
+                                    text: [
+                                        "⚠️ EchoMem could not verify whether this account's vault is encrypted.",
+                                        "No memory data was returned. Retry this action after the service recovers.",
+                                    ].join("\n"),
                                 }],
+                            isError: true,
                         };
                     }
-                    const force = isRecord(request.params.arguments) && request.params.arguments.force === true;
-                    const status = await checkLatestUpdateStatus({ force });
-                    this.handleUpdateStatus(status);
-                    return { content: [{ type: "text", text: formatUpdateStatusText(this.updateStatus ?? status) }] };
-                }
-                if (canonicalName === canonicalToolNames.contextHealth) {
-                    const client = isRecord(request.params.arguments) && typeof request.params.arguments.client === "string"
-                        ? request.params.arguments.client
-                        : "auto";
-                    const mode = client === "codex" || client === "claude-code" || client === "claude-desktop" || client === "auto"
-                        ? client
-                        : "auto";
-                    return { content: [{ type: "text", text: await contextHealthMarkdown(mode) }] };
-                }
-                if (canonicalName === canonicalToolNames.recompose) {
-                    const client = isRecord(request.params.arguments) && typeof request.params.arguments.client === "string"
-                        ? request.params.arguments.client
-                        : "auto";
-                    const mode = client === "codex" || client === "claude-code" || client === "claude-desktop" || client === "auto"
-                        ? client
-                        : "auto";
-                    const capsuleText = await recomposeCapsuleMarkdown(mode);
-                    // If logged in, persist the capsule via passthrough so it's retrievable by contextId.
-                    if (this.client.hasToken()) {
-                        try {
-                            const saveResult = await this.client.saveConversation({
-                                conversation: capsuleText,
-                                title: "Session capsule (recompose)",
-                                source: "mcp_recompose",
-                                passthrough: true,
-                            });
-                            const ctxId = saveResult?.contextId;
-                            const capId = saveResult?.capsuleId;
-                            const persistLine = ctxId
-                                ? `\n\n---\nCapsule persisted${capId ? ` (${capId})` : ""}. To reload in a fresh session:\nget_memories_by_context({ contextId: "${ctxId}" })`
-                                : "";
-                            return { content: [{ type: "text", text: capsuleText + persistLine }] };
-                        }
-                        catch {
-                            // Persistence is best-effort; return the capsule text regardless.
-                        }
+                    if (error instanceof ZodError) {
+                        throw new McpError(ErrorCode.InvalidParams, `Invalid arguments: ${error.message}`);
+                    }
+                    if (error instanceof McpError) {
+                        throw error;
+                    }
+                    const reconnectRequired = formatReconnectRequiredResult(error);
+                    if (reconnectRequired) {
+                        return {
+                            content: [{ type: "text", text: reconnectRequired }],
+                            isError: true,
+                        };
+                    }
+                    const upgradeRequired = formatUpgradeRequiredResult(error);
+                    if (upgradeRequired) {
+                        return {
+                            content: [{ type: "text", text: upgradeRequired }],
+                        };
                     }
-                    return { content: [{ type: "text", text: capsuleText }] };
-                }
-                if (!this.client.hasToken())
-                    throw new NoTokenError();
-                if (canonicalName !== canonicalToolNames.save) {
-                    void this.client.trackMcpAnalyticsEvent("[MCP] EchoMem Tool Called", analyticsBase, `${analyticsCallId}:generic-called`);
-                    void this.client.trackMcpAnalyticsEvent(toolEventName(canonicalName, "Called"), analyticsBase, `${analyticsCallId}:called`);
-                }
-                if (canonicalName !== canonicalToolNames.save && analyticsBase.trigger_message_available === true) {
-                    void this.client.trackMcpAnalyticsEvent("[MCP] EchoMem Triggered By User Turn", analyticsBase);
-                }
-                switch (canonicalName) {
-                    case canonicalToolNames.search:
-                        return await this.handleSearch(toolArgs, rec);
-                    case canonicalToolNames.save:
-                        return await this.handleSave(request.params.arguments, rec);
-                    case canonicalToolNames.timeRange:
-                        return await this.handleTimeRange(toolArgs);
-                    case canonicalToolNames.getByContext:
-                        return await this.handleGetByContext(request.params.arguments);
-                    case canonicalToolNames.checkpointByContext:
-                        return await this.handleGetCheckpointByContext(request.params.arguments);
-                    case canonicalToolNames.keywords:
-                        return await this.handleKeywords(toolArgs);
-                    case canonicalToolNames.friends:
-                        return await this.handleFriends(request.params.arguments);
-                    case canonicalToolNames.searchUsers:
-                        return await this.handleSearchUsers(request.params.arguments);
-                    case canonicalToolNames.sendFriendRequest:
-                        return await this.handleSendFriendRequest(request.params.arguments);
-                    case canonicalToolNames.others:
-                        return await this.handleOthers(toolArgs);
-                    case canonicalToolNames.publicMemory:
-                        return await this.handlePublicMemory(request.params.arguments);
-                    case canonicalToolNames.recordCitations:
-                        return await this.handleRecordMemoryCitations(request.params.arguments);
-                    case canonicalToolNames.groupContext:
-                        return await this.handleGroupContext(request.params.arguments);
-                    case canonicalToolNames.getGroupSessionSharing:
-                        return await this.handleGetGroupSessionSharing(request.params.arguments);
-                    case canonicalToolNames.requestGroupSessionSharing:
-                        return await this.handleRequestGroupSessionSharing(request.params.arguments);
-                    case canonicalToolNames.setGroupSessionSharing:
-                        return await this.handleSetGroupSessionSharing(request.params.arguments);
-                    case canonicalToolNames.createGroup:
-                        return await this.handleCreateGroup(request.params.arguments);
-                    case canonicalToolNames.createGroupInvite:
-                        return await this.handleCreateGroupInvite(request.params.arguments);
-                    case canonicalToolNames.joinGroup:
-                        return await this.handleJoinGroup(request.params.arguments);
-                    case canonicalToolNames.prepareGroupPublication:
-                        return await this.handlePrepareGroupPublication(request.params.arguments);
-                    case canonicalToolNames.flagPublicationAttention:
-                        return await this.handleFlagPublicationAttention(request.params.arguments);
-                    case canonicalToolNames.updateGroupProfile:
-                        return await this.handleUpdateGroupProfile(request.params.arguments);
-                    case canonicalToolNames.completeGroupPublication:
-                        return await this.handleCompleteGroupPublication(request.params.arguments);
-                    case canonicalToolNames.publishToGroup:
-                        return await this.handlePublishToGroup(request.params.arguments);
-                    case canonicalToolNames.publishBatchToGroup:
-                        return await this.handlePublishBatchToGroup(request.params.arguments);
-                    case canonicalToolNames.delete:
-                        return await this.handleDelete(request.params.arguments, rec);
-                    default:
-                        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
-                }
-            }
-            catch (error) {
-                rec.error_kind = classifyError(error);
-                if (error instanceof NoTokenError) {
-                    // Not isError: a normal "not connected yet" state. Once `login` runs, the next call works.
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `🔌 EchoMem isn't connected yet. ${CONNECT_DEVICE_INSTRUCTION} No editor restart is needed.`,
-                            },
-                        ],
-                    };
-                }
-                if (error instanceof LockedError) {
-                    // Not isError: this is a normal "needs unlock" state the model should relay to the user.
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: [
-                                    "🔒 EchoMem vault is locked.",
-                                    "This encrypted account has no usable local decryption key. Once unlocked, this trusted device stays unlocked until you explicitly lock it or log out.",
-                                    `Action required from the user: ${UNLOCK_VAULT_INSTRUCTION}`,
-                                    ...(DESKTOP_MANAGED ? [] : [
-                                        "At `Vault passphrase (typing is hidden):`, type the passphrase and press Return. No characters will appear while you type; that is expected.",
-                                    ]),
-                                    "After the success message, retry this EchoMem action in the current session — no editor restart is needed.",
-                                ].join("\n"),
-                            },
-                        ],
-                    };
-                }
-                if (error instanceof EncryptionStatusUnavailableError) {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: [
-                                    "⚠️ EchoMem could not verify whether this account's vault is encrypted.",
-                                    "No memory data was returned. Retry this action after the service recovers.",
-                                ].join("\n"),
-                            }],
-                        isError: true,
-                    };
-                }
-                if (error instanceof ZodError) {
-                    throw new McpError(ErrorCode.InvalidParams, `Invalid arguments: ${error.message}`);
-                }
-                if (error instanceof McpError) {
-                    throw error;
-                }
-                const reconnectRequired = formatReconnectRequiredResult(error);
-                if (reconnectRequired) {
                     return {
-                        content: [{ type: "text", text: reconnectRequired }],
+                        content: [{ type: "text", text: `Error: ${describeError(error)}` }],
                         isError: true,
                     };
                 }
-                const upgradeRequired = formatUpgradeRequiredResult(error);
-                if (upgradeRequired) {
-                    return {
-                        content: [{ type: "text", text: upgradeRequired }],
-                    };
-                }
-                return {
-                    content: [{ type: "text", text: `Error: ${describeError(error)}` }],
-                    isError: true,
-                };
-            }
-            finally {
-                if (!rec.error_kind)
-                    rec.error_kind = "none";
-                rec.ok = rec.error_kind === "none";
-                rec.latency_ms = Date.now() - t0;
-                this.events.record(rec);
-                if (canonicalName !== canonicalToolNames.report &&
-                    canonicalName !== canonicalToolNames.updateStatus &&
-                    canonicalName !== canonicalToolNames.contextHealth &&
-                    canonicalName !== canonicalToolNames.recompose &&
-                    canonicalName !== canonicalToolNames.save &&
-                    this.client.hasToken()) {
-                    const finalAnalytics = {
-                        ...analyticsBase,
-                        success: rec.ok,
-                        duration_ms: rec.latency_ms,
-                        error_type: rec.error_kind === "none" ? undefined : rec.error_kind,
-                        result_count: rec.results_count,
-                        returned_text_length: rec.results_chars,
-                        tuned: rec.tuned,
-                        map_injected: rec.map_injected,
-                        encrypted_user: rec.encrypted,
-                        extracted_memory_count: rec.memories_extracted,
-                        // Preserve only the safe correlation fields needed to join a
-                        // bridge-local failure to the central operational trace. Query
-                        // text and upstream bodies never leave the local event stream.
-                        request_id: rec.request_id,
-                        endpoint: rec.endpoint,
-                        http_status: rec.http_status,
-                        error_code: rec.error_code ?? (rec.error_kind === "none" ? undefined : rec.error_kind),
-                    };
-                    void this.client.trackMcpAnalyticsEvent(rec.ok ? "[MCP] EchoMem Tool Succeeded" : "[MCP] EchoMem Tool Failed", finalAnalytics, `${analyticsCallId}:generic-completed`);
-                    void this.client.trackMcpAnalyticsEvent(toolEventName(canonicalName, rec.ok ? "Succeeded" : "Failed"), finalAnalytics, `${analyticsCallId}:completed`);
+                finally {
+                    if (!rec.error_kind)
+                        rec.error_kind = "none";
+                    rec.ok = rec.error_kind === "none";
+                    rec.latency_ms = Date.now() - t0;
+                    this.events.record(rec);
+                    if (canonicalName !== canonicalToolNames.report &&
+                        canonicalName !== canonicalToolNames.updateStatus &&
+                        canonicalName !== canonicalToolNames.contextHealth &&
+                        canonicalName !== canonicalToolNames.recompose &&
+                        canonicalName !== canonicalToolNames.save &&
+                        this.client.hasToken()) {
+                        const finalAnalytics = {
+                            ...analyticsBase,
+                            success: rec.ok,
+                            duration_ms: rec.latency_ms,
+                            error_type: rec.error_kind === "none" ? undefined : rec.error_kind,
+                            result_count: rec.results_count,
+                            returned_text_length: rec.results_chars,
+                            tuned: rec.tuned,
+                            map_injected: rec.map_injected,
+                            encrypted_user: rec.encrypted,
+                            extracted_memory_count: rec.memories_extracted,
+                            // Preserve only the safe correlation fields needed to join a
+                            // bridge-local failure to the central operational trace. Query
+                            // text and upstream bodies never leave the local event stream.
+                            request_id: rec.request_id,
+                            endpoint: rec.endpoint,
+                            http_status: rec.http_status,
+                            error_code: rec.error_code ?? (rec.error_kind === "none" ? undefined : rec.error_kind),
+                        };
+                        void this.client.trackMcpAnalyticsEvent(rec.ok ? "[MCP] EchoMem Tool Succeeded" : "[MCP] EchoMem Tool Failed", finalAnalytics, `${analyticsCallId}:generic-completed`);
+                        void this.client.trackMcpAnalyticsEvent(toolEventName(canonicalName, rec.ok ? "Succeeded" : "Failed"), finalAnalytics, `${analyticsCallId}:completed`);
+                    }
                 }
-            }
+            });
         });
     }
     async handleSearch(args, rec) {
@@ -1771,6 +1852,24 @@ Details: ${m.details || "N/A"}`)
         ].filter(Boolean).join("\n\n");
         return { content: [{ type: "text", text }] };
     }
+    async handleBindSourceSession(args) {
+        const parsed = bindSourceSessionSchema.parse(args ?? {});
+        const verified = resolveSourceSessionFromBindingToken(parsed.bindingToken, {
+            hostPlatform: this.getMcpClientAnalytics().host_platform,
+        });
+        const bound = await this.client.bindSourceSession(verified);
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        bound.created ? "Created and bound the source-session context." : "Source-session context is bound.",
+                        `Context: ${bound.contextId}`,
+                        `Source session: ${bound.canonicalKey}`,
+                        "Later EchoMem saves, recalls, citations, sharing decisions, and activity from this bridge will use this context automatically.",
+                    ].join("\n"),
+                }],
+        };
+    }
     async handleTimeRange(args) {
         const parsed = timeRangeSchema.parse(args ?? {});
         const { success, memories, error } = await this.client.getMemoriesByTimeRange(args);
@@ -1911,6 +2010,28 @@ Details: ${m.details || "N/A"}`)
     async handleOthers(args) {
         const parsed = othersSchema.parse(args ?? {});
         const payload = await this.client.searchOthersMemories(args);
+        if (payload?.requiresWorkspaceSelection === true) {
+            const availableWorkspaces = Array.isArray(payload?.availableWorkspaces)
+                ? payload.availableWorkspaces.filter(isRecord)
+                : [];
+            const choices = availableWorkspaces
+                .map((workspace) => `${readString(workspace, "name") ?? "Unnamed workspace"} (${readString(workspace, "id") ?? "unknown id"})`)
+                .join(", ");
+            return {
+                content: [{
+                        type: "text",
+                        text: `You belong to ${availableWorkspaces.length} workspaces: ${choices}. Ask the user which workspace's teammates to search, then call search_others_memories again with workspaceId set to one of those ids. (To search a specific friend instead, pass that person as target.)`,
+                    }],
+            };
+        }
+        if (payload?.groupScopeUnavailable === true) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "You are not in a company workspace, so there are no teammates to search. To search friends instead, call search_others_memories again with scope \"friends\", or pass a specific person as target.",
+                    }],
+            };
+        }
         const memories = payload?.memories ?? [];
         const authenticatedViewer = isRecord(payload?.authenticatedViewer)
             ? payload.authenticatedViewer
@@ -2132,6 +2253,20 @@ Details: ${m.details || "N/A"}`;
     async handleGroupContext(args) {
         groupContextSchema.parse(args ?? {});
         const payload = await this.client.getGroupContext(args);
+        if (payload?.requiresWorkspaceSelection === true) {
+            const availableWorkspaces = Array.isArray(payload?.availableWorkspaces)
+                ? payload.availableWorkspaces.filter(isRecord)
+                : [];
+            const choices = availableWorkspaces
+                .map((workspace) => `${readString(workspace, "name") ?? "Unnamed workspace"} (${readString(workspace, "id") ?? "unknown id"})`)
+                .join(", ");
+            return {
+                content: [{
+                        type: "text",
+                        text: `You belong to ${availableWorkspaces.length} workspaces: ${choices}. Ask the user which workspace to show context for, then call get_group_context again with workspaceId set to one of those ids.`,
+                    }],
+            };
+        }
         const group = isRecord(payload?.group) ? payload.group : null;
         const participants = Array.isArray(payload?.participants)
             ? payload.participants.filter(isRecord)
@@ -2236,7 +2371,7 @@ Details: ${m.details || "N/A"}`;
     sharingPromptText(scopeText, groupName) {
         return [
             scopeText,
-            `Ask exactly: “Share eligible memories saved from this conversation with ${groupName}?” Only an explicit Yes or No may be passed to set_group_session_sharing. Silence leaves the state unset.`,
+            `Ask exactly: “Share eligible memories saved from this conversation with ${groupName}?” If your host can render a single-choice prompt, present this as one question with exactly two options — “Yes — share with team” and “No — keep private” — instead of free-form text. Only an explicit Yes or No may be passed to set_group_session_sharing. Silence leaves the state unset.`,
         ].filter(Boolean).join("\n\n");
     }
     formatGroupSessionSharingUpdate(share, payload, scopeText = "") {