@finchagentic/mcp 4.1.0 → 4.4.1

package/dist/tools/vault.js

@@ -1,20 +1,24 @@
 "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");
 const memory_js_1 = require("./memory.js");
 const local_vault_js_1 = require("../local-vault.js");
 const local_memory_js_1 = require("../local-memory.js");
-const VAULT_TYPES = ["research", "execution", "workflow", "prompt", "file", "memory", "credential"];
+const project_js_1 = require("../project.js");
+const VAULT_TYPES = ["research", "execution", "workflow", "prompt", "file", "memory", "code", "credential"];
 exports.VAULT_TOOLS = [
     {
         name: "vault_save",
         description: "Save or update a versioned artifact in Finch Vault. Same key = update (git-style: prior version snapshotted, patched to v+1). " +
-            "Types: research | execution | workflow | prompt | file | memory. " +
+            "Types: research | execution | workflow | prompt | file | memory | code. " +
             "Entries up to 10MB - content over 600KB auto-offloads to blob storage. " +
-            "For quick unstructured notes, use memory_add instead.",
+            "For quick unstructured notes, use memory_add instead. For coding sessions specifically, " +
+            "prefer code_session_save - same versioning, but a structured template and auto-linking built in.",
         inputSchema: {
             type: "object",
             properties: {
@@ -27,10 +31,37 @@ exports.VAULT_TOOLS = [
                 tags: { type: "array", items: { type: "string" }, description: "Tags for filtering and search" },
                 commitMsg: { type: "string", description: "Commit message for this version, e.g. 'initial research', 'refined with on-chain data'" },
                 metadata: { type: "string", description: "Optional JSON string for extra structured fields" },
+                workspaceProject: {
+                    type: "string",
+                    description: "Optional: file this entry into a named Finch workspace project (the same Projects a user " +
+                        "organizes their Agents/vault into on the Agents page). Matched case-insensitively by name; " +
+                        "created automatically if it doesn't exist yet. Not the same thing as a `key` path segment - " +
+                        "this tags the entry in Finch's own project system. Hosted vault only (no effect in local-vault mode).",
+                },
             },
             required: ["type", "content"],
         },
     },
+    {
+        name: "code_session_save",
+        description: "Persist a coding/debugging session as a versioned Markdown snapshot in Finch Vault, keyed by " +
+            "project (`code/<project>`) - so the next session (yours, or another agent's) has real context " +
+            "instead of starting cold. Same project = new version, full history kept (git-style, like vault_save). " +
+            "Auto-links to related past code and research entries. " +
+            "Call this at the end of a substantive coding task - not for every single file read or trivial edit.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: { type: "string", description: "Project or repo slug, e.g. 'finch-webapp', 'mcp-server'. Becomes the vault key: code/<project>." },
+                summary: { type: "string", description: "What was done this session - the task, the approach, the outcome." },
+                filesChanged: { type: "array", items: { type: "string" }, description: "Files touched, e.g. ['app/convex/vault.ts', 'app/src/App.tsx']" },
+                decisions: { type: "string", description: "Notable decisions or tradeoffs made and why - the part a future session can't re-derive from a diff alone." },
+                nextSteps: { type: "string", description: "What's left, or what to pick up next session." },
+                tags: { type: "array", items: { type: "string" }, description: "Extra tags for search, e.g. ['bugfix', 'refactor']" },
+            },
+            required: ["project", "summary"],
+        },
+    },
     {
         name: "vault_read",
         description: "Read a Finch Vault entry by its key. Returns full content, version, tags, and any linked entries.",
@@ -230,6 +261,14 @@ exports.VAULT_TOOLS = [
             required: ["key"],
         },
     },
