@finchagentic/mcp 4.6.1 → 4.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finchagentic/mcp",
-  "version": "4.6.1",
+  "version": "4.6.2",
   "description": "The runtime layer for Agentic AI. Persistent memory, autonomous agents, and workflows that survive every session.",
   "main": "dist/index.js",
   "bin": {
@@ -14,9 +14,7 @@
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:mutation": "node scripts/mutation-check.js",
-    "prepare": "husky",
-    "prepublishOnly": "npm run build && node scripts/version-readme.js"
+    "test:mutation": "node scripts/mutation-check.js"
   },
   "lint-staged": {
     "*.{ts,tsx}": "eslint --fix"
@@ -70,5 +68,6 @@
   },
   "publishConfig": {
     "access": "public"
-  }
-}
+  },
+  "mcpName": "io.github.finchagentic/mcp"
+}

package/dist/_http-cache.js

@@ -1,96 +0,0 @@
-"use strict";
-// Shared cache + 429-backoff wrapper for external HTTP calls.
-// Designed for read-heavy public APIs like CoinGecko (free tier: 30 req/min)
-// and DexScreener - agent loops + parallel tool calls were tripping rate
-// limits in production. Cache hit returns the prior body without a network
-// round-trip; cache miss does a fetch with bounded retries on 429/503.
-//
-// The cache is in-process only - every MCP server process keeps its own
-// LRU. That's intentional: tokens get fresh data on cold start, no shared
-// state to invalidate across users.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.cachedFetch = cachedFetch;
-exports.clearHttpCache = clearHttpCache;
-exports.httpCacheStats = httpCacheStats;
-const DEFAULT_TTL_MS = 45000; // 45s - fresh enough for prices, generous enough to absorb a flurry
-const DEFAULT_MAX_ENTRIES = 200;
-const DEFAULT_RETRY_DELAYS_MS = [500, 1500, 4000];
-const cache = new Map();
-function cacheKey(url, init) {
-    // POST bodies are part of the key so two POSTs with different params don't collide.
-    if (!init || !init.body || init.method === "GET")
-        return `GET ${url}`;
-    return `${init.method ?? "POST"} ${url} ${typeof init.body === "string" ? init.body : ""}`;
-}
-function evictExpired() {
-    const now = Date.now();
-    for (const [k, v] of cache) {
-        if (v.expiresAt < now)
-            cache.delete(k);
-    }
-    // LRU-ish eviction - Map preserves insertion order, so the first keys are oldest.
-    while (cache.size > DEFAULT_MAX_ENTRIES) {
-        const firstKey = cache.keys().next().value;
-        if (firstKey === undefined)
-            break;
-        cache.delete(firstKey);
-    }
-}
-async function cachedFetch(url, init = {}, opts = {}) {
-    const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
-    const retryDelays = opts.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
-    const timeout = opts.timeoutMs ?? 15000;
-    evictExpired();
-    const key = cacheKey(url, init);
-    if (!opts.bypassCache) {
-        const hit = cache.get(key);
-        if (hit && hit.expiresAt > Date.now()) {
-            // Refresh recency - re-insert moves it to the end of the Map.
-            cache.delete(key);
-            cache.set(key, hit);
-            return { ok: hit.status >= 200 && hit.status < 300, status: hit.status, text: hit.body, fromCache: true };
-        }
-    }
-    let lastStatus = 0;
-    let lastText = "";
-    for (let attempt = 0; attempt <= retryDelays.length; attempt++) {
-        try {
-            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeout) });
-            const text = await res.text();
-            lastStatus = res.status;
-            lastText = text;
-            // Cache successful responses + 404s (404 is "definitively not found" - no point retrying).
-            if (res.ok || res.status === 404) {
-                cache.set(key, { body: text, status: res.status, expiresAt: Date.now() + ttl });
-                return { ok: res.ok, status: res.status, text, fromCache: false };
-            }
-            // Retry on 429 (rate limit) and 5xx (transient server errors).
-            if (res.status === 429 || res.status >= 500) {
-                const delay = retryDelays[attempt];
-                if (delay === undefined)
-                    break;
-                // Honor server's Retry-After if provided (CoinGecko sends this).
-                const retryAfter = res.headers.get("retry-after");
-                const waitMs = retryAfter ? Math.min(parseInt(retryAfter) * 1000, 30000) : delay;
-                await new Promise((r) => setTimeout(r, waitMs));
-                continue;
-            }
-            // Non-retryable client error (400/401/403) - surface to caller without retry.
-            return { ok: false, status: res.status, text, fromCache: false };
-        }
-        catch (err) {
-            lastText = err instanceof Error ? err.message : String(err);
-            const delay = retryDelays[attempt];
-            if (delay === undefined)
-                break;
-            await new Promise((r) => setTimeout(r, delay));
-        }
-    }
-    return { ok: false, status: lastStatus, text: lastText, fromCache: false };
-}
-function clearHttpCache() {
-    cache.clear();
-}
-function httpCacheStats() {
-    return { size: cache.size, maxEntries: DEFAULT_MAX_ENTRIES };
-}

