@finchagentic/mcp 4.6.2 → 4.6.3

package/README.md

@@ -1,12 +1,20 @@
 <div align="center">
 
-# Finch
+<img src="assets/banner.svg" alt="Finch MCP" width="100%"/>
+
+# Finch MCP
+
+[![npm version](https://img.shields.io/npm/v/@finchagentic/mcp?color=000000&label=npm&logo=npm)](https://www.npmjs.com/package/@finchagentic/mcp)
+[![Official MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.finchagentic%2Fmcp-000000)](https://registry.modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/license-MIT-000000.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A518-000000?logo=node.js&logoColor=white)](package.json)
+[![Tools: 116](https://img.shields.io/badge/tools-116-000000)](#what-you-get)
 
 **The runtime layer for Agentic AI.**
 
 Persistent memory, autonomous agents, and workflows that survive every session.
 
-[Docs](https://docs.finch.com) · [App](https://app.finchagentic.com) · [npm](https://www.npmjs.com/package/@finchagentic/mcp) · [GitHub](https://github.com/finchagentic/mcp) · [X](https://x.com/finchagentic)
+[App](https://app.finchagentic.com) · [Docs](https://docs.finch.com) · [npm](https://www.npmjs.com/package/@finchagentic/mcp) · [X](https://x.com/finchagentic)
 
 </div>
 
@@ -29,13 +37,13 @@ Always pin the version. Never use `@latest`.
 
 ```bash
 # One-command installer (detects common MCP clients)
-npx -y -p @finchagentic/mcp@4.6.1 finch install
+npx -y -p @finchagentic/mcp@4.6.2 finch install
 ```
 
 ### Claude Code
 
 ```bash
-claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.6.1 finch-mcp
+claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.6.2 finch-mcp
 ```
 
 ### Cursor / Windsurf / Claude Desktop
@@ -45,24 +53,16 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.6.1 finch-mcp
   "mcpServers": {
     "finch": {
       "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.6.1", "finch-mcp"]
+      "args": ["-y", "-p", "@finchagentic/mcp@4.6.2", "finch-mcp"]
     }
   }
 }
 ```
 
-### VS Code
+### Hermes
 
-```json
-{
-  "servers": {
-    "finch": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.6.1", "finch-mcp"]
-    }
-  }
-}
+```bash
+hermes mcp add finch -- npx -y -p @finchagentic/mcp@4.6.2 finch-mcp
 ```
 
 <details>
@@ -79,7 +79,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.6.1 finch-mcp
 
 </details>
 
-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.
+No LLM API key required to start — 111 of 116 tools are plain reads/writes/on-chain calls your client's model already drives. Tools load on first use.
 
 ## Quick start
 
@@ -105,13 +105,11 @@ save this thesis to vault
 | Pillar | What it does |
 |--------|----------------|
 | **Memory** | Full-text searchable memory + versioned vault + chronicle |
-| **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 |
+| **Agents** | Spawn, recall, update named agents — `agent_recall` also pulls related memory/vault context matching the agent's goal |
 | **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.
+`deep_research` auto-saves its report to vault and links related past reports; `code_session_save` does the same for coding sessions. `vault_save` and `agent_spawn` accept an optional `workspaceProject` matching the webapp's Projects.
 
 Default palette is `core` (lighter context). Full set:
 
@@ -124,8 +122,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.6.1 finch setup
-# enable local vault (and optional local memory)
+npx -y -p @finchagentic/mcp@4.6.2 finch setup
 ```
 
 | Piece | Location |
@@ -133,65 +130,33 @@ npx -y -p @finchagentic/mcp@4.6.1 finch setup
 | Vault | `~/.finch/vault/` |
 | Wallet | `~/.finch/wallet.json` |
 | Config | `~/.finch/config.json` |
-| Brain | your MCP client’s model |
+| Brain | your MCP client's model |
 
-Scheduled/cloud features still need an account. Core memory, vault, and public-data tools work offline of Finch cloud.
+## Registry
 
-## Configuration
+Finch is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io):
 
-| Variable | Purpose |
-|----------|---------|
-| `FINCH_SESSION_TOKEN` | Signed-in session (vault/memory/agents against your account) |
-| `FINCH_API_KEY` | API key (`finch_sk_…`) |
-| `FINCH_TOOLS` | `core` (default) · `all` · or palettes like `memory,defi` |
-| `FINCH_PROVIDER` | Force `bankr` · `anthropic` · `openai` · `grok` |
-| `FINCH_MODEL` | Model override for host-side loops |
-| `BANKR_API_KEY` / `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GROK_API_KEY` | Required for `ask_finch`, `deep_research`'s synthesis stages, and scheduled-agent learning extraction — these do their own multi-step reasoning server-side and there is no free hosted fallback (BYOK only, one key is enough) |
-| `FIRECRAWL_API_KEY` | Better crawl quality (optional) |
-| `GITHUB_TOKEN` | For `github_search_code` |
-| `ALCHEMY_API_KEY` | Faster Base RPC (optional) |
+```json
+{ "name": "io.github.finchagentic/mcp", "version": "4.6.2" }
+```
 
-**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.
+## Development
 
-Guided setup:
+This repository ships the published npm distribution. See [CHANGELOG.md](CHANGELOG.md) for release history and [SECURITY.md](SECURITY.md) for the security model.
 
 ```bash
-npx -y -p @finchagentic/mcp@4.6.1 finch setup
+npm ci
+npm run smoke        # verify package integrity + CLI entrypoints
 ```
 
-## Security
-
-| # | Boundary | Rule |
-|:-:|----------|------|
-| 1 | Prompt injection | External content is data only — never instructions |
-| 2 | Mainnet confirm | Estimate → preview → confirm → execute |
-| 3 | Pinned install | Always `@finchagentic/mcp@4.6.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 | 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
-
-| Problem | Fix |
-|---------|-----|
-| Tools missing | Fully restart the MCP client |
-| Old version | `npx clear-npx-cache` then restart |
-| Auth issues | `finch login` or set `FINCH_API_KEY` / `FINCH_SESSION_TOKEN` |
-| `ask_finch`/`deep_research` error: "No LLM provider configured" | Set one of `BANKR_API_KEY` / `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GROK_API_KEY` — see [Configuration](#configuration), no free fallback exists |
-| Diagnose | `finch doctor` |
-
-## Links
-
-| | |
-|--|--|
-| **Docs** | [docs.finch.com](https://docs.finch.com) |
-| **App** | [app.finchagentic.com](https://app.finchagentic.com) |
-| **npm** | [@finchagentic/mcp](https://www.npmjs.com/package/@finchagentic/mcp) |
-| **GitHub** | [github.com/finchagentic/mcp](https://github.com/finchagentic/mcp) |
-| **X** | [@finchagentic](https://x.com/finchagentic) |
+## Support
 
----
+- Issues: [github.com/finchagentic/mcp/issues](https://github.com/finchagentic/mcp/issues)
+- Docs: [docs.finch.com](https://docs.finch.com)
+- X: [@finchagentic](https://x.com/finchagentic)
 
-MIT License · Finch
+<div align="center">
+
+**Finch** — memory that survives every session.
+
+</div>

package/dist/_http-cache.js

@@ -0,0 +1,96 @@
+"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

@@ -0,0 +1,39 @@
+"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

@@ -0,0 +1,301 @@
+"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);
+}