+    {
+        name: "list_projects",
+        description: "List your Finch workspace projects - the same Projects used to organize Agents and vault content on the " +
+            "webapp Agents page. Read-only. Check this before passing `workspaceProject` to vault_save/agent_spawn if " +
+            "you want to reuse an existing project rather than relying on the automatic case-insensitive name match. " +
+            "No effect / nothing to list in local-vault mode.",
+        inputSchema: { type: "object", properties: {}, required: [] },
+    },
 ];
 // ─── Zod schemas ─────────────────────────────────────────────────────────────
 const SaveSchema = zod_1.z.object({
@@ -242,6 +281,15 @@ const SaveSchema = zod_1.z.object({
     tags: zod_1.z.array(zod_1.z.string()).optional(),
     commitMsg: zod_1.z.string().optional(),
     metadata: zod_1.z.string().optional(),
+    workspaceProject: zod_1.z.string().optional(),
+});
+const CodeSessionSchema = zod_1.z.object({
+    project: zod_1.z.string().min(1).max(80),
+    summary: zod_1.z.string().min(1),
+    filesChanged: zod_1.z.array(zod_1.z.string()).max(100).optional(),
+    decisions: zod_1.z.string().optional(),
+    nextSteps: zod_1.z.string().optional(),
+    tags: zod_1.z.array(zod_1.z.string()).optional(),
 });
 const ReadSchema = zod_1.z.object({ key: zod_1.z.string().min(1) });
 const ListSchema = zod_1.z.object({
@@ -280,6 +328,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
@@ -291,11 +368,37 @@ async function handleVaultTool(name, args) {
         case "vault_save": {
             const parsed = SaveSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${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)}`);
-            const savePayload = { ...parsed.data, title: autoTitle };
+            const { workspaceProject, ...rest } = parsed.data;
+            const savePayload = { ...rest, title: autoTitle };
+            // Resolve the project name -> id server-side (auto-creates on first use).
+            // Local vault has no project concept at all - workspaceProject is
+            // silently a no-op there rather than a confusing network error.
+            let resolvedProjectName = null;
+            if (workspaceProject && !localVault) {
+                const resolved = await (0, project_js_1.resolveProjectId)(workspaceProject);
+                if (resolved) {
+                    savePayload.projectId = resolved.projectId;
+                    resolvedProjectName = resolved.name;
+                }
+            }
             const data = localVault
                 ? (0, local_vault_js_1.localVaultSave)(localVault, savePayload)
                 : await (0, convex_js_1.callConvex)("/vault/save", "POST", savePayload, "vault_save");
@@ -335,6 +438,7 @@ async function handleVaultTool(name, args) {
                 `Key: \`${key}\``,
                 `Version: v${version}`,
                 changed && version > 1 ? `Previous version auto-snapshotted.` : "",
+                resolvedProjectName ? `📁 Project: ${resolvedProjectName}` : "",
                 mirrorToMemory ? `🧠 Synced to searchable memory` : (localVault ? `💾 Stored locally at ~/.finch/vault` : ""),
                 ...linkSummary,
                 ``,
@@ -342,10 +446,99 @@ async function handleVaultTool(name, args) {
             ].filter(Boolean);
             return { content: [{ type: "text", text: lines.join("\n") }] };
         }
+        case "code_session_save": {
+            const parsed = CodeSessionSchema.safeParse(args);
+            if (!parsed.success)
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
+            const { project, summary, filesChanged, decisions, nextSteps, tags } = parsed.data;
+            const projectSlug = project.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "session";
+            const key = `code/${projectSlug}`;
+            const content = [
+                `# Code session: ${project}`,
+                ``,
+                `_${new Date().toISOString()}_`,
+                ``,
+                `## Summary`,
+                summary,
+                filesChanged?.length ? `\n## Files changed\n${filesChanged.map((f) => `- \`${f}\``).join("\n")}` : "",
+                decisions ? `\n## Decisions\n${decisions}` : "",
+                nextSteps ? `\n## Next steps\n${nextSteps}` : "",
+            ].filter(Boolean).join("\n");
+            const savePayload = {
+                type: "code",
+                key,
+                title: `Code: ${project}`,
+                content,
+                contentType: "markdown",
+                agentId: "code-session",
+                tags: ["code-session", ...(tags ?? [])],
+                commitMsg: summary.slice(0, 80),
+            };
+            const data = localVault
+                ? (0, local_vault_js_1.localVaultSave)(localVault, savePayload)
+                : await (0, convex_js_1.callConvex)("/vault/save", "POST", savePayload, "vault_save");
+            if (data.error)
+                return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
+            const { version, changed } = data;
+            // Same mirror-to-memory rule as vault_save: skip only when local vault
+            // is on WITHOUT local memory, so query terms never phone home for a
+            // fully offline setup.
+            const mirrorToMemory = !localVault || !!(0, local_memory_js_1.getLocalMemoryConfig)();
+            if (mirrorToMemory) {
+                (0, memory_js_1.syncToSupermemory)(content, {
+                    vaultKey: key, title: savePayload.title, type: "code",
+                    tags: savePayload.tags, version, source: "code_session_save",
+                });
+            }
+            // Auto-link to related past code/research entries - same idea as
+            // deep_research's auto-linking, so a project's session history and any
+            // research that informed it stay connected instead of sitting as
+            // disconnected entries. Purely additive - never blocks the save.
+            const linked = [];
+            try {
+                const searchQuery = `${project} ${summary}`.slice(0, 200);
+                let hits = [];
+                if (localVault) {
+                    const searchResult = (0, local_vault_js_1.localVaultSearch)(localVault, searchQuery, { limit: 6 });
+                    hits = (searchResult.results ?? [])
+                        .filter((r) => !!r.key && r.key !== key)
+                        .map((r) => ({ key: r.key, title: r.title ?? "(untitled)" }));
+                }
+                else {
+                    const searchResult = (await (0, convex_js_1.callConvex)("/vault/search", "POST", { q: searchQuery, n: 8 }, "vault_search"));
+                    hits = (searchResult?.results ?? [])
+                        .map((r) => {
+                        const hitKey = r.metadata?.vaultKey ?? r.metadata?.key ?? null;
+                        return hitKey ? { key: hitKey, title: r.metadata?.title ?? "(untitled)" } : null;
+                    })
+                        .filter((h) => !!h && h.key !== key);
+                }
+                for (const hit of hits.slice(0, 3)) {
+                    try {
+                        if (localVault)
+                            (0, local_vault_js_1.localVaultLink)(localVault, key, hit.key, "related");
+                        else
+                            await (0, convex_js_1.callConvex)("/vault/link", "POST", { fromKey: key, toKey: hit.key, relation: "related" }, "vault_link");
+                        linked.push(hit.key);
+                    }
+                    catch { /* skip individual link failures */ }
+                }
+            }
+            catch { /* auto-link is purely additive */ }
+            const lines = [
+                `📦 **Code session ${changed ? (version === 1 ? "saved" : "updated") : "unchanged"}** - \`${key}\` (v${version})`,
+                filesChanged?.length ? `Files: ${filesChanged.length}` : "",
+                linked.length ? `🔗 Linked to ${linked.length} related entr${linked.length === 1 ? "y" : "ies"}: ${linked.map((k) => `\`${k}\``).join(", ")}` : "",
+                mirrorToMemory ? `🧠 Synced to searchable memory` : "",
+                ``,
+                `Next session: \`vault_read key="${key}"\` for the latest state, or \`vault_history key="${key}"\` for the full timeline.`,
+            ].filter(Boolean);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
         case "vault_read": {
             const parsed = ReadSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const vaultReadKey = parsed.data.key;
             let data;
             try {
@@ -383,27 +576,38 @@ 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")}`
                 : "";
+            // A raw projectId means nothing to a reader - resolve it to a name.
+            // One extra call only when the entry is actually tagged; skipped
+            // entirely for the common case (unassigned) and in local-vault mode.
+            let projectLabel = "";
+            if (data.projectId && !localVault) {
+                try {
+                    const projData = await (0, convex_js_1.callConvex)("/projects/list", "GET", undefined, "list_projects");
+                    const match = projData?.projects?.find((p) => p.id === data.projectId);
+                    if (match)
+                        projectLabel = `📁 Project: ${match.name}`;
+                }
+                catch { /* best-effort - never block the read over this */ }
+            }
             const lines = [
                 `📂 **${data.title}**`,
                 `Key: \`${data.key}\`  ·  Type: ${data.type}  ·  v${data.version}  ·  ${sizeLabel}${data.contentFileId ? " · blob" : ""}`,
                 data.tags?.length ? `Tags: ${data.tags.join(", ")}` : "",
                 data.isPinned ? "📌 Pinned" : "",
                 data.agentId ? `Agent: ${data.agentId}` : "",
+                projectLabel,
                 `Updated: ${formatDate(data.updatedAt)}`,
                 data.linkedKeys?.length ? `\nLinks out:\n${data.linkedKeys.map((l) => `  → ${l}`).join("\n")}` : "",
                 backlinksBlock,
@@ -417,7 +621,7 @@ async function handleVaultTool(name, args) {
         case "vault_list": {
             const parsed = ListSchema.safeParse(args ?? {});
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const params = new URLSearchParams();
             if (parsed.data.type)
                 params.set("type", parsed.data.type);
@@ -433,23 +637,35 @@ 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);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             // Full-text search, proxied through Convex (searchSupermemory is a
             // legacy name - it calls Finch's own /memory/search endpoint, not a
             // third-party semantic service; there is no embedding step here). Large vault
             // 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 +705,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 +716,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,19 +735,26 @@ 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);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const histKey = parsed.data.key;
             let data;
             try {
@@ -568,7 +794,7 @@ async function handleVaultTool(name, args) {
         case "vault_diff": {
             const parsed = DiffSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const { key, fromVersion, toVersion } = parsed.data;
             let data;
             try {
@@ -612,7 +838,7 @@ async function handleVaultTool(name, args) {
         case "vault_export": {
             const parsed = ExportSchema.safeParse(args ?? {});
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const params = parsed.data.type ? `?type=${parsed.data.type}` : "";
             const data = localVault
                 ? (0, local_vault_js_1.localVaultExport)(localVault, parsed.data.type)
@@ -631,7 +857,7 @@ async function handleVaultTool(name, args) {
         case "vault_store_credential": {
             const parsed = StoreCredentialSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const data = localVault
                 ? (0, local_vault_js_1.localVaultStoreCredential)(localVault, parsed.data.name, parsed.data.value, parsed.data.description)
                 : await (0, convex_js_1.callConvex)("/vault/credential/store", "POST", parsed.data, "vault_store_credential");
@@ -642,7 +868,7 @@ async function handleVaultTool(name, args) {
         case "vault_get_credential": {
             const parsed = GetCredentialSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const params = new URLSearchParams({ name: parsed.data.name });
             let data;
             try {
@@ -665,7 +891,7 @@ async function handleVaultTool(name, args) {
         case "vault_pin": {
             const parsed = PinSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const { key, pinned = true } = parsed.data;
             const data = localVault
                 ? (0, local_vault_js_1.localVaultPin)(localVault, key, pinned)
@@ -677,7 +903,7 @@ async function handleVaultTool(name, args) {
         case "vault_unpublish": {
             const parsed = UnpublishSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             // Publishing is a hosted/marketplace concept - a local vault is private
             // by construction, so there is nothing to retract.
             if (localVault) {
@@ -698,7 +924,7 @@ async function handleVaultTool(name, args) {
         case "vault_delete": {
             const parsed = DeleteSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             if (args?.confirm !== true) {
                 return {
                     content: [{
@@ -714,12 +940,26 @@ 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);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const { key, tags, replace = false } = parsed.data;
             const data = localVault
                 ? (0, local_vault_js_1.localVaultTag)(localVault, key, tags, replace)
@@ -731,7 +971,7 @@ async function handleVaultTool(name, args) {
         case "vault_link": {
             const parsed = LinkSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const { fromKey, toKey, relation } = parsed.data;
             const data = localVault
                 ? (0, local_vault_js_1.localVaultLink)(localVault, fromKey, toKey, relation)
@@ -744,7 +984,7 @@ async function handleVaultTool(name, args) {
         case "vault_related": {
             const parsed = RelatedSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const { key, relation } = parsed.data;
             const params = new URLSearchParams({ key });
             if (relation)
@@ -760,6 +1000,20 @@ async function handleVaultTool(name, args) {
             const lines = items.map(r => `- **${r.title}** (\`${r.key}\`) [${r.type}] - ${r.direction} \`${r.relation}\``);
             return { content: [{ type: "text", text: `## Related entries for \`${key}\` (${items.length})\n\n${lines.join("\n")}` }] };
         }
+        case "list_projects": {
+            if (localVault) {
+                return { content: [{ type: "text", text: "Local vault mode has no project concept - `workspaceProject` has no effect, and there's nothing to list here." }] };
+            }
+            const data = await (0, convex_js_1.callConvex)("/projects/list", "GET", undefined, "list_projects");
+            if (data.error)
+                return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
+            const projects = data.projects ?? [];
+            if (!projects.length) {
+                return { content: [{ type: "text", text: "No projects yet. Pass `workspaceProject: \"name\"` to `vault_save` or `agent_spawn` and one is created automatically." }] };
+            }
+            const lines = projects.map((p) => `- **${p.name}** (\`${p.slug}\`)${p.description ? ` - ${p.description}` : ""}`);
+            return { content: [{ type: "text", text: `📁 **Your projects** (${projects.length})\n\n${lines.join("\n")}` }] };
+        }
         default:
             return null;
     }