package/dist/_text-search.js

@@ -1,39 +0,0 @@
-"use strict";
-// Shared substring/keyword scoring for the local-file backends
-// (local-memory-file.ts, local-vault.ts) - no embeddings, no server, zero
-// dependencies. Word-boundary aware, not raw substring counting - a short
-// common term like "is"/"a" used to score a "match" purely by being a
-// substring of an unrelated word ("is" inside "distances", "a" inside
-// "banana"). Found via real testing of memory_add's new conflict-hint
-// feature: a query for "the user's favorite pizza topping is pepperoni"
-// registered as "related" to a completely unrelated stored memory about
-// metric vs imperial units, purely because both contained "the" and "is".
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.meaningfulTerms = meaningfulTerms;
-exports.wordOccurrences = wordOccurrences;
-const STOP_WORDS = new Set([
-    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
-    "to", "of", "in", "on", "at", "for", "with", "by", "from", "as",
-    "and", "or", "but", "if", "so", "this", "that", "it", "its", "i",
-    "you", "your", "they", "them", "their", "he", "she", "his", "her",
-    "not", "no", "do", "does", "did", "has", "have", "had", "will", "would",
-]);
-/** Query terms worth scoring against - lowercased, stop-words and
- *  single-character noise dropped. An empty result means the query was
- *  entirely stop words/punctuation - callers should treat that as "no
- *  meaningful query" (return no matches) rather than matching everything. */
-function meaningfulTerms(query) {
-    return query
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((t) => t.length > 1 && !STOP_WORDS.has(t));
-}
-function escapeRegex(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-/** Word-boundary occurrence count of `term` inside `haystack` - not a raw
- *  substring count, so "is" doesn't match inside "distances" or "this". */
-function wordOccurrences(haystack, term) {
-    const re = new RegExp(`\\b${escapeRegex(term)}\\b`, "g");
-    return (haystack.match(re) || []).length;
-}

package/dist/agent-loop.js

@@ -1,301 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runAgent = runAgent;
-const server_js_1 = require("./server.js");
-const llm_js_1 = require("./llm.js");
-const convex_js_1 = require("./convex.js");
-const SYSTEM_PROMPT = [
-    `You are Finch, the runtime layer for Agentic AI - with ${server_js_1.ALL_TOOLS.length} tools spanning memory, vault, deep research, persistent agents, code, automations, DeFi, and GitHub.`,
-    "Be direct and concise. Pick the right tool - don't narrate the choice. Summarize tool results in plain English.",
-    "",
-    "CRITICAL - on-chain / financial actions (swap, send, transfer, buy, sell, bridge, lend, deposit, withdraw, balance):",
-    "- You MUST call the corresponding tool. NEVER write 'Sent', 'Swapped', 'Tx confirmed', or any execution claim without an actual tool call returning a result first.",
-    "- Tx hash and basescan/explorer URL from the tool output are MANDATORY in your reply - show them verbatim, do not omit or paraphrase.",
-    "- NEVER fabricate a post-transaction balance with arithmetic. If user wants the new balance, call the balance tool again - do not compute it from a prior balance + amount.",
-    "- For ALL Base chain operations, you MUST use the base_mcp_* family: base_mcp_swap (NOT swap_tokens), base_mcp_send (NOT send_token), base_mcp_balance (NOT get_portfolio), base_mcp_estimate, base_mcp_resolve, base_mcp_lend, base_mcp_status. This is non-negotiable - Base operations go through the Base MCP skill, period.",
-    "- For Robinhood Chain tokenized stocks (chainId 4663, NVDA/AAPL/etc on Uniswap V4), you MUST use rh_mcp_*: rh_mcp_status, rh_mcp_list_stocks, rh_mcp_balance, rh_mcp_estimate, rh_mcp_swap. Never use base_mcp_* or 0x for RH stocks. rh_mcp_swap requires confirm:true. Explorer = robinhoodchain.blockscout.com. This is NOT Robinhood Agentic brokerage (agent.robinhood.com).",
-    "- Do NOT claim an address belongs to the user (e.g. 'your own address') unless you have verified ownership. Resolving a basename returns whoever owns that name - usually NOT the caller.",
-    "- The Finch wallet is the SAME address on both Base and Robinhood Chain, but they are separate ledgers - a balance on one tells you nothing about the other. If the user asks a chain-unspecified question ('what's my balance', 'do I have any funds') call BOTH base_mcp_balance AND rh_mcp_balance before answering. Never report only one chain's result as 'your balance' or 'your wallet is empty' - say which chain(s) you checked, and give both figures.",
-    "- Swap/send requests are only chain-unambiguous when the token itself pins the chain (a RH catalog stock like NVDA/AAPL, or a token you already know only exists on one side). A bare request like 'swap 0.001 ETH to a stablecoin' with no chain named is NOT unambiguous just because you picked one - ETH and 'stablecoin' both exist on Base (USDC/USDT/DAI) and Robinhood Chain (USDG). Before estimating or executing an ambiguous swap, call both base_mcp_balance and rh_mcp_balance first: if only one chain actually holds enough of the source token, use that chain and say which one and why; if neither holds enough, say so plainly instead of quoting a swap the wallet can't cover; if both hold enough, ask the user which chain before proceeding.",
-    "- There is NO send/transfer tool for Robinhood Chain - base_mcp_send only moves assets on Base mainnet. If the user asks to send/transfer USDG or any RH catalog stock (NVDA, AAPL, etc.), do NOT call base_mcp_send with that token name hoping it resolves - it will either error or, worse, silently match an unrelated Base token with the same symbol. Tell the user directly that on-chain sends are not yet supported on Robinhood Chain.",
-    "- Never state a balance, price, quote, token address, or transaction result from memory or inference - every number in your answer must trace to a tool call you made THIS turn. If you are not sure which chain, token, or address a term refers to, ask or resolve it (rh_token_resolve / base_mcp_resolve) before answering - do not guess and present the guess as fact.",
-    "",
-    "For deep research: prefer deep_research (multi-stage, saves to vault). Use continueFrom when extending prior reports.",
-    "For live web info: use web_search. For market questions: use get_market_data or market_thesis.",
-    "Save substantive findings to vault; do not save thin or empty outputs.",
-    "",
-    "NEVER call ask_finch from this shell. It exists for MCP clients that have no reasoning model of their own - you already are one. Calling it mid-task means asking a second model to think for you, which produces nothing you couldn't write yourself from the data you already have, and repeating it when unsatisfied just burns turns. If a tool's result already answers the question, write the answer yourself.",
-    "Do not call the same tool with the same or near-identical arguments more than once in a single answer. If deep_research, a search, or an analysis tool already returned data, synthesize from that - do not re-run it hoping for a different result, and do not chain more tool calls than the question actually needs. Stop calling tools and answer as soon as you have enough to answer well.",
-].join("\n");
-async function runAgent(userMessage, history, onToolCall) {
-    const provider = process.env.FINCH_PROVIDER?.toLowerCase().trim();
-    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)
-        return runBankrLoop(bankrKey, userMessage, history, onToolCall);
-    if (provider === "anthropic" && anthropicKey)
-        return runAnthropicLoop(anthropicKey, userMessage, history, onToolCall);
-    if (provider === "openai" && openaiKey)
-        return runOpenAILoop(openaiKey, userMessage, history, onToolCall);
-    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 {
-        return await runConvexProxiedLoop(userMessage, history, onToolCall);
-    }
-    catch {
-        // Network down or backend unavailable - plain chat fallback
-        const text = await (0, llm_js_1.callLLM)(SYSTEM_PROMPT, userMessage, 1024, history);
-        return { text, toolCalls: [] };
-    }
-}
-// ── Anthropic agent loop ─────────────────────────────────────────────────────
-function toAnthropicTool(tool) {
-    return {
-        name: tool.name,
-        description: tool.description ?? "",
-        input_schema: tool.inputSchema ?? { type: "object", properties: {} },
-    };
-}
-// 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 = [
-        ...history.map(h => ({ role: h.role, content: h.content })),
-        { role: "user", content: userMessage },
-    ];
-    for (let turn = 0; turn < 10; turn++) {
-        const data = await sendTurn(messages, tools);
-        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 };
-        }
-        // Execute all tool_use blocks
-        const toolResults = [];
-        for (const block of data.content) {
-            if (block.type !== "tool_use")
-                continue;
-            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 ?? {});
-                // 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}`;
-            }
-            toolResults.push({ type: "tool_result", tool_use_id: block.id, content: resultText });
-        }
-        messages.push({ role: "user", content: toolResults });
-    }
-    // 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(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" },
-            body: JSON.stringify({ model, max_tokens: 4096, system: SYSTEM_PROMPT, messages: msgs }),
-            signal: AbortSignal.timeout(90000),
-        });
-        if (!res.ok)
-            return "";
-        const data = await res.json();
-        return (data.content ?? []).filter(b => b.type === "text").map(b => b.text).join("");
-    };
-    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
-// conversation history (including every tool result so far) it already has,
-// with no tools offered so it can't keep deferring.
-async function finishWithoutTools(call, messages, toolCalls) {
-    try {
-        const closingMessages = [
-            ...messages,
-            { role: "user", content: "Stop calling tools. Summarize what you found above into a direct answer for the user right now." },
-        ];
-        const text = await call(closingMessages);
-        if (text.trim())
-            return { text, toolCalls };
-    }
-    catch { /* fall through to the honest failure message below */ }
-    return {
-        text: "I gathered some information but ran out of turns before finishing the analysis. Try a narrower question, or ask me to continue from what I found.",
-        toolCalls,
-    };
-}
-// ── Convex-proxied Anthropic loop (session token only - platform covers LLM) ──
-function runConvexProxiedLoop(userMessage, history, onToolCall) {
-    const model = process.env.FINCH_MODEL ?? process.env.ANTHROPIC_MODEL ?? "claude-haiku-4-5-20251001";
-    // 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("");
-    };
-    return runAnthropicStyleLoop(sendTurn, sendFinal, userMessage, history, onToolCall);
-}
-// ── Bankr (OpenAI-compatible) agent loop ─────────────────────────────────────
-function toBankrTool(tool) {
-    return {
-        type: "function",
-        function: {
-            name: tool.name,
-            description: tool.description ?? "",
-            parameters: tool.inputSchema ?? { type: "object", properties: {} },
-        },
-    };
-}
-// Shared tool-calling loop for any OpenAI Chat Completions-compatible
-// endpoint (Bankr's LLM gateway and OpenAI itself both speak this format).
-// Only the URL, auth header, and model differ per provider.
-async function runOpenAICompatibleLoop(url, authHeaders, model, providerLabel, userMessage, history, onToolCall) {
-    const tools = server_js_1.ALL_TOOLS.map(toBankrTool);
-    const toolCalls = [];
-    const messages = [
-        { role: "system", content: SYSTEM_PROMPT },
-        ...history.map(h => ({ role: h.role, content: h.content })),
-        { role: "user", content: userMessage },
-    ];
-    for (let turn = 0; turn < 10; turn++) {
-        const res = await fetch(url, {
-            method: "POST",
-            headers: { "Content-Type": "application/json", ...authHeaders },
-            body: JSON.stringify({ model, messages, tools, max_tokens: 4096 }),
-            signal: AbortSignal.timeout(90000),
-        });
-        if (!res.ok) {
-            const body = await res.text().catch(() => "");
-            throw new Error(`${providerLabel} ${res.status}: ${body.slice(0, 300)}`);
-        }
-        const data = await res.json();
-        const choice = data.choices?.[0]?.message;
-        if (!choice)
-            throw new Error(`Empty response from ${providerLabel}`);
-        messages.push(choice);
-        if (!choice.tool_calls?.length) {
-            return { text: choice.content ?? "", toolCalls };
-        }
-        for (const call of choice.tool_calls) {
-            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.";
-            }
-            catch (err) {
-                resultText = `Error: ${err.message}`;
-            }
-            messages.push({ role: "tool", tool_call_id: call.id, content: resultText });
-        }
-    }
-    return finishWithoutTools(async (msgs) => {
-        const res = await fetch(url, {
-            method: "POST",
-            headers: { "Content-Type": "application/json", ...authHeaders },
-            body: JSON.stringify({ model, messages: msgs, max_tokens: 4096 }),
-            signal: AbortSignal.timeout(90000),
-        });
-        if (!res.ok)
-            return "";
-        const data = await res.json();
-        return data.choices?.[0]?.message?.content ?? "";
-    }, messages, toolCalls);
-}
-async function runBankrLoop(apiKey, userMessage, history, onToolCall) {
-    const model = process.env.FINCH_MODEL ?? process.env.BANKR_MODEL ?? "claude-haiku-4-5-20251001";
-    return runOpenAICompatibleLoop("https://llm.bankr.bot/v1/chat/completions", { "X-API-Key": apiKey }, model, "Bankr", userMessage, history, onToolCall);
-}
-// Same OPENAI_BASE_URL override as llm.ts's callOpenAI - lets tool-calling
-// route to a self-hosted OpenAI-compatible gateway too.
-function openAiChatUrl() {
-    const base = process.env.OPENAI_BASE_URL?.replace(/\/+$/, "");
-    return base ? `${base}/chat/completions` : "https://api.openai.com/v1/chat/completions";
-}
-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

