@finchagentic/mcp 4.1.0 → 4.2.0

package/dist/tools/stake.js

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STAKE_TOOLS = void 0;
+exports.parseStakeAmount = parseStakeAmount;
+exports.handleStakeTool = handleStakeTool;
+const ethers_1 = require("ethers");
+const convex_js_1 = require("../convex.js");
+const config_js_1 = require("../config.js");
+const rh_mcp_js_1 = require("./rh-mcp.js");
+// FINCH staking - MCP wrapper around the EXISTING app/convex staking actions
+// (stake.ts's stakeFINCH/unstakeFINCH, stakeInternal.ts's myStakingStats/
+// globalStats). No staking logic lives here - this only parses a
+// human-friendly amount ("all", "max", "50%", "1m", "100k", a raw number)
+// into wei and calls the backend, exactly like the webapp's Stake page does.
+//
+// IMPORTANT - custodial wallet, not the local signing wallet: unlike
+// base_mcp_swap/rh_mcp_swap (which sign and broadcast with the LOCAL
+// ~/.finch/wallet.json key and need no login), staking moves FINCH from the
+// account's CUSTODIAL wallet (the one shown on the webapp's Wallet page) -
+// stake.ts's actions resolve identity via a real logged-in session, not a
+// wallet signature. Requires `finch login` first; there is no way around
+// this without changing stake.ts's own session-based design, which is out
+// of scope here. The local wallet and the custodial wallet are DIFFERENT
+// addresses with different balances - never conflate them in output.
+//
+// SECURITY: no tool here ever returns a private key or seed phrase, and
+// none ever will - the custodial key stays server-side (Turnkey-enclave /
+// encrypted-at-rest), exactly as it already does for the webapp. "Log in,
+// then stake" is the ceiling of what this integration does; it does not,
+// and must not, add an export path.
+const FINCH_CA = "0xce1981b0431fb495912cab057d2877a290199824";
+const FINCH_DECIMALS = 18;
+const ERC20_BALANCE_ABI = ["function balanceOf(address) view returns (uint256)"];
+// Mirrors app/convex/stake.ts's STAKING_TIERS - fixed constants, not worth a
+// round-trip to the backend to fetch. Keep in sync if the backend tiers change.
+const STAKING_TIERS = {
+    7: { multiplier: 1.0, label: "Flexible" },
+    30: { multiplier: 1.5, label: "Committed" },
+    90: { multiplier: 2.0, label: "Diamond Hands" },
+};
+const VALID_LOCK_TIERS = Object.keys(STAKING_TIERS).map(Number);
+function requireLogin() {
+    const token = (0, config_js_1.getSavedToken)();
+    return token ? { token } : null;
+}
+const NOT_LOGGED_IN_MSG = "Staking needs a logged-in session (not just the local wallet). Run `finch login` first, then retry.";
+async function finchBalanceOf(address) {
+    const provider = await (0, rh_mcp_js_1.rhProviderAsync)();
+    const finch = new ethers_1.ethers.Contract(FINCH_CA, ERC20_BALANCE_ABI, provider);
+    return await finch.balanceOf(address);
+}
+// Parses "all" | "max" | "50%" | "1m" | "100k" | "100000" | "value 100000"
+// against a live balance. Returns wei as a string, or throws with a message
+// the caller can show verbatim.
+function parseStakeAmount(input, balanceWei) {
+    const raw = input.trim().toLowerCase().replace(/^value\s+/, "");
+    if (raw === "all" || raw === "max") {
+        if (balanceWei <= 0n)
+            throw new Error("Wallet has 0 FINCH - nothing to stake.");
+        return balanceWei;
+    }
+    const pctMatch = raw.match(/^(\d+(?:\.\d+)?)\s*%$/);
+    if (pctMatch) {
+        const pct = parseFloat(pctMatch[1]);
+        if (!(pct > 0) || pct > 100)
+            throw new Error("Percentage must be between 0 and 100.");
+        return (balanceWei * BigInt(Math.round(pct * 100))) / 10000n;
+    }
+    const suffixMatch = raw.match(/^(\d+(?:\.\d+)?)\s*([km])$/);
+    if (suffixMatch) {
+        const n = parseFloat(suffixMatch[1]);
+        const mult = suffixMatch[2] === "m" ? 1000000 : 1000;
+        return ethers_1.ethers.parseUnits((n * mult).toString(), FINCH_DECIMALS);
+    }
+    const plainMatch = raw.match(/^(\d+(?:\.\d+)?)$/);
+    if (plainMatch) {
+        return ethers_1.ethers.parseUnits(plainMatch[1], FINCH_DECIMALS);
+    }
+    throw new Error(`Could not parse amount "${input}". Use "all", "max", a percentage like "50%", ` +
+        `a shorthand like "1m" or "100k", or a plain number like "100000".`);
+}
+function fmtFinch(wei) {
+    return `${Number(ethers_1.ethers.formatUnits(wei, FINCH_DECIMALS)).toLocaleString("en-US", { maximumFractionDigits: 4 })} FINCH`;
+}
+exports.STAKE_TOOLS = [
+    {
+        name: "stake_finch_status",
+        description: "View your FINCH staking status - custodial wallet balance available to stake, your active stakes " +
+            "(amount, lock-up remaining, accrued rewards), and pool-wide stats (total staked, daily USDG reward). " +
+            "Requires `finch login` (stakes live on your account's custodial wallet, not the local MCP signing wallet).",
+        inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "stake_finch",
+        description: "Stake FINCH from your custodial wallet (the one shown on the webapp's Wallet page) to earn USDG " +
+            "rewards. Locks for a fixed period chosen at stake time - unstake is blocked until then, and the " +
+            "tier cannot be changed mid-stake. Longer locks earn a higher reward multiplier: " +
+            "7 days = 1.0x (default) · 30 days = 1.5x · 90 days = 2.0x. " +
+            "Requires `finch login` first and `confirm: true`. Amount accepts \"all\"/\"max\" (entire " +
+            "available balance), a percentage (\"50%\"), a shorthand (\"1m\", \"100k\"), or a plain number " +
+            "(\"100000\").",
+        inputSchema: {
+            type: "object",
+            properties: {
+                amount: {
+                    type: "string",
+                    description: "\"all\" | \"max\" | \"50%\" | \"1m\" | \"100k\" | \"100000\"",
+                },
+                lockTier: {
+                    type: "number",
+                    enum: [7, 30, 90],
+                    description: "Lock period in days: 7 (1.0x, default), 30 (1.5x), or 90 (2.0x). Omit for 7-day/1.0x.",
+                },
+                confirm: {
+                    type: "boolean",
+                    description: "Must be true to stake - this moves real FINCH out of your custodial wallet.",
+                },
+            },
+            required: ["amount", "confirm"],
+        },
+    },
+    {
+        name: "unstake_finch",
+        description: "Unstake FINCH back to your custodial wallet, plus any pending USDG rewards. Only works once the " +
+            "lock-up period has passed (check stake_finch_status for which stakes are unlockable). Requires " +
+            "`finch login` and `confirm: true`. Pass a specific stakeId, or \"all\" to unstake every currently " +
+            "unlockable stake in one call (each processed and reported individually).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                stakeId: { type: "string", description: "A stake ID from stake_finch_status, or \"all\"" },
+                confirm: { type: "boolean", description: "Must be true to unstake." },
+            },
+            required: ["stakeId", "confirm"],
+        },
+    },
+    {
+        name: "stake_auto_restake",
+        description: "Turn auto-restake on/off for one of your stakes. When ON, the moment the lock-up ends the stake " +
+            "is automatically renewed for another full period at the SAME tier - no FINCH ever leaves the " +
+            "treasury, no gas, no confirmation needed each cycle (a background job on the Finch backend does " +
+            "this, roughly every 15 minutes). When OFF (default), you instead get a one-time notification that " +
+            "the stake is unlockable and it just sits there earning nothing until you run unstake_finch. " +
+            "Does NOT auto-compound rewards into the stake - that would require signing from your custodial " +
+            "wallet unattended, which this intentionally does not do; claim rewards yourself with " +
+            "claimVestedRewards (you'll get a notification when they're ready). Requires `finch login`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                stakeId: { type: "string", description: "A stake ID from stake_finch_status" },
+                enabled: { type: "boolean", description: "true to turn auto-restake on, false to turn it off" },
+            },
+            required: ["stakeId", "enabled"],
+        },
+    },
+];
+async function handleStakeTool(name, args) {
+    if (name === "stake_finch_status") {
+        const login = requireLogin();
+        if (!login)
+            return { content: [{ type: "text", text: NOT_LOGGED_IN_MSG }], isError: true };
+        const data = await (0, convex_js_1.callConvex)("/mcp/stake/status", "GET", undefined, "stake_finch_status");
+        if (data.error)
+            return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
+        const address = data.walletAddress ?? null;
+        let balanceWei = null;
+        if (address) {
+            try {
+                balanceWei = await finchBalanceOf(address);
+            }
+            catch { /* balance is a nice-to-have, don't fail the whole status */ }
+        }
+        const my = data.myStats;
+        const global = data.global;
+        const lines = [
+            `## FINCH Staking Status`,
+            ``,
+            address ? `**Custodial wallet:** \`${address}\` ${balanceWei != null ? `(${fmtFinch(balanceWei)} available to stake)` : ""}` : `_Could not resolve custodial wallet address._`,
+            ``,
+            global ? `**Pool:** ${global.totalStakedHuman.toLocaleString()} FINCH staked by ${global.totalStakers} stakers · ${global.dailyRewardUsdg} USDG/day pool` : "",
+            `**Lock tiers:** ${VALID_LOCK_TIERS.map((t) => `${t}d/${STAKING_TIERS[t].multiplier}x (${STAKING_TIERS[t].label})`).join(" · ")} — pick with \`stake_finch lockTier\`, default 7d/1.0x`,
+            ``,
+            my ? `**Your stakes:** ${my.activeStakes} active · ${my.totalStaked.toLocaleString()} FINCH staked · ${my.totalRewards.toFixed(4)} USDG accrued · ${my.canUnstakeCount} unlockable now` : "",
+        ];
+        if (my?.stakes?.length) {
+            lines.push(``, `**Detail:**`);
+            for (const s of my.stakes) {
+                const unlocked = Date.now() >= s.unlockAt;
+                const tier = STAKING_TIERS[s.lockTier ?? 7] ?? STAKING_TIERS[7];
+                const autoNote = s.status === "staked" ? (s.autoRestake ? " · 🔄 auto-restake ON" : "") : "";
+                lines.push(`- \`${s._id}\` — ${s.amountHuman} FINCH · ${s.lockTier ?? 7}d/${tier.multiplier}x · ${s.status}${s.status === "staked" ? (unlocked ? " · unlockable now" : ` · unlocks ${new Date(s.unlockAt).toISOString().slice(0, 10)}`) : ""}${autoNote}`);
+            }
+        }
+        return { content: [{ type: "text", text: lines.filter(Boolean).join("\n") }] };
+    }
+    if (name === "stake_finch") {
+        const raw = (args ?? {});
+        const { amount, confirm } = raw;
+        // Coerce defensively - MCP clients commonly send numeric args as JSON
+        // strings, and unlike `amount` (a string by design, parsed by
+        // parseStakeAmount) or `confirm` (unambiguous boolean), a stray
+        // "30" here must not silently mismatch the numeric VALID_LOCK_TIERS
+        // check and fall through to the 7-day default with no error.
+        const lockTier = raw.lockTier === undefined || raw.lockTier === null || raw.lockTier === ""
+            ? undefined
+            : Number(raw.lockTier);
+        if (!amount)
+            return { content: [{ type: "text", text: "amount is required" }], isError: true };
+        if (lockTier !== undefined && (!Number.isFinite(lockTier) || !VALID_LOCK_TIERS.includes(lockTier))) {
+            return {
+                content: [{ type: "text", text: `Invalid lockTier ${JSON.stringify(raw.lockTier)} - must be one of ${VALID_LOCK_TIERS.join(", ")} (days).` }],
+                isError: true,
+            };
+        }
+        if (confirm !== true) {
+            return {
+                content: [{ type: "text", text: "Refusing to stake without confirmation - pass `confirm: true` after reviewing the amount." }],
+                isError: true,
+            };
+        }
+        const login = requireLogin();
+        if (!login)
+            return { content: [{ type: "text", text: NOT_LOGGED_IN_MSG }], isError: true };
+        const status = await (0, convex_js_1.callConvex)("/mcp/stake/status", "GET", undefined, "stake_finch_status");
+        if (status.error)
+            return { content: [{ type: "text", text: `Error: ${status.error}` }], isError: true };
+        if (!status.walletAddress)
+            return { content: [{ type: "text", text: "Could not resolve your custodial wallet address." }], isError: true };
+        let balanceWei;
+        try {
+            balanceWei = await finchBalanceOf(status.walletAddress);
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Could not read FINCH balance: ${e?.message ?? e}` }], isError: true };
+        }
+        let amountWei;
+        try {
+            amountWei = parseStakeAmount(amount, balanceWei);
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: e.message }], isError: true };
+        }
+        if (amountWei > balanceWei) {
+            return {
+                content: [{ type: "text", text: `Insufficient FINCH. Have ${fmtFinch(balanceWei)}, tried to stake ${fmtFinch(amountWei)}.` }],
+                isError: true,
+            };
+        }
+        const result = await (0, convex_js_1.callConvex)("/mcp/stake/stake", "POST", { amountWei: amountWei.toString(), lockTier }, "stake_finch");
+        if (result.error)
+            return { content: [{ type: "text", text: `Stake failed: ${result.error}` }], isError: true };
+        const tier = STAKING_TIERS[lockTier ?? 7];
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `✅ Staked ${fmtFinch(amountWei)}`,
+                        `Lock: ${lockTier ?? 7} days (${tier.label}, ${tier.multiplier}x rewards)`,
+                        `Stake ID: \`${result.stakeId}\``,
+                        `Tx: \`${result.txHash}\``,
+                        `${rh_mcp_js_1.RH_EXPLORER}/tx/${result.txHash}`,
+                    ].join("\n"),
+                }],
+        };
+    }
+    if (name === "unstake_finch") {
+        const { stakeId, confirm } = (args ?? {});
+        if (!stakeId)
+            return { content: [{ type: "text", text: "stakeId is required (or \"all\")" }], isError: true };
+        if (confirm !== true) {
+            return {
+                content: [{ type: "text", text: "Refusing to unstake without confirmation - pass `confirm: true`." }],
+                isError: true,
+            };
+        }
+        const login = requireLogin();
+        if (!login)
+            return { content: [{ type: "text", text: NOT_LOGGED_IN_MSG }], isError: true };
+        let targetIds;
+        if (stakeId.toLowerCase() === "all") {
+            const status = await (0, convex_js_1.callConvex)("/mcp/stake/status", "GET", undefined, "stake_finch_status");
+            if (status.error)
+                return { content: [{ type: "text", text: `Error: ${status.error}` }], isError: true };
+            const now = Date.now();
+            targetIds = (status.myStats?.stakes ?? [])
+                .filter((s) => s.status === "staked" && now >= s.unlockAt)
+                .map((s) => s._id);
+            if (!targetIds.length) {
+                return { content: [{ type: "text", text: "No stakes are currently unlockable." }] };
+            }
+        }
+        else {
+            targetIds = [stakeId];
+        }
+        const lines = [];
+        for (const id of targetIds) {
+            const result = await (0, convex_js_1.callConvex)("/mcp/stake/unstake", "POST", { stakeId: id }, "unstake_finch");
+            if (result.error) {
+                lines.push(`🔴 \`${id}\`: ${result.error}`);
+            }
+            else {
+                lines.push(`✅ \`${id}\` unstaked — tx \`${result.txHash}\`${result.rewardsTxHash ? ` · rewards tx \`${result.rewardsTxHash}\`` : ""}`);
+            }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    if (name === "stake_auto_restake") {
+        const { stakeId, enabled } = (args ?? {});
+        if (!stakeId)
+            return { content: [{ type: "text", text: "stakeId is required" }], isError: true };
+        if (typeof enabled !== "boolean")
+            return { content: [{ type: "text", text: "enabled (true/false) is required" }], isError: true };
+        const login = requireLogin();
+        if (!login)
+            return { content: [{ type: "text", text: NOT_LOGGED_IN_MSG }], isError: true };
+        const result = await (0, convex_js_1.callConvex)("/mcp/stake/auto-restake", "POST", { stakeId, enabled }, "stake_auto_restake");
+        if (result.error)
+            return { content: [{ type: "text", text: `Failed: ${result.error}` }], isError: true };
+        return {
+            content: [{
+                    type: "text",
+                    text: enabled
+                        ? `🔄 Auto-restake ON for \`${stakeId}\`. It'll renew itself for another full period at the same tier every time it unlocks - no action needed from you.`
+                        : `⏸️ Auto-restake OFF for \`${stakeId}\`. You'll get a notification when it unlocks instead, and it'll just sit there until you run \`unstake_finch\`.`,
+                }],
+        };
+    }
+    return null;
+}

