@finchagentic/mcp 4.1.0 → 4.4.1

package/README.md

@@ -29,13 +29,13 @@ Always pin the version. Never use `@latest`.
 
 ```bash
 # One-command installer (detects common MCP clients)
-npx -y -p @finchagentic/mcp@4.1.0 finch install
+npx -y -p @finchagentic/mcp@4.4.1 finch install
 ```
 
 ### Claude Code
 
 ```bash
-claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.1.0 finch-mcp
+claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.4.1 finch-mcp
 ```
 
 ### Cursor / Windsurf / Claude Desktop
@@ -45,7 +45,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.1.0 finch-mcp
   "mcpServers": {
     "finch": {
       "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.1.0", "finch-mcp"]
+      "args": ["-y", "-p", "@finchagentic/mcp@4.4.1", "finch-mcp"]
     }
   }
 }
@@ -59,7 +59,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.1.0 finch-mcp
     "finch": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.1.0", "finch-mcp"]
+      "args": ["-y", "-p", "@finchagentic/mcp@4.4.1", "finch-mcp"]
     }
   }
 }
@@ -79,7 +79,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.1.0 finch-mcp
 
 </details>
 
-No LLM API key is required to start — 116 of 121 tools are plain reads/writes/on-chain calls that your MCP client's own model already drives; only 5 (`ask_finch`, `deep_research`, and scheduled agent learning) do their own multi-step reasoning server-side and need a key (see [Configuration](#configuration)). Tools load on first use.
+No LLM API key is required to start — 111 of 116 tools are plain reads/writes/on-chain calls that your MCP client's own model already drives; only 5 (`ask_finch`, `deep_research`, and scheduled agent learning) do their own multi-step reasoning server-side and need a key (see [Configuration](#configuration)). Tools load on first use.
 
 ## Quick start
 
@@ -93,21 +93,25 @@ Try in your MCP client:
 
 ```
 remember: I prefer conservative DeFi strategies, max 5% risk
-spawn an agent called research-bot to track AI agent news weekly
+spawn an agent called research-bot to track AI agent news, update it after each session
 save this thesis to vault
 ```
 
 ## What you get
 
-**121 tools** across four pillars:
+**116 tools** across four pillars:
 
 | Pillar | What it does |
 |--------|----------------|
 | **Memory** | Full-text searchable memory + versioned vault + chronicle |
-| **Agents** | Spawn, recall, update, schedule named agents |
-| **Workflows** | Automations, monitors, packets, deep research |
+| **Agents** | Spawn, recall, update named agents — `agent_recall` also pulls related memory/vault context matching the agent's goal, not just its own logged updates |
+| **Workflows** | Automations, monitors, packets, deep research (auto-saves reports + auto-links related past research) |
 | **Execution** | Base DeFi, Robinhood Chain, market data, web, GitHub |
 
+Coding and research sessions persist the same way: `deep_research` auto-saves its report to vault and links it to related past reports; `code_session_save` does the same for coding/debugging sessions (`vault_save type=code`, versioned per project, auto-linked). Both exist so the next session — yours or another agent's — starts with real context instead of cold.
+
+`vault_save` and `agent_spawn` also take an optional `workspaceProject` - the same named Projects a user organizes their Agents/vault content into on the webapp's Agents page. Pass a name and it's matched case-insensitively or created automatically (`list_projects` to browse what exists first). Hosted vault only - local-vault mode has no project concept.
+
 Default palette is `core` (lighter context). Full set:
 
 ```json
@@ -119,7 +123,7 @@ Default palette is `core` (lighter context). Full set:
 Finch is the runtime. **Your LLM is the brain. Your data stays yours.**
 
 ```bash
-npx -y -p @finchagentic/mcp@4.1.0 finch setup
+npx -y -p @finchagentic/mcp@4.4.1 finch setup
 # enable local vault (and optional local memory)
 ```
 
@@ -146,12 +150,12 @@ Scheduled/cloud features still need an account. Core memory, vault, and public-d
 | `GITHUB_TOKEN` | For `github_search_code` |
 | `ALCHEMY_API_KEY` | Faster Base RPC (optional) |
 
-**Cost model:** almost everything is free to run — the other 116 tools are plain API/RPC calls, and your MCP client's own model (Claude, GPT, whatever's driving the chat) does all the tool-selection reasoning at no cost to Finch. The 5 exceptions above need their own key because their reasoning happens *inside* the tool call, invisible to your client, and can't be delegated to it. Set exactly one of the four env vars and every tool that needs it will use it automatically.
+**Cost model:** almost everything is free to run — the other 110 tools are plain API/RPC calls, and your MCP client's own model (Claude, GPT, whatever's driving the chat) does all the tool-selection reasoning at no cost to Finch. The 5 exceptions above need their own key because their reasoning happens *inside* the tool call, invisible to your client, and can't be delegated to it. Set exactly one of the four env vars and every tool that needs it will use it automatically.
 
 Guided setup:
 
 ```bash
