@mysten-incubation/memwal-mcp 0.0.14-dev.0 → 0.0.14-dev.10

package/dist/bridge.js

@@ -3,8 +3,9 @@ import { TOOL_DEFINITIONS } from "./auth-required.js";
 import { clientInfoHeaders, lastClientInfoHeaders, rememberInitializeClientInfo, } from "./client-info.js";
 import { randomUUID } from "node:crypto";
 import { ensureCompatibleRelayer, resolveConnectTimeoutMs } from "./compatibility.js";
-import { PROACTIVE_INSTRUCTIONS } from "./instructions.js";
-import { startOrReuseLoginFlow, resolveLoginTimeoutMs } from "./login.js";
+import { describeHealthProbe, probeRelayerHealth, resolveHealthProbeMs, } from "./health-probe.js";
+import { proactiveInstructions } from "./instructions.js";
+import { startOrReuseLoginFlow, resolveLoginTimeoutMs, isLoginSuperseded } from "./login.js";
 import { log, note } from "./logger.js";
 import { loginPrompt, loginSuccessNotice, loginSuccessNotification, } from "./messages.js";
 import { openStreamableSession, resolveTransport } from "./streamable.js";
@@ -33,7 +34,8 @@ const NAMESPACE_TOOLS = new Set([
  *     per-call namespace always wins over the configured default.
  */
 /**
- * Name the relayer this process dialled in a `memwal_health` result.
+ * Name the destination this process is bound to in a `memwal_health` result:
+ * the relayer it dialled, and the account it signs for.
  *
  * The relayer-side text can only report an origin its deployment published, and
  * stays silent on a self-hosted or local one, where the sidecar knows nothing
@@ -45,8 +47,15 @@ const NAMESPACE_TOOLS = new Set([
  * Rewrites an existing `relayer=` field rather than appending a second one: when
  * both sides know the origin they describe the same session, and two
  * conflicting fields would be worse than neither.
+ *
+ * `account=` rides along for the same reason (WALM-639). A project-local
+ * credentials file can point this process at a different account than the one
+ * the user signed in with, and "which account am I writing to" was otherwise
+ * only visible in stderr the MCP host usually hides — so the half of the
+ * destination that decides WHOSE memory this is now shows up beside the half
+ * that decides where it is stored.
  */
-export function annotateHealthResult(result, relayerUrl) {
+export function annotateHealthResult(result, relayerUrl, accountId) {
     // A failed health call has no session to describe; naming a relayer beside
     // an error reads as though that relayer answered.
     if (result.isError)
@@ -60,6 +69,12 @@ export function annotateHealthResult(result, relayerUrl) {
     block.text = existing.test(block.text)
         ? block.text.replace(existing, `relayer=${relayerUrl}`)
         : `${block.text} relayer=${relayerUrl}`;
+    if (!accountId)
+        return;
+    const existingAccount = /\baccount=\S+/;
+    block.text = existingAccount.test(block.text)
+        ? block.text.replace(existingAccount, `account=${accountId}`)
+        : `${block.text} account=${accountId}`;
 }
 export function applyDefaultNamespace(msg, namespace) {
     if (!namespace)
@@ -88,7 +103,13 @@ const LOCAL_TOOL_DEFINITIONS = [
         description: "Sign in (or re-sign in) to Walrus Memory by opening a browser. Use to switch wallets, refresh credentials, or sign in for the first time. Returns a click-able URL — the user must approve in their browser.",
         inputSchema: {
             type: "object",
-            properties: {},
+            properties: {
+                freshKey: {
+                    type: "boolean",
+                    default: false,
+                    description: "Mint a new delegate key instead of reusing the one a previous unfinished sign-in left pending. Leave false for an ordinary login. Set it only after a normal sign-in has already failed on the pending key — it abandons that key, which must then be removed from the dashboard if it was approved on-chain, and the new one needs its own add_delegate_key transaction.",
+                },
+            },
             additionalProperties: false,
         },
     },
@@ -129,7 +150,11 @@ function buildLocalInitializeResult(params) {
         // client: this local answer wins and the upstream initialize reply is
         // suppressed. Omitting it here silently strips the proactive contract
         // from every stdio client, which is the WALM-324 regression itself.
-        instructions: PROACTIVE_INSTRUCTIONS,
+        //
+        // Resolved per handshake, not read from a module const: whether the
+        // model is told to save unprompted depends on the user's automatic-save
+        // opt-in, which lives on disk and can change between spawns (WALM-642).
+        instructions: proactiveInstructions(),
     };
 }
 /** Names of the tools we serve locally, so we can de-dup them out of the
@@ -152,6 +177,15 @@ const SIGNED_OUT_FAILURE = {
  * "connection dropped, please retry", which is advice that cannot work. Name
  * the cause and the way back in instead (GH #365 / WALM-602). */
 const UNAUTHORIZED_TEXT = "❌ Walrus Memory rejected the saved credentials (HTTP 401). The delegate key may have been revoked or is no longer registered on this account. Call `memwal_login` to sign in again — saved credentials were NOT modified.";
+/** Reply for a `tools/call` naming a tool the connected relayer does not
+ * serve. Names what IS on offer, because the agent's next move is to pick one
+ * of those — "unknown tool" alone leaves it guessing or retrying. */
+export function unknownToolText(name, available) {
+    return (`❌ \`${name}\` is not a tool this Walrus Memory server offers. ` +
+        `Available: ${available.join(", ")}. ` +
+        `Your tool list is stale — re-read \`tools/list\` and use one of those instead. ` +
+        `Nothing ran, so nothing was saved or changed.`);
+}
 /** `failRequest` options for every credentials-rejected refusal, so one refused
  * at handshake time and one refused on arrival afterwards read identically. */
 const UNAUTHORIZED_FAILURE = {
@@ -175,6 +209,10 @@ const LOCAL_TOOLS_LIST = {
         ...LOCAL_TOOL_DEFINITIONS,
     ],
 };
+/** Names advertised at cold start (baseline relayer + locally-served). A
+ * `tools/call` for anything else is refused until an upstream `tools/list`
+ * has been seen — fail-closed, not fail-open. */
+const COLD_START_TOOL_NAMES = new Set(LOCAL_TOOLS_LIST.tools.map((t) => t.name));
 const URL_READY_TIMEOUT_MS = 5_000;
 /** Maximum silence we tolerate on the SSE stream before assuming the
  * relayer-side session has gone dead. The relayer sends keepalive events
@@ -218,8 +256,13 @@ const MIN_CALL_TIMEOUT_MS = 1_000;
  * `MAX_STATUS_WAIT_MS` for `memwal_remember_status`, and the fixed `timeoutMs`
  * the bulk and analyze tools pass to the SDK. Keep them in lockstep: a value
  * below a tool's real ceiling abandons healthy work. Unlisted tools keep the
- * default. */
+ * default.
+ *
+ * `memwal_recall` is the exception to lockstep: the SDK aborts the recall
+ * request itself at 15s, but the checks it runs first (`/version`, `/config`)
+ * carry their own deadlines, or none on older SDKs. 90s covers those. */
 const TOOL_DEADLINE_MS = {
+    memwal_recall: 90_000,
     memwal_remember: 90_000,
     memwal_remember_status: 60_000,
     memwal_remember_bulk: 120_000,
@@ -700,13 +743,18 @@ function writeStdoutMessage(msg) {
  * mode, but available even when creds already exist (so user can re-login,
  * switch wallets, or refresh). Returns a click-able URL near-instantly;
  * listener stays alive in the background until callback or timeout. */
-async function handleLocalLogin(config, onCredentials) {
+async function handleLocalLogin(config, onCredentials, freshKey) {
+    let discardedKey;
     const session = startOrReuseLoginFlow({
         relayerUrl: config.relayerUrl,
         webUrl: config.webUrl,
         label: config.label,
         timeoutMs: resolveLoginTimeoutMs(),
         openBrowser: false,
+        freshKey,
+        onDiscarded: (key) => {
+            discardedKey = key;
+        },
     }, async (creds) => {
         await onCredentials(creds);
         log.info("memwal_login.bridge.success", {
@@ -750,8 +798,10 @@ async function handleLocalLogin(config, onCredentials) {
                 // cannot help that key, since it reuses it and the
                 // dashboard cannot register it twice.
                 data: `Walrus Memory sign-in did not complete: ${msg}. Existing credentials are ` +
-                    `unchanged. If you approved the wallet step, the next start reclaims that ` +
-                    `key; otherwise call memwal_login again to retry.`,
+                    `unchanged. The key is kept on disk and a later start reclaims it only if ` +
+                    `the relayer can confirm it was registered, which it cannot always do. ` +
+                    `Call memwal_login again to retry with that key, or with freshKey: true to ` +
+                    `mint a new one and abandon it.`,
             },
         });
     });
@@ -761,6 +811,9 @@ async function handleLocalLogin(config, onCredentials) {
         url = await Promise.race([session.url, timeoutPromise]);
     }
     catch (err) {
+        if (isLoginSuperseded(err)) {
+            return { isError: true, text: "This sign-in was replaced by a newer memwal_login. Open that result instead of starting another login." };
+        }
         return {
             isError: true,
             text: `❌ Failed to start login: ${err instanceof Error ? err.message : String(err)}`,
@@ -776,6 +829,7 @@ async function handleLocalLogin(config, onCredentials) {
             url,
             credentialsPath: credsPath(),
             signedIn: loadCreds() !== null,
+            discardedKey,
         }),
     };
 }
@@ -1148,15 +1202,23 @@ pendingLines = []) {
     const inFlight = new Map();
     const callTimeoutMs = resolveCallTimeoutMs();
     const stalledHandshakeMs = resolveStalledHandshakeMs(callTimeoutMs);
+    const healthProbeMs = resolveHealthProbeMs();
     /** IDs of `tools/list` requests we've forwarded to the relayer. When
      * the response comes back through the SSE pump, we splice in the
      * locally-served `memwal_login` + `memwal_logout` tools so the MCP
      * client surfaces them in its tool palette. */
     const pendingListIds = new Set();
-    /** IDs of forwarded `memwal_health` calls, each against the relayer URL the
-     * call went out on. Captured at send time rather than read at reply time so
-     * a reconnect that swapped credentials mid-flight cannot label the answer
-     * with a relayer it did not come from. */
+    /** Tool names the CONNECTED relayer advertised on its last `tools/list`,
+     * minus the ones we serve locally. Empty until the client has listed tools
+     * at least once over the *current* session. `reconnect()` clears it: a
+     * stale allow would re-forward a tool the new relayer does not serve
+     * (GH #928), and a stale deny would refuse a tool it does. Until the
+     * next upstream list, the gate allows only the cold-start floor. */
+    const upstreamToolNames = new Set();
+    /** IDs of forwarded `memwal_health` calls, each against the destination the
+     * call went out on — relayer URL and account. Captured at send time rather
+     * than read at reply time so a reconnect that swapped credentials mid-flight
+     * cannot label the answer with a destination it did not come from. */
     const pendingHealthIds = new Map();
     /** Record a 429 and tell the user ONCE that this is a rate limit rather
      * than a broken config — the distinction the MCP host cannot make for
@@ -1273,6 +1335,15 @@ pendingLines = []) {
                     throttleNoticed = false;
                     clearHandshakeFailure();
                     endConnectEpisode();
+                    // This session has not advertised anything yet. Keep the
+                    // previous set and a login that swapped relayerUrl would
+                    // re-forward a tool the new one does not serve, or refuse
+                    // one it does, until the client happened to re-list.
+                    upstreamToolNames.clear();
+                    writeStdoutMessage({
+                        jsonrpc: "2.0",
+                        method: "notifications/tools/list_changed",
+                    });
                     // An accepted handshake retires any earlier rejection —
                     // `memwal_login` re-registers a key and lands here, not on
                     // the background connect's publish path, so clearing only
@@ -1311,6 +1382,15 @@ pendingLines = []) {
                             log.info("bridge.replay_halted_signed_out", { id });
                             break;
                         }
+                        // The sweeper already declared this call's reply lost
+                        // and is answering it as failed. Posting it again would
+                        // run it a second time — a duplicate write for a tool
+                        // with no idempotency key — and the reply would be
+                        // dropped anyway, as a late answer for a closed-out id.
+                        if (entry.orphaned) {
+                            log.info("bridge.replay_skipped_orphaned", { id });
+                            continue;
+                        }
                         const msg = entry.msg;
                         try {
                             // A replayed `initialize` produces a fresh upstream
@@ -1641,6 +1721,16 @@ pendingLines = []) {
                             // duplicate tool name. Mirrors LOCAL_TOOLS_LIST.
                             const upstream = result.tools.filter((t) => !LOCAL_TOOL_NAMES.has(t.name ?? ""));
                             result.tools = [...upstream, ...LOCAL_TOOL_DEFINITIONS];
+                            // Record what this relayer actually serves. A
+                            // later call for a name absent here is answered
+                            // locally instead of being forwarded into a wait
+                            // no reply will ever end.
+                            upstreamToolNames.clear();
+                            for (const t of upstream) {
+                                if (typeof t.name === "string" && t.name !== "") {
+                                    upstreamToolNames.add(t.name);
+                                }
+                            }
                         }
                     }
                     if (value &&
@@ -1652,7 +1742,7 @@ pendingLines = []) {
                         const dialled = pendingHealthIds.get(value.id);
                         pendingHealthIds.delete(value.id);
                         if (dialled !== undefined) {
-                            annotateHealthResult(value.result, dialled);
+                            annotateHealthResult(value.result, dialled.relayerUrl, dialled.accountId);
                         }
                     }
                     // Health annotation runs BEFORE the sign-in banner. Both
@@ -1755,7 +1845,7 @@ pendingLines = []) {
                         id: msg.id,
                     });
                     if (params.name === "memwal_login") {
-                        const result = await handleLocalLogin(config, adoptCredentials);
+                        const result = await handleLocalLogin(config, adoptCredentials, params.arguments?.freshKey === true);
                         writeStdoutMessage({
                             jsonrpc: "2.0",
                             id: msg.id,
@@ -1811,6 +1901,45 @@ pendingLines = []) {
                     failRequest(msg, "credentials rejected", UNAUTHORIZED_FAILURE);
                     return;
                 }
+                // Version skew: this bridge ships on npm and updates itself,
+                // while a relayer ships per environment and does not, so the
+                // bridge is routinely newer than the server it dials. A tool
+                // named in initialize instructions or a cached list can be
+                // missing from the session that actually came up —
+                // `memwal_remember_status` against a prod relayer, which is
+                // GH #928. Forwarding that call parks it in `inFlight` until
+                // the orphan sweeper's deadline (60s + 30s headroom for that
+                // tool), and the user reads the 90s as a hang.
+                //
+                // Fail closed. Before any upstream `tools/list`, only the
+                // cold-start floor is callable. After one, only what that
+                // relayer advertised (plus locally-served tools). A stale
+                // tool list is not a transport fault: say so now, while the
+                // agent can still act on it.
+                if (msg.method === "tools/call" && msg.id != null) {
+                    const called = msg.params?.name;
+                    if (typeof called === "string" && !LOCAL_TOOL_NAMES.has(called)) {
+                        const known = upstreamToolNames.size > 0
+                            ? upstreamToolNames
+                            : COLD_START_TOOL_NAMES;
+                        if (!known.has(called)) {
+                            const available = [
+                                ...(upstreamToolNames.size > 0
+                                    ? [...upstreamToolNames, ...LOCAL_TOOL_NAMES]
+                                    : COLD_START_TOOL_NAMES),
+                            ].sort();
+                            log.warn("bridge.tool_not_served", {
+                                tool: called,
+                                window: upstreamToolNames.size > 0 ? "upstream" : "cold-start",
+                            });
+                            failRequest(msg, "tool not served", {
+                                toolText: unknownToolText(called, available),
+                                errorMessage: `${called} is not served by this Walrus Memory relayer`,
+                            });
+                            return;
+                        }
+                    }
+                }
                 // Fill in the configured default namespace for memory tool
                 // calls that didn't pass one. Mutates msg in place so the
                 // forwarded — and any replayed-on-reconnect — copy carries it.
@@ -1825,7 +1954,10 @@ pendingLines = []) {
                 if (msg.method === "tools/call" &&
                     msg.id != null &&
                     msg.params?.name === "memwal_health") {
-                    pendingHealthIds.set(msg.id, creds?.relayerUrl ?? config.relayerUrl);
+                    pendingHealthIds.set(msg.id, {
+                        relayerUrl: creds?.relayerUrl ?? config.relayerUrl,
+                        accountId: creds?.accountId,
+                    });
                 }
                 // Track requests (have both method and id) so we can replay
                 // them on reconnect. Notifications and responses are not
@@ -2079,13 +2211,19 @@ pendingLines = []) {
         "memwal_remember_bulk",
         "memwal_analyze",
     ]);
-    function expiredRequestReport(neverSent, now, tool) {
+    function expiredRequestReport(neverSent, now, tool, health) {
         if (!neverSent) {
+            // What the relayer's `/health` said just now: tells a dead
+            // relayer from a wrong URL from one stuck call.
+            const described = health ? describeHealthProbe(health.probe, health.relayerUrl) : null;
             // The request reached the relayer. What is missing is the reply,
             // and for a write that distinction is the whole message: the work
             // may have completed, may still be running, and cannot be assumed
             // undone. "Please retry" is only safe advice for a read.
             if (tool !== null && MUTATING_TOOLS.has(tool)) {
+                const healthNote = described
+                    ? `\nRelayer health: ${described.health}. ${described.verdict}`
+                    : "";
                 return {
                     reason: "no response to a sent write",
                     opts: {
@@ -2095,20 +2233,36 @@ pendingLines = []) {
                             "it and does not mean nothing was stored. Do NOT simply repeat the " +
                             "call: run `memwal_recall` for this content first, and only re-save " +
                             "what is genuinely missing. Repeating a bulk save that already " +
-                            "landed stores a second paid copy.",
+                            "landed stores a second paid copy." +
+                            healthNote,
                         errorMessage: `Walrus Memory ${tool} was sent but its reply never arrived. The write ` +
-                            "may have completed; verify with recall before retrying.",
+                            "may have completed; verify with recall before retrying." +
+                            healthNote,
                     },
                 };
             }
+            // Not "this call only reads": `memwal_restore` re-indexes. What
+            // makes a retry safe is that none of these can store a duplicate.
+            const nextStep = described === null || described.reachable
+                ? "Repeating this call cannot store a duplicate, so it is safe to retry " +
+                    "once. If it keeps happening, report it with the time of the call."
+                : "Repeating this call cannot store a duplicate, so it is safe to retry " +
+                    "after the relayer is reachable again — wait a minute if the problem " +
+                    "is on the relayer's side.";
+            const healthValue = described?.health ?? "not checked";
             return {
                 reason: "no response",
                 opts: {
-                    toolText: "❌ Walrus Memory did not answer this call. The request reached the " +
-                        "relayer but the reply never came back. This call only reads, so it is " +
-                        "safe to retry.",
-                    errorMessage: "Walrus Memory call was orphaned by a reconnect and never " +
-                        "received a response. Safe to retry: this call only reads.",
+                    toolText: [
+                        "❌ Walrus Memory did not answer this call.",
+                        "Cause: the request reached the relayer but no reply came back." +
+                            (described ? ` ${described.verdict}` : ""),
+                        `Relayer health: ${healthValue}`,
+                        `Next step: ${nextStep}`,
+                    ].join("\n"),
+                    errorMessage: "Walrus Memory call reached the relayer but never received a " +
+                        `response (relayer health: ${healthValue}). Safe to retry: it cannot ` +
+                        "store a duplicate.",
                 },
             };
         }
@@ -2148,6 +2302,8 @@ pendingLines = []) {
     const orphanSweeper = setInterval(() => {
         const now = Date.now();
         const handshakeStalledMs = handshakeStalledForMs(now);
+        // One `/health` request per sweep, however many calls expired in it.
+        let sweepProbe = null;
         for (const [id, entry] of Array.from(inFlight.entries())) {
             const elapsedMs = now - entry.startedAt;
             // Never sent = no POST was ever issued for it. Read from the entry
@@ -2172,6 +2328,58 @@ pendingLines = []) {
                 : entry.deadlineMs;
             if (elapsedMs <= deadlineMs)
                 continue;
+            // `initialize` is answered locally and gets no reply here, so
+            // there is nothing to explain and nothing to probe for.
+            if (!neverSent && entry.msg.method !== "initialize") {
+                // A sent call: ask the relayer's `/health` before answering,
+                // so the message can say whether it is down, unreachable, or
+                // up with this one call stuck. Only the answer waits on the
+                // probe; the bookkeeping stays synchronous.
+                if (entry.probing)
+                    continue;
+                entry.probing = true;
+                // From here the call is the sweeper's to answer: a reconnect
+                // must not replay it behind the probe's back.
+                entry.orphaned = true;
+                const relayerUrl = creds?.relayerUrl ?? config.relayerUrl;
+                // `probeRelayerHealth` does not reject, but a call left with
+                // `probing` set and no answer is the one outcome this path
+                // must never have, so a rejection still answers it.
+                sweepProbe ??= probeRelayerHealth(relayerUrl, healthProbeMs).catch(() => null);
+                void sweepProbe
+                    .then((probe) => {
+                    // A late reply, a logout or a shutdown may have answered
+                    // it while the probe ran. Answering again would be a
+                    // second response for the same id — and after stdin has
+                    // closed there is nobody left to answer.
+                    if (stdinClosed || inFlight.get(id) !== entry)
+                        return;
+                    const settledAt = Date.now();
+                    const { reason, opts } = expiredRequestReport(false, settledAt, toolNameOf(entry.msg), probe ? { probe, relayerUrl } : undefined);
+                    log.warn("bridge.call_orphaned", {
+                        id,
+                        method: entry.msg.method ?? null,
+                        elapsedMs: settledAt - entry.startedAt,
+                        deadlineMs,
+                        reason,
+                        health: probe?.kind ?? null,
+                        healthMs: probe?.ms ?? null,
+                        handshakeStalledMs: handshakeStalledForMs(settledAt),
+                        lastHandshakeError,
+                    });
+                    failRequest(entry.msg, reason, opts);
+                })
+                    .catch((err) => {
+                    // Never leave a call marked `probing` with no answer:
+                    // clearing it lets the next sweep answer it.
+                    entry.probing = false;
+                    log.warn("bridge.call_orphaned_answer_failed", {
+                        id,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+                continue;
+            }
             // Built only for what actually expired: this walks `pendingForward`
             // and interpolates two user-facing strings, and the branch it
             // serves fires roughly never.