@@ -1,122 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MUTATING_TOOL_NAMES = void 0;
-exports.annotationsFor = annotationsFor;
-exports.withAnnotations = withAnnotations;
-const output_schemas_js_1 = require("./output-schemas.js");
-// Read-only AND no network - a purely local computation (static analysis).
-// Read-only but open-world is the default, so this set only exists to flip
-// openWorldHint off for the rare offline tool.
-const READ_ONLY_LOCAL = new Set([
-    "audit_contract", // deterministic static Solidity scan, no backend call
-]);
-// readOnly=false, destructive=false, idempotent=true.
-// Toggles and upserts: re-running with the same args lands in the same state.
-const WRITE_IDEMPOTENT = new Set([
-    "agent_update",
-    "pause_automation",
-    "stake_auto_restake",
-    "vault_link",
-    "vault_pin",
-    "vault_tag",
-    "vault_unpublish",
-]);
-// readOnly=false, destructive=false.
-// Additive writes / new resources: they create or append, they don't destroy.
-const WRITE = new Set([
-    "agent_spawn",
-    "chronicle_add",
-    "code_session_save",
-    "memory_add",
-    "memory_extract",
-    "memory_consolidate",
-    "packet_create",
-    "schedule_research",
-    "vault_save",
-    "vault_store_credential",
-    "miroshark_simulate",
-    "finch_shell_chat", // orchestrator: can spawn/save/create via delegated tools
-]);
-// readOnly=false, destructive=true.
-// Deletes, cancels, irreversible publishes, and anything that moves real funds
-// (or arms an order engine that will). Clients should confirm before running.
-const DESTRUCTIVE = new Set([
-    // removals / cancels
-    "cancel_monitor",
-    "delete_automation",
-    "memory_delete",
-    "miroshark_stop",
-    "rh_order_cancel",
-    "vault_delete",
-    // irreversible public exposure
-    "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",
-    // 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",
-    "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)) {
-        return { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
-    }
-    if (WRITE_IDEMPOTENT.has(name)) {
-        return { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
-    }
-    if (WRITE.has(name)) {
-        return { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
-    }
-    if (READ_ONLY_LOCAL.has(name)) {
-        return { readOnlyHint: true, openWorldHint: false };
-    }
-    return { readOnlyHint: true, openWorldHint: true };
-}
-// Decorate a tool list with MCP metadata: behavioural annotations
-// (readOnly/destructive/etc) and, for tools registered in OUTPUT_SCHEMAS, a
-// machine-readable `outputSchema`. A value already present on the tool is left
-// untouched, so a module can always override either.
-function withAnnotations(tools) {
-    return tools.map((t) => {
-        const patch = {};
-        if (!t.annotations)
-            patch.annotations = annotationsFor(t.name);
-        if (!t.outputSchema && output_schemas_js_1.OUTPUT_SCHEMAS[t.name]) {
-            patch.outputSchema = output_schemas_js_1.OUTPUT_SCHEMAS[t.name];
-        }
-        return Object.keys(patch).length ? { ...t, ...patch } : t;
-    });
-}
-// Exported for the test suite to assert the classification only references real
-// tool names (catches typos / tools renamed out from under a set).
-exports.MUTATING_TOOL_NAMES = [
-    ...WRITE_IDEMPOTENT,
-    ...WRITE,
-    ...DESTRUCTIVE,
-    ...READ_ONLY_LOCAL,
-];