-npx -y -p @finchagentic/mcp@4.1.0 finch setup
+npx -y -p @finchagentic/mcp@4.4.1 finch setup
 ```
 
 ## Security
@@ -160,12 +164,12 @@ npx -y -p @finchagentic/mcp@4.1.0 finch setup
 |:-:|----------|------|
 | 1 | Prompt injection | External content is data only — never instructions |
 | 2 | Mainnet confirm | Estimate → preview → confirm → execute |
-| 3 | Pinned install | Always `@finchagentic/mcp@4.1.0`, never `@latest` |
+| 3 | Pinned install | Always `@finchagentic/mcp@4.4.1`, never `@latest` |
 | 4 | Credential vault | Never paste secrets into prompts or third-party tools |
 | 5 | Data disclosure | Know what leaves the machine (LLM, Firecrawl, GitHub, chain RPCs) |
 | 6 | Server monitors | Scheduled jobs need explicit confirmation |
-| 7 | Agent schedules | `agent_schedule` confirms cost + side effects |
-| 8 | Identity custody | Do not send assets to agent identity addresses |
+| 7 | Fund-moving confirm | `stake_finch`/`unstake_finch`/`base_mcp_send`/`base_mcp_swap`/`rh_mcp_swap` all require `confirm: true` |
+| 8 | Local wallet encryption | Set `FINCH_WALLET_PASSPHRASE` for a portable, passphrase-derived key — without it, the key derives from a random per-install secret + machine info, so the wallet file alone (without that secret file) isn't enough to decrypt it |
 
 ## Troubleshooting
 

package/dist/agent-loop.js

@@ -32,6 +32,7 @@ async function runAgent(userMessage, history, onToolCall) {
     const bankrKey = process.env.BANKR_API_KEY;
     const anthropicKey = process.env.ANTHROPIC_API_KEY;
     const openaiKey = process.env.OPENAI_API_KEY;
+    const grokKey = process.env.GROK_API_KEY;
     // Explicit override - lets FINCH_PROVIDER=openai win even when BANKR_API_KEY
     // is also set (e.g. as a persistent shell env var), same as llm.ts's callLLM.
     if (provider === "bankr" && bankrKey)
@@ -40,13 +41,22 @@ async function runAgent(userMessage, history, onToolCall) {
         return runAnthropicLoop(anthropicKey, userMessage, history, onToolCall);
     if (provider === "openai" && openaiKey)
         return runOpenAILoop(openaiKey, userMessage, history, onToolCall);
-    // Auto-priority
+    if (provider === "grok" && grokKey)
+        return runGrokLoop(grokKey, userMessage, history, onToolCall);
+    // Auto-priority - matches llm.ts's callLLM() order exactly (bankr →
+    // anthropic → openai → grok → Convex proxy) so a one-shot LLM tool call
+    // (ask_finch, memory extraction, etc.) and the interactive agent loop
+    // never silently pick different providers for the same configured keys.
+    // A GROK_API_KEY-only user used to fall all the way through to the
+    // Convex-proxied Anthropic loop here despite callLLM() using Grok.
     if (bankrKey)
         return runBankrLoop(bankrKey, userMessage, history, onToolCall);
     if (anthropicKey)
         return runAnthropicLoop(anthropicKey, userMessage, history, onToolCall);
     if (openaiKey)
         return runOpenAILoop(openaiKey, userMessage, history, onToolCall);
+    if (grokKey)
+        return runGrokLoop(grokKey, userMessage, history, onToolCall);
     // No direct key - proxy through Finch backend. Wallet auto-creates at ~/.finch/wallet.json
     // on first use and signs requests transparently. No account or config needed.
     try {
@@ -66,8 +76,14 @@ function toAnthropicTool(tool) {
         input_schema: tool.inputSchema ?? { type: "object", properties: {} },
     };
 }
-async function runAnthropicLoop(apiKey, userMessage, history, onToolCall) {
-    const model = process.env.FINCH_MODEL ?? process.env.ANTHROPIC_MODEL ?? "claude-haiku-4-5-20251001";
+// Shared loop body for any provider that speaks Anthropic's native
+// content-block format (tool_use/tool_result) - runAnthropicLoop (direct
+// api.anthropic.com) and runConvexProxiedLoop (same wire format via Finch's
+// /llm/complete proxy) previously duplicated this ~70-line body verbatim,
+// with only the transport (sendTurn/sendFinal) differing. Keeping one copy
+// means a future fix (retry-on-5xx, tool-result truncation, etc.) can't be
+// applied to one provider and silently miss the other.
+async function runAnthropicStyleLoop(sendTurn, sendFinal, userMessage, history, onToolCall) {
     const tools = server_js_1.ALL_TOOLS.map(toAnthropicTool);
     const toolCalls = [];
     const messages = [
@@ -75,21 +91,7 @@ async function runAnthropicLoop(apiKey, userMessage, history, onToolCall) {
         { role: "user", content: userMessage },
     ];
     for (let turn = 0; turn < 10; turn++) {
-        const res = await fetch("https://api.anthropic.com/v1/messages", {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "x-api-key": apiKey,
-                "anthropic-version": "2023-06-01",
-            },
-            body: JSON.stringify({ model, max_tokens: 4096, system: SYSTEM_PROMPT, tools, messages }),
-            signal: AbortSignal.timeout(90000),
-        });
-        if (!res.ok) {
-            const body = await res.text().catch(() => "");
-            throw new Error(`Anthropic ${res.status}: ${body.slice(0, 300)}`);
-        }
-        const data = await res.json();
+        const data = await sendTurn(messages, tools);
         messages.push({ role: "assistant", content: data.content });
         if (data.stop_reason !== "tool_use") {
             const text = data.content
@@ -103,15 +105,27 @@ async function runAnthropicLoop(apiKey, userMessage, history, onToolCall) {
         for (const block of data.content) {
             if (block.type !== "tool_use")
                 continue;
-            onToolCall(block.name);
-            toolCalls.push({ name: block.name });
             let resultText;
             try {
                 const handler = server_js_1.HANDLER_MAP.get(block.name);
                 if (!handler)
                     throw new Error(`Unknown tool: ${block.name}`);
+                // Recorded only once the handler is confirmed to exist - an "Unknown
+                // tool" miss is a model error, not a real tool execution, and callers
+                // reading AgentResult.toolCalls should be able to trust every entry
+                // actually ran.
+                onToolCall(block.name);
+                toolCalls.push({ name: block.name });
                 const result = await handler(block.name, block.input ?? {});
-                resultText = result?.content?.[0]?.text ?? "Done.";
+                // A handler returning null (a name declared in its *_TOOLS array with
+                // no matching branch - a latent bug ruled out today but not
+                // structurally prevented) must not fall through to "Done." - that
+                // would report success to the model for a call that never actually
+                // ran, directly contradicting this loop's own system-prompt rule
+                // against claiming an unverified result.
+                if (result === null)
+                    throw new Error(`Tool ${block.name} returned no result (handler bug - not executed)`);
+                resultText = result.content?.[0]?.text ?? "Done.";
             }
             catch (err) {
                 resultText = `Error: ${err.message}`;
@@ -123,7 +137,28 @@ async function runAnthropicLoop(apiKey, userMessage, history, onToolCall) {
     // Hit the turn cap without a final answer - rather than hand back nothing,
     // force one more call with no tools available so the model has to
     // synthesize a real answer from whatever it already gathered.
-    return finishWithoutTools(async (msgs) => {
+    return finishWithoutTools(sendFinal, messages, toolCalls);
+}
+function runAnthropicLoop(apiKey, userMessage, history, onToolCall) {
+    const model = process.env.FINCH_MODEL ?? process.env.ANTHROPIC_MODEL ?? "claude-haiku-4-5-20251001";
+    const sendTurn = async (messages, tools) => {
+        const res = await fetch("https://api.anthropic.com/v1/messages", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": apiKey,
+                "anthropic-version": "2023-06-01",
+            },
+            body: JSON.stringify({ model, max_tokens: 4096, system: SYSTEM_PROMPT, tools, messages }),
+            signal: AbortSignal.timeout(90000),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`Anthropic ${res.status}: ${body.slice(0, 300)}`);
+        }
+        return await res.json();
+    };
+    const sendFinal = async (msgs) => {
         const res = await fetch("https://api.anthropic.com/v1/messages", {
             method: "POST",
             headers: { "Content-Type": "application/json", "x-api-key": apiKey, "anthropic-version": "2023-06-01" },
@@ -134,7 +169,8 @@ async function runAnthropicLoop(apiKey, userMessage, history, onToolCall) {
             return "";
         const data = await res.json();
         return (data.content ?? []).filter(b => b.type === "text").map(b => b.text).join("");
-    }, messages, toolCalls);
+    };
+    return runAnthropicStyleLoop(sendTurn, sendFinal, userMessage, history, onToolCall);
 }
 // Shared turn-cap fallback: rather than "Reached max tool iterations." with
 // nothing useful, ask the model to synthesize a real answer from whatever
@@ -157,58 +193,17 @@ async function finishWithoutTools(call, messages, toolCalls) {
     };
 }
 // ── Convex-proxied Anthropic loop (session token only - platform covers LLM) ──
-async function runConvexProxiedLoop(userMessage, history, onToolCall) {
+function runConvexProxiedLoop(userMessage, history, onToolCall) {
     const model = process.env.FINCH_MODEL ?? process.env.ANTHROPIC_MODEL ?? "claude-haiku-4-5-20251001";
-    const tools = server_js_1.ALL_TOOLS.map(toAnthropicTool);
-    const toolCalls = [];
-    const messages = [
-        ...history.map(h => ({ role: h.role, content: h.content })),
-        { role: "user", content: userMessage },
-    ];
-    for (let turn = 0; turn < 10; turn++) {
-        // callConvex handles wallet/session auth automatically; 90s timeout matches the proxy endpoint
-        const data = await (0, convex_js_1.callConvex)("/llm/complete", "POST", {
-            model,
-            max_tokens: 4096,
-            system: SYSTEM_PROMPT,
-            tools,
-            messages,
-        }, "llm_complete", 90000);
-        messages.push({ role: "assistant", content: data.content });
-        if (data.stop_reason !== "tool_use") {
-            const text = data.content
-                .filter(b => b.type === "text")
-                .map(b => b.text)
-                .join("");
-            return { text, toolCalls };
-        }
-        const toolResults = [];
-        for (const block of data.content) {
-            if (block.type !== "tool_use")
-                continue;
-            onToolCall(block.name);
-            toolCalls.push({ name: block.name });
-            let resultText;
-            try {
-                const handler = server_js_1.HANDLER_MAP.get(block.name);
-                if (!handler)
-                    throw new Error(`Unknown tool: ${block.name}`);
-                const result = await handler(block.name, block.input ?? {});
-                resultText = result?.content?.[0]?.text ?? "Done.";
-            }
-            catch (err) {
-                resultText = `Error: ${err.message}`;
-            }
-            toolResults.push({ type: "tool_result", tool_use_id: block.id, content: resultText });
-        }
-        messages.push({ role: "user", content: toolResults });
-    }
-    return finishWithoutTools(async (msgs) => {
+    // callConvex handles wallet/session auth automatically; 90s timeout matches the proxy endpoint
+    const sendTurn = (messages, tools) => (0, convex_js_1.callConvex)("/llm/complete", "POST", { model, max_tokens: 4096, system: SYSTEM_PROMPT, tools, messages }, "llm_complete", 90000);
+    const sendFinal = async (msgs) => {
         const data = await (0, convex_js_1.callConvex)("/llm/complete", "POST", {
             model, max_tokens: 4096, system: SYSTEM_PROMPT, messages: msgs,
         }, "llm_complete", 90000);
         return (data.content ?? []).filter((b) => b.type === "text").map((b) => b.text).join("");
-    }, messages, toolCalls);
+    };
+    return runAnthropicStyleLoop(sendTurn, sendFinal, userMessage, history, onToolCall);
 }
 // ── Bankr (OpenAI-compatible) agent loop ─────────────────────────────────────
 function toBankrTool(tool) {
@@ -252,14 +247,16 @@ async function runOpenAICompatibleLoop(url, authHeaders, model, providerLabel, u
             return { text: choice.content ?? "", toolCalls };
         }
         for (const call of choice.tool_calls) {
-            onToolCall(call.function.name);
-            toolCalls.push({ name: call.function.name });
             let resultText;
             try {
                 const args = JSON.parse(call.function.arguments ?? "{}");
                 const handler = server_js_1.HANDLER_MAP.get(call.function.name);
                 if (!handler)
                     throw new Error(`Unknown tool: ${call.function.name}`);
+                // Recorded only once the handler is confirmed to exist - see the
+                // matching comment in runAnthropicLoop/runConvexProxiedLoop.
+                onToolCall(call.function.name);
+                toolCalls.push({ name: call.function.name });
                 const result = await handler(call.function.name, args);
                 resultText = result?.content?.[0]?.text ?? "Done.";
             }
@@ -296,3 +293,9 @@ async function runOpenAILoop(apiKey, userMessage, history, onToolCall) {
     const model = process.env.FINCH_MODEL ?? process.env.OPENAI_MODEL ?? "gpt-4o-mini";
     return runOpenAICompatibleLoop(openAiChatUrl(), { Authorization: `Bearer ${apiKey}` }, model, "OpenAI", userMessage, history, onToolCall);
 }
+// xAI's Chat Completions API is OpenAI-compatible (same as llm.ts's callGrok),
+// so this reuses runOpenAICompatibleLoop rather than a bespoke loop.
+async function runGrokLoop(apiKey, userMessage, history, onToolCall) {
+    const model = process.env.FINCH_MODEL ?? process.env.FINCH_GROK_MODEL ?? process.env.GROK_MODEL ?? "grok-4-fast-reasoning";
+    return runOpenAICompatibleLoop("https://api.x.ai/v1/chat/completions", { Authorization: `Bearer ${apiKey}` }, model, "Grok", userMessage, history, onToolCall);
+}

package/dist/annotations.js

@@ -14,32 +14,23 @@ const READ_ONLY_LOCAL = new Set([
 // Toggles and upserts: re-running with the same args lands in the same state.
 const WRITE_IDEMPOTENT = new Set([
     "agent_update",
-    "agent_schedule",
-    "agent_pause",
-    "agent_resume",
-    "agent_unschedule",
     "pause_automation",
+    "stake_auto_restake",
     "vault_link",
     "vault_pin",
     "vault_tag",
     "vault_unpublish",
-    "wallet_sign_message", // signing is not itself a fund move; re-sign = same sig
 ]);
 // readOnly=false, destructive=false.
 // Additive writes / new resources: they create or append, they don't destroy.
-// (hire_agent is deliberately NOT here: it only returns a specialist persona
-// scoped to the caller's task - it reads, it does not write - so it stays in
-// the read-only default.)
 const WRITE = new Set([
     "agent_spawn",
     "chronicle_add",
-    "create_automation",
-    "create_monitor",
+    "code_session_save",
     "memory_add",
     "memory_extract",
     "memory_consolidate",
     "packet_create",
-    "packet_share",
     "schedule_research",
     "vault_save",
     "vault_store_credential",
@@ -58,20 +49,38 @@ const DESTRUCTIVE = new Set([
     "rh_order_cancel",
     "vault_delete",
     // irreversible public exposure
-    "memory_publish", // "IRREVERSIBLE, PUBLIC" per its own description
+    "packet_share", // "copies already taken remain" per its own description
     // money movement (Base)
+    // NOTE: base_mcp_lend deliberately excluded - per its own description it
+    // "Returns deposit INSTRUCTIONS only... Does NOT broadcast" - it's a read,
+    // not a fund move, so it falls through to the read-only default below.
     "base_mcp_send",
     "base_mcp_swap",
-    "base_mcp_lend",
+    // off-chain signature that can itself authorise value movement (order,
+    // session login) without any on-chain tx - same risk class as a real
+    // transfer per its own tool description, so it belongs here rather than
+    // in WRITE_IDEMPOTENT ("re-sign = same sig" is true but undersells the risk)
+    "wallet_sign_message",
     // money movement (Robinhood Chain)
     "rh_mcp_swap",
     "rh_dca_create", // arms recurring real buys
     "rh_bracket_create", // arms real TP/SL sells
+    // a swap/send automation arms unattended, REPEATING real fund movement
+    // (the backend's 1-minute cron evaluator fires it) - same risk class as
+    // rh_dca_create/rh_bracket_create above, not a plain additive write. An
+    // alert-only automation doesn't move funds, but the tool can't tell which
+    // kind it's about to create until AFTER the backend parses rawInput, so
+    // it's classified by its worst case, same reasoning as rh_orders_tick.
+    "create_automation",
     "rh_orders_tick", // preview by default, but can execute:true and move funds
     // executors that run other (possibly fund-moving) tools
     "run_automation",
-    "run_playbook",
     "packet_run",
+    // money movement (FINCH staking, custodial wallet) - stake locks real value
+    // for a fixed period; unstake moves it (plus rewards) back
+    "stake_finch",
+    "unstake_finch",
+    "claim_vested_rewards", // treasury -> custodial wallet USDG transfer
 ]);
 function annotationsFor(name) {
     if (DESTRUCTIVE.has(name)) {

package/dist/convex.js

@@ -4,7 +4,6 @@ exports.PaymentRequiredError = exports.CONVEX_SITE = void 0;
 exports.buildPaymentHeader = buildPaymentHeader;
 exports.callConvex = callConvex;
 exports.callConvexRaw = callConvexRaw;
-exports.notifyTelegram = notifyTelegram;
 const wallet_js_1 = require("./wallet.js");
 const config_js_1 = require("./config.js");
 exports.CONVEX_SITE = process.env.FINCH_CONVEX_URL ?? "https://befitting-porcupine-276.convex.site";
@@ -66,10 +65,6 @@ async function callConvex(path, method, body, toolName = "unknown", timeoutMs =
         headers["X-User-Grok-Key"] = process.env.GROK_API_KEY;
     if (process.env.BANKR_API_KEY)
         headers["X-User-Bankr-Key"] = process.env.BANKR_API_KEY;
-    if (process.env.TELEGRAM_BOT_TOKEN)
-        headers["X-User-Telegram-Token"] = process.env.TELEGRAM_BOT_TOKEN;
-    if (process.env.TELEGRAM_CHAT_ID)
-        headers["X-User-Telegram-Chat"] = process.env.TELEGRAM_CHAT_ID;
     let lastError = null;
     for (let attempt = 0; attempt < RETRY_DELAYS.length; attempt++) {
         if (attempt > 0) {
@@ -95,7 +90,13 @@ async function callConvex(path, method, body, toolName = "unknown", timeoutMs =
                 `${b.alternative ? `Alternative: ${b.alternative}` : ""}`);
         }
         if (RETRY_STATUSES.has(res.status) && attempt < RETRY_DELAYS.length) {
-            lastError = new Error(`Finch API error: ${res.status}`);
+            // Capture the actual body so a deterministic error (e.g. "unknown
+            // token") that happens to come back on a 500 still surfaces its real
+            // message if retries exhaust - previously this discarded the body
+            // entirely and threw a bare "Finch API error: 500", hiding exactly the
+            // information the caller needed to fix the request.
+            const bodyText = await res.text().catch(() => "");
+            lastError = new Error(`Finch API error ${res.status}: ${bodyText.slice(0, 300) || "(no body)"}`);
             continue;
         }
         if (!res.ok)
@@ -112,10 +113,14 @@ async function callConvexRaw(path, toolName = "unknown", timeoutMs = 60000) {
     const headers = {};
     const apiKey = process.env.FINCH_API_KEY;
     const sessionToken = (0, config_js_1.getSavedToken)();
-    const authHeader = apiKey
-        ? `Bearer ${apiKey}`
-        : sessionToken
-            ? `Bearer ${sessionToken}`
+    // Same precedence as callConvex() above - prefer session token over API
+    // key. These two functions previously disagreed (this one checked apiKey
+    // first), so the same env/config could pick a different credential
+    // depending on which helper a tool happened to call.
+    const authHeader = sessionToken
+        ? `Bearer ${sessionToken}`
+        : apiKey
+            ? `Bearer ${apiKey}`
             : null;
     if (authHeader) {
         headers["Authorization"] = authHeader;
@@ -141,11 +146,3 @@ async function callConvexRaw(path, toolName = "unknown", timeoutMs = 60000) {
         throw new Error(`Finch API error: ${res.status}`);
     return res.text();
 }
-async function notifyTelegram(userId, message) {
-    try {
-        return await callConvex("/user/telegram/notify", "POST", { userId, message }, "set_telegram");
-    }
-    catch (error) {
-        return { sent: false, reason: error.message ?? String(error) };
-    }
-}

package/dist/index.js

@@ -66,14 +66,17 @@ const C = {
     reset: "\x1b[0m",
     bold: "\x1b[1m",
 };
+// Was still spelling out the pre-rebrand "NOELCLAW" wordmark in ASCII art -
+// leftover from before the Finch rebrand, never caught because nothing
+// visually diffs a banner string.
 const BANNER = `
 ${C.cyan}