package/dist/tools/vault.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VAULT_TOOLS = void 0;
+exports.buildVaultList = buildVaultList;
+exports.buildVaultSearch = buildVaultSearch;
 exports.handleVaultTool = handleVaultTool;
 const zod_1 = require("zod");
 const convex_js_1 = require("../convex.js");
@@ -280,6 +282,35 @@ function formatBytes(n) {
 function formatDate(ts) {
     return new Date(ts).toUTCString();
 }
+// ── Structured output builders (schemas in output-schemas.ts) ───────────────
+function buildVaultList(entries, type) {
+    return {
+        type: type ?? null,
+        count: entries.length,
+        entries: entries.map((e) => ({
+            key: e.key,
+            title: e.title ?? null,
+            type: e.type ?? null,
+            version: e.version ?? null,
+            size: e.size ?? null,
+            updatedAt: e.updatedAt ?? null,
+            isPinned: !!e.isPinned,
+        })),
+    };
+}
+function buildVaultSearch(query, results) {
+    return {
+        query,
+        count: results.length,
+        results: results.map((r) => ({
+            key: r.key,
+            title: r.title ?? null,
+            type: r.type ?? null,
+            score: r.score ?? null,
+            preview: r.preview ?? null,
+        })),
+    };
+}
 // ─── Handler ─────────────────────────────────────────────────────────────────
 async function handleVaultTool(name, args) {
     // When the user has opted into a fully-local, user-owned vault
@@ -292,6 +323,20 @@ async function handleVaultTool(name, args) {
             const parsed = SaveSchema.safeParse(args);
             if (!parsed.success)
                 return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+            if (parsed.data.type === "credential") {
+                // vault_save writes plaintext to disk/DB - "credential" is only a
+                // valid FILTER value for vault_list/search/export (which correctly
+                // exclude it), never a valid type to actually SAVE through here.
+                // vault_store_credential is the only path that encrypts at rest.
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Use `vault_store_credential` to save a secret - it encrypts at rest (AES-256-GCM). " +
+                                "`vault_save` writes plaintext, so `type: \"credential\"` is refused here.",
+                        }],
+                    isError: true,
+                };
+            }
             // Auto-generate title from content if not provided
             const firstLine = parsed.data.content.split("\n")[0].replace(/^#+\s*/, "").slice(0, 80);
             const autoTitle = parsed.data.title ?? (firstLine || `${parsed.data.type} - ${new Date().toISOString().slice(0, 10)}`);
@@ -383,17 +428,14 @@ async function handleVaultTool(name, args) {
                 }
                 return { content: [{ type: "text", text: `vault_read error: ${data.error}` }], isError: true };
             }
