@finchagentic/mcp 4.0.0 → 4.2.0

package/dist/agent-loop.js

@@ -15,21 +15,48 @@ const SYSTEM_PROMPT = [
     "- 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 {
@@ -49,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 = [
@@ -58,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: 2048, 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
@@ -86,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}`;
@@ -103,56 +134,76 @@ async function runAnthropicLoop(apiKey, userMessage, history, onToolCall) {
         }
         messages.push({ role: "user", content: toolResults });
     }
-    return { text: "Reached max tool iterations.", toolCalls };
+    // 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) ──
-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
+    // 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: 2048,
-            system: SYSTEM_PROMPT,
-            tools,
-            messages,
+            model, max_tokens: 4096, system: SYSTEM_PROMPT, messages: msgs,
         }, "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 { text: "Reached max tool iterations.", toolCalls };
+        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) {
@@ -180,7 +231,7 @@ async function runOpenAICompatibleLoop(url, authHeaders, model, providerLabel, u
         const res = await fetch(url, {
             method: "POST",
             headers: { "Content-Type": "application/json", ...authHeaders },
-            body: JSON.stringify({ model, messages, tools, max_tokens: 2048 }),
+            body: JSON.stringify({ model, messages, tools, max_tokens: 4096 }),
             signal: AbortSignal.timeout(90000),
         });
         if (!res.ok) {
@@ -196,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.";
             }
@@ -213,7 +266,18 @@ async function runOpenAICompatibleLoop(url, authHeaders, model, providerLabel, u
             messages.push({ role: "tool", tool_call_id: call.id, content: resultText });
         }
     }
-    return { text: "Reached max tool iterations.", toolCalls };
+    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";
@@ -229,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",
     "memory_add",
     "memory_extract",
     "memory_consolidate",
     "packet_create",
-    "packet_share",
     "schedule_research",
     "vault_save",
     "vault_store_credential",
@@ -58,11 +49,18 @@ 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
@@ -70,8 +68,11 @@ const DESTRUCTIVE = new Set([
     "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",
 ]);
 function annotationsFor(name) {
     if (DESTRUCTIVE.has(name)) {

package/dist/cli.js

@@ -44,6 +44,7 @@ const tool_filter_js_1 = require("./tool-filter.js");
 const config_js_1 = require("./config.js");
 const local_memory_js_1 = require("./local-memory.js");
 const clink_input_js_1 = require("./clink-input.js");
+const wallet_js_1 = require("./wallet.js");
 const child_process = __importStar(require("child_process"));
 (0, config_js_1.hydrateEnvFromConfig)();
 // Derived tool counts - single source of truth, kept in sync with the
@@ -117,8 +118,8 @@ async function loginWithApiKey(rl) {
     }
     const email = data.email ?? "api-key-user";
     const name = data.displayName ?? undefined;
-    (0, config_js_1.writeConfig)({ sessionToken: data.token, email, name });
-    printLoginSuccess({ email, name });
+    (0, config_js_1.writeConfig)({ sessionToken: data.token, email, name, walletAddress: data.walletAddress });
+    printLoginSuccess({ email, name, walletAddress: data.walletAddress });
 }
 async function loginFlow(loginRl) {
     const rl = loginRl ?? readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -136,8 +137,8 @@ async function loginFlow(loginRl) {
         if (res.ok && data.token) {
             const email = data.email ?? "api-key-user";
             const name = data.displayName ?? undefined;
-            (0, config_js_1.writeConfig)({ sessionToken: data.token, email, name });
-            printLoginSuccess({ email, name });
+            (0, config_js_1.writeConfig)({ sessionToken: data.token, email, name, walletAddress: data.walletAddress });
+            printLoginSuccess({ email, name, walletAddress: data.walletAddress });
             rl.close();
             return;
         }
@@ -210,10 +211,16 @@ async function setupFlow() {
         console.log(`\n  ${C.dim}Skipped - using Finch proxy.${C.reset}\n`);
     }
     // ── Step 2: local memory ──────────────────────────────────────────────────
-    console.log(`  ${C.cyan}${C.bold}Local memory${C.reset}  ${C.dim}(self-hosted supermemory - github.com/supermemoryai/supermemory)${C.reset}`);
-    console.log(`  ${C.dim}Runs on your machine, MIT licensed, free. Replaces the Finch-hosted memory proxy.${C.reset}\n`);
-    const enableLocal = (0, clink_input_js_1.dedupClinkInput)((await ask(`  Enable local memory? [y/N]: `)).trim()).toLowerCase();
-    if (enableLocal === "y" || enableLocal === "yes") {
+    console.log(`  ${C.cyan}${C.bold}Local memory${C.reset}  ${C.dim}(self-hosted - your choice of backend)${C.reset}`);
+    console.log(`  ${C.dim}[1] Simple file-based (recommended) - zero dependency, JSON on disk at ~/.finch/memory/, keyword search only.${C.reset}`);
+    console.log(`  ${C.dim}[2] Supermemory server - real semantic/embedding search, but you run a separate process yourself.${C.reset}`);
+    console.log(`  ${C.dim}[3] Skip - memory tools use the Finch-hosted proxy.${C.reset}\n`);
+    const memChoice = (0, clink_input_js_1.dedupClinkInput)((await ask(`  Choose [1-3]: `)).trim());
+    if (memChoice === "1") {
+        (0, config_js_1.writeConfig)({ memoryBackend: "local-file" });
+        console.log(`\n  ${C.green}✓${C.reset} Local file memory enabled at ~/.finch/memory/. No server, no key - memory tools run fully local.\n`);
+    }
+    else if (memChoice === "2") {
         const url = "http://localhost:6767";
         console.log(`\n  ${C.dim}Checking ${url}...${C.reset}`);
         let reachable = await isLocalMemoryReachableRaw(url);
@@ -389,16 +396,21 @@ const C = {
 //   ██║ ╚████║╚██████╔╝███████╗███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝
 //   ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝
 const LOGO_LINES = [
-    `  ███╗   ██╗ ██████╗ ███████╗██╗      ██████╗██╗      █████╗ ██╗    ██╗`,
-    `  ████╗  ██║██╔═══██╗██╔════╝██║     ██╔════╝██║     ██╔══██╗██║    ██║`,
-    `  ██╔██╗ ██║██║   ██║█████╗  ██║     ██║     ██║     ███████║██║ █╗ ██║`,
-    `  ██║╚██╗██║██║   ██║██╔══╝  ██║     ██║     ██║     ██╔══██║██║███╗██║`,
-    `  ██║ ╚████║╚██████╔╝███████╗███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝`,
-    `  ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝`,
+    `  ███████╗ ██╗ ███╗   ██╗  ██████╗ ██╗  ██╗`,
+    `  ██╔════╝ ██║ ████╗  ██║ ██╔════╝ ██║  ██║`,
+    `  █████╗   ██║ ██╔██╗ ██║ ██║      ███████║`,
+    `  ██╔══╝   ██║ ██║╚██╗██║ ██║      ██╔══██║`,
+    `  ██║      ██║ ██║ ╚████║ ╚██████╗ ██║  ██║`,
+    `  ╚═╝      ╚═╝ ╚═╝  ╚═══╝  ╚═════╝ ╚═╝  ╚═╝`,
 ];
 const SEP = `  ${"─".repeat(70)}`;
 function buildBanner() {
     const cfg = (0, config_js_1.readConfig)();
+    // Every base_mcp_*/rh_mcp_* tool signs locally via getOrCreateWallet()
+    // (~/.finch/wallet.json) on BOTH Base and Robinhood Chain (RH reuses the
+    // same local address) - this CLI never touches the account's custodial
+    // webapp wallet. Showing that other address here would mismatch what
+    // every tool call actually reports and operates on.
     const walletAddr = getLocalWalletAddress();
     const provider = process.env.BANKR_API_KEY ? "Bankr"
         : process.env.ANTHROPIC_API_KEY ? "Anthropic"
@@ -415,8 +427,9 @@ function buildBanner() {
         const nameLine = displayName
             ? `  ${C.green}●${C.reset}  ${displayName}  ${displayEmail}`
             : `  ${C.green}●${C.reset}  ${displayEmail || `${C.green}Signed in${C.reset}`}`;
+        const walletNote = "Base + Robinhood Chain · local device wallet · keys never leave your machine";
         const walletLine = walletAddr
-            ? `     ${C.dim}Wallet${C.reset}  ${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· Base mainnet · keys never leave your machine${C.reset}`
+            ? `     ${C.dim}Wallet${C.reset}  ${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· ${walletNote}${C.reset}`
             : `     ${C.dim}Wallet  not created yet · auto-creates on first DeFi call${C.reset}`;
         const llmLine = `     ${C.dim}LLM     ${C.reset}${C.green}${provider}${C.reset}  ${C.dim}· ${TOTAL_TOOL_COUNT} tools active${C.reset}`;
         authBlock = `\n${nameLine}\n${walletLine}\n${llmLine}`;
@@ -434,6 +447,10 @@ function buildBanner() {
 }
 // ── Post-login success block ──────────────────────────────────────────────────
 function printLoginSuccess({ email, name }) {
+    // Always show the local per-device wallet: every base_mcp_*/rh_mcp_* tool
+    // signs with it on BOTH chains. The account's custodial webapp wallet is a
+    // separate address this CLI never touches - showing it here would mismatch
+    // what every subsequent tool call actually reports.
     const walletAddr = getLocalWalletAddress();
     const displayName = name ?? "";
     console.log(`\n${SEP}`);
@@ -444,7 +461,8 @@ function printLoginSuccess({ email, name }) {
         console.log(`  ${C.green}✓${C.reset}  ${C.green}${C.bold}Signed in${C.reset}  ${C.dim}as ${email}${C.reset}`);
     }
     if (walletAddr) {
-        console.log(`     ${C.dim}Wallet${C.reset}  ${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· Base mainnet${C.reset}`);
+        const note = "Base + Robinhood Chain · local device wallet";
+        console.log(`     ${C.dim}Wallet${C.reset}  ${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· ${note}${C.reset}`);
     }
     else {
         console.log(`     ${C.dim}Wallet  auto-creates on first DeFi tool call${C.reset}`);
@@ -527,7 +545,7 @@ async function main() {
             });
             const data = await res.json();
             if (res.ok && data.token) {
-                (0, config_js_1.writeConfig)({ sessionToken: data.token, email: data.email ?? "api-key-user", name: data.displayName ?? undefined });
+                (0, config_js_1.writeConfig)({ sessionToken: data.token, email: data.email ?? "api-key-user", name: data.displayName ?? undefined, walletAddress: data.walletAddress });
                 console.log(`${C.green}✓${C.reset} ${C.dim}Signed in as ${data.email}${C.reset}`);
             }
             else {
@@ -539,6 +557,8 @@ async function main() {
         }
     }
     process.stdout.write(buildBanner());
+    // Once, here, so it doesn't interrupt the first tool reply mid-conversation.
+    (0, wallet_js_1.warnIfNoPassphrase)();
     // Check for updates in background - shows after banner, doesn't block prompt
     checkForUpdate().catch(() => { });
     const history = [];
@@ -998,10 +1018,17 @@ async function doctorFlow() {
             fix: `Optional. Create at https://github.com/settings/tokens (scopes: public_repo) and add to MCP env.`,
         });
     }
-    // 9. Local memory (self-hosted supermemory) - optional, zero-cost alternative
-    // to the Convex-proxied cloud memory backend.
+    // 9. Local memory (self-hosted) - optional, zero-cost alternative to the
+    // Convex-proxied cloud memory backend. Two flavors: zero-dependency file
+    // store, or a separately-run supermemory server.
     const localMemCfg = (0, local_memory_js_1.getLocalMemoryConfig)();
-    if (localMemCfg) {
+    if (localMemCfg?.kind === "file") {
+        checks.push({
+            name: "Local memory", status: "✓",
+            detail: `file-based at ~/.finch/memory - memory tools run fully local, zero cost, no server`,
+        });
+    }
+    else if (localMemCfg?.kind === "supermemory") {
         const reachable = await (0, local_memory_js_1.isLocalMemoryReachable)(localMemCfg);
         checks.push(reachable ? {
             name: "Local memory", status: "✓",
@@ -1143,6 +1170,9 @@ else if (cmd === "logout") {
 }
 else if (cmd === "status") {
     const cfg = (0, config_js_1.readConfig)();
+    // Every base_mcp_*/rh_mcp_* tool signs locally on BOTH chains - the
+    // account's custodial webapp wallet is a separate address this CLI never
+    // touches, so always show the local one to match what tools report.
     const walletAddr = getLocalWalletAddress();
     const provider = process.env.BANKR_API_KEY ? "Bankr"
         : process.env.ANTHROPIC_API_KEY ? "Anthropic"
@@ -1155,7 +1185,8 @@ else if (cmd === "status") {
         const displayEmail = cfg.email ? `${C.dim}${cfg.email}${C.reset}` : "";
         console.log(`  ${C.green}●${C.reset}  ${displayName}${displayEmail}`);
         if (walletAddr) {
-            console.log(`     ${C.dim}Wallet  ${C.reset}${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· Base mainnet${C.reset}`);
+            const note = "Base + Robinhood Chain · local device wallet";
+            console.log(`     ${C.dim}Wallet  ${C.reset}${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· ${note}${C.reset}`);
         }
         else {
             console.log(`     ${C.dim}Wallet  not created yet${C.reset}`);
@@ -1169,12 +1200,38 @@ else if (cmd === "status") {
     }
     console.log(`${SEP_S}\n`);
 }
+else if (cmd === "run") {
+    const prompt = process.argv.slice(3).join(" ");
+    if (!prompt) {
+        console.error(`  ${C.red}✗ usage: finch run "your prompt"${C.reset}\n`);
+        process.exit(1);
+    }
+    (0, wallet_js_1.warnIfNoPassphrase)();
+    (async () => {
+        const history = [];
+        const stop = spinner("thinking");
+        try {
+            const result = await (0, agent_loop_js_1.runAgent)(prompt, history, (toolName) => {
+                stop();
+                process.stdout.write(`  ${C.dim}✦ ${toolName}${C.reset}\n`);
+            });
+            stop();
+            console.log(`\n${result.text}\n`);
+        }
+        catch (err) {
+            stop();
+            console.error(`  ${C.red}✗ run error: ${err.message || err}${C.reset}\n`);
+            process.exit(1);
+        }
+    })();
+}
 else if (cmd === "help" || cmd === "--help" || cmd === "-h") {
     console.log(`
   ${C.cyan}${C.bold}finch${C.reset}  ${C.dim}runtime layer for Agentic AI · terminal CLI${C.reset}
 
   ${C.cyan}Commands:${C.reset}
     finch              Start interactive AI terminal
+    finch run "..."    Run a single prompt and exit (scripting/CI-friendly)
     finch install      Auto-configure all detected MCP clients
     finch login        Sign in to unlock all tools
     finch logout       Sign out and clear saved token

package/dist/config.js

@@ -43,10 +43,10 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const CONFIG_DIR = path.join(os.homedir(), ".finch");
-const LEGACY_DIR = path.join(os.homedir(), ".noelclaw");
+const LEGACY_DIR = path.join(os.homedir(), ".finch");
 const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
 const LEGACY_FILE = path.join(LEGACY_DIR, "config.json");
-/** Prefer FINCH_* env, fall back to legacy NOELCLAW_* during rebrand. */
+/** Prefer FINCH_* env, fall back to legacy FINCH_* during rebrand. */
 function env(name, legacy) {
     const primary = process.env[name];
     if (primary !== undefined && primary !== "")
@@ -56,9 +56,9 @@ function env(name, legacy) {
         if (v !== undefined && v !== "")
             return v;
     }
-    // Auto-map FINCH_X → NOELCLAW_X when legacy not passed
+    // Auto-map FINCH_X → FINCH_X when legacy not passed
     if (name.startsWith("FINCH_")) {
-        const auto = "NOELCLAW_" + name.slice("FINCH_".length);
+        const auto = "FINCH_" + name.slice("FINCH_".length);
         const v = process.env[auto];
         if (v !== undefined && v !== "")
             return v;
@@ -70,7 +70,7 @@ function readConfig() {
         if (fs.existsSync(CONFIG_FILE)) {
             return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
         }
-        // migrate-read: still pick up old ~/.noelclaw/config.json
+        // migrate-read: still pick up old ~/.finch/config.json
         if (fs.existsSync(LEGACY_FILE)) {
             return JSON.parse(fs.readFileSync(LEGACY_FILE, "utf8"));
         }
@@ -89,7 +89,7 @@ function writeConfig(patch) {
 }
 function getSavedToken() {
     // env var always wins over saved config
-    return env("FINCH_SESSION_TOKEN", "NOELCLAW_SESSION_TOKEN") ?? readConfig().sessionToken;
+    return env("FINCH_SESSION_TOKEN", "FINCH_SESSION_TOKEN") ?? readConfig().sessionToken;
 }
 /** Accept finch_sk_* (new) and noel_sk_* (backend still issues these). */
 function isApiKey(value) {
@@ -114,16 +114,16 @@ function hydrateEnvFromConfig() {
         process.env.OPENAI_BASE_URL = cfg.openaiBaseUrl;
     // Bridge legacy env into FINCH_* so the rest of the codebase can read one name.
     const bridges = [
-        ["FINCH_SESSION_TOKEN", "NOELCLAW_SESSION_TOKEN"],
-        ["FINCH_API_KEY", "NOELCLAW_API_KEY"],
-        ["FINCH_CONVEX_URL", "NOELCLAW_CONVEX_URL"],
-        ["FINCH_TOOLS", "NOELCLAW_TOOLS"],
-        ["FINCH_PROVIDER", "NOELCLAW_PROVIDER"],
-        ["FINCH_MODEL", "NOELCLAW_MODEL"],
-        ["FINCH_RPC_URL", "NOELCLAW_RPC_URL"],
-        ["FINCH_BROADCAST_RPC", "NOELCLAW_BROADCAST_RPC"],
-        ["FINCH_WALLET_PASSPHRASE", "NOELCLAW_WALLET_PASSPHRASE"],
-        ["FINCH_PAYMENT_HEADER", "NOELCLAW_PAYMENT_HEADER"],
+        ["FINCH_SESSION_TOKEN", "FINCH_SESSION_TOKEN"],
+        ["FINCH_API_KEY", "FINCH_API_KEY"],
+        ["FINCH_CONVEX_URL", "FINCH_CONVEX_URL"],
+        ["FINCH_TOOLS", "FINCH_TOOLS"],
+        ["FINCH_PROVIDER", "FINCH_PROVIDER"],
+        ["FINCH_MODEL", "FINCH_MODEL"],
+        ["FINCH_RPC_URL", "FINCH_RPC_URL"],
+        ["FINCH_BROADCAST_RPC", "FINCH_BROADCAST_RPC"],
+        ["FINCH_WALLET_PASSPHRASE", "FINCH_WALLET_PASSPHRASE"],
+        ["FINCH_PAYMENT_HEADER", "FINCH_PAYMENT_HEADER"],
     ];
     for (const [fin, leg] of bridges) {
         if (!process.env[fin] && process.env[leg])