-  ███╗   ██╗ ██████╗ ███████╗██╗      ██████╗██╗      █████╗ ██╗    ██╗
-  ████╗  ██║██╔═══██╗██╔════╝██║     ██╔════╝██║     ██╔══██╗██║    ██║
-  ██╔██╗ ██║██║   ██║█████╗  ██║     ██║     ██║     ███████║██║ █╗ ██║
-  ██║╚██╗██║██║   ██║██╔══╝  ██║     ██║     ██║     ██╔══██║██║███╗██║
-  ██║ ╚████║╚██████╔╝███████╗███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝
-  ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝
+  ███████╗██╗███╗   ██╗ ██████╗██╗  ██╗
+  ██╔════╝██║████╗  ██║██╔════╝██║  ██║
+  █████╗  ██║██╔██╗ ██║██║     ███████║
+  ██╔══╝  ██║██║╚██╗██║██║     ██╔══██║
+  ██║     ██║██║ ╚████║╚██████╗██║  ██║
+  ╚═╝     ╚═╝╚═╝  ╚═══╝ ╚═════╝╚═╝  ╚═╝
 ${C.reset}`;
 function line(label, value, color = C.cyan) {
     const pad = " ".repeat(Math.max(0, 12 - label.length));
@@ -108,24 +111,23 @@ async function main() {
     (0, config_js_1.hydrateEnvFromConfig)();
     process.stderr.write(BANNER);
     const CAT_RULES = [
-        { label: "Market", match: n => /^(get_market_data|get_token_data|compare_tokens|market_overview|token_history)$/.test(n) },
+        { label: "Market", match: n => /^(get_market_data|get_token_data|compare_tokens|market_overview|token_history|get_base_token_data|stock_fundamentals|stock_insider|stock_events)$/.test(n) },
         { label: "Insight", match: n => /^(ask_finch|market_thesis|trade_plan)$/.test(n) },
         { label: "DeFi", match: n => n === "get_defi_yields" },
         { label: "Base MCP", match: n => n.startsWith("base_mcp_") },
         { label: "RH MCP", match: n => n.startsWith("rh_") },
         { label: "Automation", match: n => /^(create_automation|list_automations|pause_automation|delete_automation|get_automation_runs|run_automation)$/.test(n) },
-        { label: "Framework", match: n => /^(list_playbooks|run_playbook|get_finch_ledger)$/.test(n) },
-        { label: "Vault", match: n => n.startsWith("vault_") },
+        { label: "Vault", match: n => n.startsWith("vault_") || n === "code_session_save" || n === "list_projects" },
         { label: "Wallet", match: n => /^(get_wallet_address|get_wallet_balance|wallet_sign_message)$/.test(n) },
+        { label: "Staking", match: n => /^(stake_finch|unstake_finch|stake_finch_status|stake_auto_restake|claim_vested_rewards)$/.test(n) },
         { label: "MiroShark", match: n => n.startsWith("miroshark_") },
         { label: "Scanner", match: n => /^(scan_market|score_token|check_token)$/.test(n) },
-        { label: "Agents", match: n => n.startsWith("agent_") || n === "list_agents" || n === "hire_agent" },
+        { label: "Agents", match: n => n.startsWith("agent_") },
         { label: "Coder", match: n => n === "audit_contract" },
-        { label: "Base", match: n => /^(query_vaults|list_markets|prepare_deposit|chain_stats)$/.test(n) },
         { label: "Memory", match: n => n.startsWith("memory_") },
         { label: "OS", match: n => /^(finch_status|finch_diagnostics|finch_shell_chat)$/.test(n) },
         { label: "Research", match: n => /^(web_scrape|web_search|deep_research|research_compare|research_chain)$/.test(n) },
-        { label: "Monitor", match: n => /^(schedule_research|create_monitor|list_monitors|cancel_monitor)$/.test(n) },
+        { label: "Monitor", match: n => /^(schedule_research|list_monitors|cancel_monitor)$/.test(n) },
         { label: "GitHub", match: n => n.startsWith("github_") },
         { label: "Chronicle", match: n => n.startsWith("chronicle_") },
         { label: "Packets", match: n => n.startsWith("packet_") },

package/dist/llm.js

@@ -227,7 +227,18 @@ async function callOpenAI(apiKey, systemPrompt, userPrompt, maxTokens, history,
         throw new Error(`OpenAI error ${res.status}: ${body.slice(0, 200)}`);
     }
     const data = await res.json();
-    return data.choices?.[0]?.message?.content ?? "";
+    // Most OpenAI-compatible gateways put `choices` at the top level, but
+    // OPENAI_BASE_URL can point at anything that speaks this API shape - at
+    // least one (9Router) wraps the whole payload in `{ data: {...}, success:
+    // true }` for some models (confirmed live: routers9/glm5.2 returns this
+    // wrapper while routers9/tencent/hy3 on the SAME endpoint/key returns
+    // top-level choices). Without this fallback the call silently returns ""
+    // instead of throwing - worse than an error, since every caller of
+    // callLLM() just gets an empty synthesis with no indication anything failed.
+    const content = data.choices?.[0]?.message?.content ?? data.data?.choices?.[0]?.message?.content;
+    if (!content)
+        throw new Error(`OpenAI-compatible endpoint returned no content (model: ${model})`);
+    return content;
 }
 async function callGrok(apiKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, liveSearch, modelOverride) {
     const model = modelOverride ?? process.env.FINCH_MODEL ?? process.env.GROK_MODEL ?? "grok-4-fast-reasoning";

package/dist/local-memory-file.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLocalMemoryFileConfig = getLocalMemoryFileConfig;
 exports.fileMemoryAdd = fileMemoryAdd;
+exports.fileMemoryDeleteByVaultKey = fileMemoryDeleteByVaultKey;
 exports.fileMemorySearch = fileMemorySearch;
 exports.fileMemoryList = fileMemoryList;
 exports.fileMemoryDelete = fileMemoryDelete;
@@ -71,7 +72,7 @@ function toResult(m) {
     return {
         id: m.id,
         content: m.content,
-        metadata: { title: m.title, tags: m.tags, source: m.source, sourceUrl: m.sourceUrl, contentHash: m.contentHash, pinned: m.pinned, addedAt: m.addedAt },
+        metadata: { title: m.title, tags: m.tags, source: m.source, sourceUrl: m.sourceUrl, contentHash: m.contentHash, pinned: m.pinned, addedAt: m.addedAt, vaultKey: m.vaultKey },
     };
 }
 function fileMemoryAdd(cfg, content, metadata, sourceUrl) {
@@ -87,11 +88,23 @@ function fileMemoryAdd(cfg, content, metadata, sourceUrl) {
         contentHash: metadata.contentHash ?? "",
         pinned: metadata.pinned,
         addedAt: metadata.addedAt ?? Date.now(),
+        vaultKey: metadata.vaultKey,
     };
     idx.memories.push(row);
     writeIndex(cfg, idx);
     return { id };
 }
+/** Remove every memory row mirroring a given vault entry - called by
+ * vault_delete so its "PERMANENT... cannot be undone" claim is actually true,
+ * instead of leaving the content fully recoverable via memory_search. */
+function fileMemoryDeleteByVaultKey(cfg, vaultKey) {
+    const idx = readIndex(cfg);
+    const next = idx.memories.filter((m) => m.vaultKey !== vaultKey);
+    const removed = idx.memories.length - next.length;
+    if (removed > 0)
+        writeIndex(cfg, { memories: next });
+    return removed;
+}
 function fileMemorySearch(cfg, query, limit) {
     const idx = readIndex(cfg);
     const terms = query.toLowerCase().split(/\s+/).filter(Boolean);

package/dist/local-memory.js

@@ -6,6 +6,7 @@ exports.localMemoryAdd = localMemoryAdd;
 exports.localMemorySearch = localMemorySearch;
 exports.localMemoryList = localMemoryList;
 exports.localMemoryDelete = localMemoryDelete;
+exports.localMemoryDeleteByVaultKey = localMemoryDeleteByVaultKey;
 exports.localMemoryProfile = localMemoryProfile;
 const config_js_1 = require("./config.js");
 const local_memory_file_js_1 = require("./local-memory-file.js");
@@ -109,6 +110,18 @@ async function localMemoryDelete(cfg, id) {
     if (!res.ok)
         throw new Error(`local supermemory delete failed: HTTP ${res.status}`);
 }
+/**
+ * Remove memory rows mirroring a deleted vault entry - called by vault_delete.
+ * "file" backend: direct filter+delete, exact. Self-hosted supermemory server:
+ * no documented "delete by metadata filter" endpoint, so this is a no-op that
+ * returns 0 rather than guessing at an unconfirmed API - vault_delete surfaces
+ * that count so a 0 on that backend doesn't get silently mistaken for success.
+ */
+function localMemoryDeleteByVaultKey(cfg, vaultKey) {
+    if (cfg.kind === "file")
+        return (0, local_memory_file_js_1.fileMemoryDeleteByVaultKey)(cfg, vaultKey);
+    return 0;
+}
 // No dedicated count endpoint is documented for the local supermemory server,
 // so that path approximates via a capped wildcard search - accurate up to
 // `PROFILE_SAMPLE_LIMIT`, reported as a floor ("200+") beyond that rather