-            // Large entries are offloaded to Convex File Storage. The doc holds a
-            // preview only; pull the real content from /vault/blob.
-            let fullContent = data.content ?? "";
-            if (data.contentFileId) {
-                try {
-                    fullContent = await (0, convex_js_1.callConvexRaw)(`/vault/blob?id=${encodeURIComponent(data.contentFileId)}`, "vault_read");
-                }
-                catch (err) {
-                    fullContent = (data.content ?? "") + `\n\n_(could not load full blob: ${err.message})_`;
-                }
-            }
+            // NOTE: there is no blob-storage tier on the backend (see
+            // app/convex/vault.ts MAX_CONTENT_BYTES comment) - oversized content is
+            // rejected at save time, not offloaded to file storage, so `contentFileId`
+            // never comes back on a vault entry. A `/vault/blob` fallback used to live
+            // here but the route was never registered in http.ts either, so it was
+            // dead in both directions - removed rather than fixed against a storage
+            // tier that doesn't exist. Re-add only alongside building that tier.
+            const fullContent = data.content ?? "";
             const sizeLabel = data.originalSize ? formatBytes(data.originalSize) : formatBytes(data.size);
             const backlinksBlock = Array.isArray(data.backlinks) && data.backlinks.length > 0
                 ? `\n🔙 Linked from (${data.backlinks.length}):\n${data.backlinks.map((b) => `  ← \`${b.key}\`${b.title ? ` - ${b.title}` : ""}`).join("\n")}`
@@ -433,11 +475,18 @@ async function handleVaultTool(name, args) {
             if (data.error)
                 return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
             const entries = data.entries ?? [];
-            if (!entries.length)
-                return { content: [{ type: "text", text: `No vault entries found${parsed.data.type ? ` of type '${parsed.data.type}'` : ""}.` }] };
+            if (!entries.length) {
+                return {
+                    content: [{ type: "text", text: `No vault entries found${parsed.data.type ? ` of type '${parsed.data.type}'` : ""}.` }],
+                    structuredContent: buildVaultList([], parsed.data.type),
+                };
+            }
             const header = `📚 **Finch Vault** (${entries.length} entries)`;
             const rows = entries.map((e) => `${e.isPinned ? "📌 " : ""}[\`${e.key}\`] ${e.title} - v${e.version} · ${e.type} · ${formatBytes(e.size)} · ${formatDate(e.updatedAt)}`);
-            return { content: [{ type: "text", text: [header, "", ...rows].join("\n") }] };
+            return {
+                content: [{ type: "text", text: [header, "", ...rows].join("\n") }],
+                structuredContent: buildVaultList(entries, parsed.data.type),
+            };
         }
         case "vault_search": {
             const parsed = SearchSchema.safeParse(args);
@@ -449,7 +498,12 @@ async function handleVaultTool(name, args) {
             // entries are indexed as multiple chunks tagged with isVaultChunk +
             // vaultKey - group chunks back to their parent entry so the result
             // list shows one row per entry, not one row per chunk.
-            {
+            //
+            // Skipped entirely when vaultBackend is local - a local vault's whole
+            // point is "no network," so the query string must never leave the
+            // machine, not even to check for results before falling back to the
+            // (always-local) full-text branch below.
+            if (!localVault) {
                 const limit = parsed.data.limit ?? 20;
                 // Over-fetch so that after chunk dedup we still have ~limit rows.
                 const smResults = await (0, memory_js_1.searchSupermemory)(parsed.data.query, Math.min(50, limit * 3));
@@ -489,7 +543,7 @@ async function handleVaultTool(name, args) {
                         const grouped = Array.from(groups.values())
                             .sort((a, b) => b.bestScore - a.bestScore)
                             .slice(0, limit);
-                        const header = `🔍 **Vault Search** [Semantic]: "${parsed.data.query}" - ${grouped.length} entry/entries`;
+                        const header = `🔍 **Vault Search**: "${parsed.data.query}" - ${grouped.length} entry/entries`;
                         const rows = grouped.map((g, i) => {
                             const score = g.bestScore ? ` ${(g.bestScore * 100).toFixed(0)}%` : "";
                             const chunkBadge = g.isVaultChunk && g.chunkHits > 1
@@ -500,7 +554,10 @@ async function handleVaultTool(name, args) {
                                 `   ${g.bestPreview}${g.bestPreview.length >= 200 ? "…" : ""}`,
                             ].join("\n");
                         });
-                        return { content: [{ type: "text", text: [header, "", ...rows].join("\n") }] };
+                        return {
+                            content: [{ type: "text", text: [header, "", ...rows].join("\n") }],
+                            structuredContent: buildVaultSearch(parsed.data.query, grouped.map((g) => ({ key: g.key, title: g.title, type: g.type, score: g.bestScore, preview: g.bestPreview }))),
+                        };
                     }
                 }
             }
@@ -516,14 +573,21 @@ async function handleVaultTool(name, args) {
             if (data.error)
                 return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
             const results = data.results ?? [];
-            if (!results.length)
-                return { content: [{ type: "text", text: `No vault entries found for: "${parsed.data.query}"` }] };
+            if (!results.length) {
+                return {
+                    content: [{ type: "text", text: `No vault entries found for: "${parsed.data.query}"` }],
+                    structuredContent: buildVaultSearch(parsed.data.query, []),
+                };
+            }
             const header = `🔍 **Vault Search**: "${parsed.data.query}" - ${results.length} result(s)`;
             const rows = results.map((r, i) => [
                 `${i + 1}. [\`${r.key}\`] **${r.title}**  (${r.type} · v${r.version})`,
                 `   ${r.preview}`,
             ].join("\n"));
-            return { content: [{ type: "text", text: [header, "", ...rows].join("\n") }] };
+            return {
+                content: [{ type: "text", text: [header, "", ...rows].join("\n") }],
+                structuredContent: buildVaultSearch(parsed.data.query, results),
+            };
         }
         case "vault_history": {
             const parsed = HistorySchema.safeParse(args);
@@ -714,7 +778,21 @@ async function handleVaultTool(name, args) {
                 : await (0, convex_js_1.callConvex)("/vault/delete", "POST", { key: parsed.data.key }, "vault_delete");
             if (data.error)
                 return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
-            return { content: [{ type: "text", text: `🗑️ Deleted: \`${parsed.data.key}\` (${data.versionsRemoved ?? 0} versions removed)` }] };
+            // vault_save mirrors non-credential entries into memory for search - a
+            // "PERMANENT... cannot be undone" delete that leaves that mirror intact
+            // is not actually permanent. Only relevant for the local memory-file
+            // backend (the hosted Convex path cleans its own memories table inside
+            // the /vault/delete mutation itself, same request, no separate call).
+            let memoriesRemoved = 0;
+            const localMem = (0, local_memory_js_1.getLocalMemoryConfig)();
+            if (localMem) {
+                memoriesRemoved = (0, local_memory_js_1.localMemoryDeleteByVaultKey)(localMem, parsed.data.key);
+            }
+            else if (typeof data.memoriesRemoved === "number") {
+                memoriesRemoved = data.memoriesRemoved;
+            }
+            const memoryNote = memoriesRemoved > 0 ? ` + ${memoriesRemoved} memory mirror${memoriesRemoved === 1 ? "" : "s"} removed` : "";
+            return { content: [{ type: "text", text: `🗑️ Deleted: \`${parsed.data.key}\` (${data.versionsRemoved ?? 0} versions removed${memoryNote})` }] };
         }
         case "vault_tag": {
             const parsed = TagSchema.safeParse(args);