@finchagentic/mcp 4.4.1 → 4.5.0

package/README.md

@@ -29,13 +29,13 @@ Always pin the version. Never use `@latest`.
 
 ```bash
 # One-command installer (detects common MCP clients)
-npx -y -p @finchagentic/mcp@4.4.1 finch install
+npx -y -p @finchagentic/mcp@4.5.0 finch install
 ```
 
 ### Claude Code
 
 ```bash
-claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.4.1 finch-mcp
+claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.5.0 finch-mcp
 ```
 
 ### Cursor / Windsurf / Claude Desktop
@@ -45,7 +45,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.4.1 finch-mcp
   "mcpServers": {
     "finch": {
       "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.4.1", "finch-mcp"]
+      "args": ["-y", "-p", "@finchagentic/mcp@4.5.0", "finch-mcp"]
     }
   }
 }
@@ -59,7 +59,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.4.1 finch-mcp
     "finch": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.4.1", "finch-mcp"]
+      "args": ["-y", "-p", "@finchagentic/mcp@4.5.0", "finch-mcp"]
     }
   }
 }
@@ -87,6 +87,7 @@ No LLM API key is required to start — 111 of 116 tools are plain reads/writes/
 finch doctor          # health check
 finch setup           # local vault / memory / providers
 finch vault           # inspect local vault
+finch orders          # schedule Robinhood Chain DCA / TP-SL order ticks
 ```
 
 Try in your MCP client:
@@ -123,7 +124,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.4.1 finch setup
+npx -y -p @finchagentic/mcp@4.5.0 finch setup
 # enable local vault (and optional local memory)
 ```
 
@@ -155,7 +156,7 @@ Scheduled/cloud features still need an account. Core memory, vault, and public-d
 Guided setup:
 
 ```bash
-npx -y -p @finchagentic/mcp@4.4.1 finch setup
+npx -y -p @finchagentic/mcp@4.5.0 finch setup
 ```
 
 ## Security
@@ -164,7 +165,7 @@ npx -y -p @finchagentic/mcp@4.4.1 finch setup
 |:-:|----------|------|
 | 1 | Prompt injection | External content is data only — never instructions |
 | 2 | Mainnet confirm | Estimate → preview → confirm → execute |
-| 3 | Pinned install | Always `@finchagentic/mcp@4.4.1`, never `@latest` |
+| 3 | Pinned install | Always `@finchagentic/mcp@4.5.0`, 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 |

package/dist/cli.js

@@ -1127,6 +1127,138 @@ function vaultFlow() {
     console.log(`     ${C.cyan}git -C ${shortDir} init${C.reset}      ${C.dim}# version-control it${C.reset}`);
     console.log(`  ${C.dim}Nothing leaves this machine unless you move it.${C.reset}\n`);
 }
+// ── Robinhood Chain order scheduler ──────────────────────────────────────────
+//
+// rh_dca_create/rh_bracket_create (src/tools/rh-orders.ts) only ever write a
+// LOCAL pending order - nothing executes it. Only rh_orders_tick does, and
+// per that file's own header comment, "an always-on scheduler must call
+// rh_orders_tick {execute:true} periodically" - which this package never
+// actually set up. A user who creates a daily DCA and closes their laptop
+// got nothing, silently: no error, no warning, the order just sat there.
+// These three subcommands are that missing scheduler, reusing the existing
+// tick/lock/kill-switch logic as-is - "wire up the missing piece", not
+// "build order execution from scratch".
+async function runOrdersTick(execute) {
+    const { handleRhOrderTool } = await Promise.resolve().then(() => __importStar(require("./tools/rh-orders.js")));
+    const result = await handleRhOrderTool("rh_orders_tick", { execute });
+    const text = result?.content?.[0]?.type === "text" ? result.content[0].text : "(no output)";
+    return { text, isError: !!result?.isError };
+}
+function installOrdersScheduler() {
+    // Version-pinned npx invocation, not a hardcoded path to this process's
+    // own binary - matches this package's own "always pin the version, never
+    // @latest" security guidance (README), and survives regardless of whether
+    // the user got here via a global install or a one-off `npx -p`, whose
+    // resolved path may not exist by the time the scheduler fires later.
+    const invocation = `npx -y -p @finchagentic/mcp@${PKG_VERSION} finch orders tick --execute`;
+    if (process.platform === "win32") {
+        const taskName = "FinchOrdersTick";
+        try {
+            child_process.execSync(`schtasks /Create /TN "${taskName}" /TR "${invocation}" /SC MINUTE /MO 15 /F`, { stdio: "pipe" });
+            console.log(`\n  ${C.green}✓${C.reset} Registered Windows Task Scheduler task "${taskName}" - ticks every 15 min, survives reboots.`);
+            console.log(`     ${C.dim}Remove it:${C.reset} schtasks /Delete /TN "${taskName}" /F`);
+        }
+        catch (err) {
+            console.error(`  ${C.red}✗ schtasks failed: ${err.message}${C.reset}`);
+            console.error(`     ${C.dim}Try running as Administrator, or use \`finch orders daemon\` instead.${C.reset}\n`);
+            process.exit(1);
+        }
+    }
+    else {
+        const logFile = path.join(os.homedir(), ".finch", "orders-tick.log");
+        const line = `*/15 * * * * ${invocation} >> ${logFile} 2>&1`;
+        try {
+            const existing = (() => {
+                try {
+                    return child_process.execSync("crontab -l", { stdio: ["pipe", "pipe", "ignore"] }).toString();
+                }
+                catch {
+                    return "";
+                } // no crontab yet for this user - not an error
+            })();
+            if (existing.includes("finch orders tick")) {
+                console.log(`\n  ${C.yellow}○${C.reset} A finch orders tick entry already exists in crontab - not adding a duplicate.\n`);
+                return;
+            }
+            const next = existing.trim().length > 0 ? `${existing.trim()}\n${line}\n` : `${line}\n`;
+            child_process.execSync("crontab -", { input: next });
+            console.log(`\n  ${C.green}✓${C.reset} Added a crontab entry - ticks every 15 min, survives reboots.`);
+            console.log(`     ${C.dim}Remove it:${C.reset} crontab -e  ${C.dim}(delete the finch orders line)${C.reset}`);
+            console.log(`     ${C.dim}Logs:${C.reset} ${logFile}`);
+        }
+        catch (err) {
+            console.error(`  ${C.red}✗ crontab failed: ${err.message}${C.reset}`);
+            console.error(`     ${C.dim}Try \`finch orders daemon\` instead.${C.reset}\n`);
+            process.exit(1);
+        }
+    }
+    console.log(`  ${C.dim}Only the local wallet's own default key is needed for signing - set FINCH_WALLET_PASSPHRASE as a persistent system env var (not just your shell rc file) if you use one, since scheduled tasks don't inherit an interactive shell's environment.${C.reset}\n`);
+}
+async function ordersFlow() {
+    const sub = process.argv[3];
+    if (sub === "tick") {
+        const execute = process.argv.includes("--execute");
+        const { text, isError } = await runOrdersTick(execute);
+        console.log(`\n${text}\n`);
+        if (isError)
+            process.exit(1);
+        return;
+    }
+    if (sub === "daemon") {
+        const intervalFlag = process.argv.indexOf("--interval");
+        const intervalMinutes = intervalFlag !== -1 ? Number(process.argv[intervalFlag + 1]) : 15;
+        if (!(intervalMinutes > 0)) {
+            console.error(`  ${C.red}✗ --interval must be a positive number of minutes${C.reset}\n`);
+            process.exit(1);
+        }
+        console.log(`\n  ${C.cyan}${C.bold}finch orders daemon${C.reset} ${C.dim}- ticking every ${intervalMinutes}m, Ctrl+C to stop${C.reset}`);
+        console.log(`  ${C.dim}Kill-switch: RH_ORDERS_DISABLED=1 or create ~/.finch/rh-orders.OFF${C.reset}`);
+        console.log(`  ${C.dim}Note: this only runs while this process stays alive - for something that${C.reset}`);
+        console.log(`  ${C.dim}survives reboots/terminal closure, use \`finch orders install-scheduler\` instead.${C.reset}\n`);
+        let running = false; // skip a tick if the previous one is still in flight (slow RPC), don't queue up
+        const tick = async () => {
+            if (running)
+                return;
+            running = true;
+            const ts = new Date().toISOString();
+            try {
+                const { text } = await runOrdersTick(true);
+                console.log(`  ${C.dim}[${ts}]${C.reset}`);
+                console.log(text.split("\n").map((l) => `  ${l}`).join("\n") + "\n");
+            }
+            catch (err) {
+                console.error(`  ${C.red}[${ts}] tick error: ${err.message ?? err}${C.reset}\n`);
+            }
+            finally {
+                running = false;
+            }
+        };
+        await tick();
+        const timer = setInterval(tick, intervalMinutes * 60000);
+        const shutdown = () => {
+            clearInterval(timer);
+            console.log(`\n  ${C.dim}Stopped.${C.reset}\n`);
+            process.exit(0);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        return; // process stays alive via the interval timer
+    }
+    if (sub === "install-scheduler") {
+        installOrdersScheduler();
+        return;
+    }
+    console.log(`
+  ${C.cyan}${C.bold}finch orders${C.reset}  ${C.dim}- Robinhood Chain DCA/TP-SL orders (rh_dca_create/rh_bracket_create)${C.reset}
+  ${C.dim}do nothing on their own until one of these is running - creating an order${C.reset}
+  ${C.dim}only ever writes it locally, nothing executes it automatically by itself.${C.reset}
+
+  ${C.cyan}Commands:${C.reset}
+    finch orders tick [--execute]         Run one tick now and exit (preview by default)
+    finch orders daemon [--interval N]    Run in the foreground, ticking every N min (default 15)
+    finch orders install-scheduler        Register an OS-level recurring task (Task Scheduler / cron)
+`);
+}
 // ── Entry point ───────────────────────────────────────────────────────────────
 const cmd = process.argv[2];
 if (cmd === "install") {
@@ -1158,6 +1290,12 @@ else if (cmd === "setup") {
 else if (cmd === "vault") {
     vaultFlow();
 }
+else if (cmd === "orders") {
+    ordersFlow().catch((err) => {
+        console.error(`  ${C.red}✗ orders error: ${err.message}${C.reset}`);
+        process.exit(1);
+    });
+}
 else if (cmd === "logout") {
     const cfg = (0, config_js_1.readConfig)();
     if (!cfg.sessionToken) {
@@ -1239,6 +1377,7 @@ else if (cmd === "help" || cmd === "--help" || cmd === "-h") {
     finch doctor       Run a full health check + suggest fixes
     finch setup        Configure your own LLM key and/or local memory + vault
     finch vault        Show your local vault (location, contents, backup)
+    finch orders       Run/schedule Robinhood Chain DCA & TP-SL order ticks
     finch help         Show this help
 
   ${C.dim}Claude Code / Cursor / Windsurf / Codex / Aeon / Antigravity / Zed — anywhere MCP runs.${C.reset}

package/dist/convex.js

@@ -28,7 +28,17 @@ async function attemptConvex(url, method, headers, body, timeoutMs = 30000) {
         signal: AbortSignal.timeout(timeoutMs),
     });
 }
-async function callConvex(path, method, body, toolName = "unknown", timeoutMs = 30000) {
+async function callConvex(path, method, body, toolName = "unknown", timeoutMs = 30000, 
+// Fund-moving mutations (stake, unstake, claim rewards, a real - non-
+// dryRun - automation trigger) are NOT idempotent server-side: there is
+// no request-id dedup on the backend, so silently retrying a POST whose
+// response was merely lost (a network blip or client-side timeout AFTER
+// the server already processed it) can double-execute a real transfer.
+// Pass true here for any such call - it trades the convenience of an
+// automatic retry for never risking a duplicate execution; the caller
+// sees a clear "may have already gone through" error instead and can
+// check status before deciding to retry by hand.
+noRetry = false) {
     const url = `${exports.CONVEX_SITE}${path}`;
     const headers = { "Content-Type": "application/json" };
     const apiKey = process.env.FINCH_API_KEY;
@@ -66,7 +76,8 @@ async function callConvex(path, method, body, toolName = "unknown", timeoutMs =
     if (process.env.BANKR_API_KEY)
         headers["X-User-Bankr-Key"] = process.env.BANKR_API_KEY;
     let lastError = null;
-    for (let attempt = 0; attempt < RETRY_DELAYS.length; attempt++) {
+    const attempts = noRetry ? 1 : RETRY_DELAYS.length;
+    for (let attempt = 0; attempt < attempts; attempt++) {
         if (attempt > 0) {
             await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt - 1]));
         }
@@ -75,7 +86,14 @@ async function callConvex(path, method, body, toolName = "unknown", timeoutMs =
             res = await attemptConvex(url, method, headers, body, timeoutMs);
         }
         catch (err) {
-            lastError = err;
+            // Ambiguous: the request may never have reached the server, or it may
+            // have been received and even processed before the connection died -
+            // there's no way to tell from here. Safe to retry for read-only/
+            // idempotent calls; for a fund-moving one, retrying risks resending a
+            // mutation that already landed.
+            lastError = noRetry
+                ? new Error(`${err?.message ?? err} - request may or may not have completed (no response received). Check status before retrying manually.`)
+                : err;
             continue;
         }
         if (res.status === 402) {
@@ -89,7 +107,7 @@ async function callConvex(path, method, body, toolName = "unknown", timeoutMs =
                 `Hint: ${b.hint || 'Add FINCH_SESSION_TOKEN=… to the env block in your MCP config'}\n\n` +
                 `${b.alternative ? `Alternative: ${b.alternative}` : ""}`);
         }
-        if (RETRY_STATUSES.has(res.status) && attempt < RETRY_DELAYS.length) {
+        if (RETRY_STATUSES.has(res.status) && attempt < attempts - 1) {
             // Capture the actual body so a deterministic error (e.g. "unknown
             // token") that happens to come back on a 500 still surfaces its real
             // message if retries exhaust - previously this discarded the body
@@ -99,6 +117,15 @@ async function callConvex(path, method, body, toolName = "unknown", timeoutMs =
             lastError = new Error(`Finch API error ${res.status}: ${bodyText.slice(0, 300) || "(no body)"}`);
             continue;
         }
+        // noRetry + a retryable status on the one and only attempt: the server
+        // definitely received this one (unlike the network-exception case
+        // above), so it may have partially or fully processed it before
+        // erroring - same "check before retrying" caution, worded for the case
+        // where we know a response did come back.
+        if (RETRY_STATUSES.has(res.status) && noRetry) {
+            const bodyText = await res.text().catch(() => "");
+            throw new Error(`Finch API error ${res.status}: ${bodyText.slice(0, 300) || "(no body)"} - the server received this request and may have processed it before erroring. Check status before retrying manually.`);
+        }
         if (!res.ok)
             throw new Error(`Finch API error: ${res.status} ${await res.text()}`);
         return res.json();

package/dist/tools/agents.js

@@ -43,7 +43,7 @@ async function extractLearning(goal, priorUpdates, priorLearnings, latest) {
     // the catch below swallows that into a silent skip. This early return just
     // avoids building the prompt for a call we already know will fail.
     const hasLLM = !!(process.env.BANKR_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY || process.env.GROK_API_KEY);
-    if (!hasLLM && !process.env.FINCH_SESSION_TOKEN) {
+    if (!hasLLM) {
         return null;
     }
     // Build the user prompt with all the context the model needs.

package/dist/tools/automation.js

@@ -301,7 +301,11 @@ async function handleAutomationTool(name, args) {
             if (!parsed.success)
                 return { content: [{ type: "text", text: `Invalid input: automationId ${parsed.error.issues[0].message}` }], isError: true };
             const { automationId, dryRun } = parsed.data;
-            const data = await (0, convex_js_1.callConvex)("/automations/run", "POST", { automationId, dryRun: !!dryRun }, "run_automation");
+            // A real (non-dryRun) trigger moves funds if the automation is a
+            // swap/send - noRetry so a lost response never risks re-sending the
+            // same trigger. A dryRun call does nothing server-side, so retrying
+            // it is harmless and stays on the default retry behavior.
+            const data = await (0, convex_js_1.callConvex)("/automations/run", "POST", { automationId, dryRun: !!dryRun }, "run_automation", 30000, !dryRun);
             if (data.error) {
                 const cat = categorizeError(data.error);
                 return {

package/dist/tools/rh-orders.js

@@ -143,8 +143,11 @@ exports.RH_ORDER_TOOLS = [
         name: "rh_dca_create",
         description: "Robinhood Chain — create a DCA plan: buy a fixed ETH amount of a token every N hours, " +
             "up to a total number of buys, capped by maxSpendEth. Token by catalog symbol, crypto " +
-            "ticker, or 0x contract address (resolved via DexScreener). Does NOT execute now — the " +
-            "scheduler runs it via rh_orders_tick. Always confirm the resolved contract address first.",
+            "ticker, or 0x contract address (resolved via DexScreener). Does NOT execute now and does " +
+            "NOT run itself automatically — this only saves the plan. It fires only when something calls " +
+            "rh_orders_tick {execute:true}, which nothing does on its own. Tell the user to run " +
+            "`finch orders install-scheduler` (or `finch orders daemon`) after creating this, or the " +
+            "order will just sit there forever. Always confirm the resolved contract address first.",
         inputSchema: {
             type: "object",
             properties: {
@@ -165,9 +168,11 @@ exports.RH_ORDER_TOOLS = [
     {
         name: "rh_bracket_create",
         description: "Robinhood Chain — set take-profit and/or stop-loss on a token you HOLD. When DexScreener " +
-            "price crosses tpPriceUsd (≥) or slPriceUsd (≤), the scheduler sells sellPct% of your " +
-            "current balance for ETH via rh_orders_tick. Provide at least one of tpPriceUsd / slPriceUsd. " +
-            "Only ever sells tokens already in the wallet — never borrows or shorts.",
+            "price crosses tpPriceUsd (≥) or slPriceUsd (≤), sellPct% of the current balance sells for " +
+            "ETH — but only when something calls rh_orders_tick {execute:true}, which nothing does on " +
+            "its own by default. Tell the user to run `finch orders install-scheduler` (or `finch orders " +
+            "daemon`) after creating this, or the trigger will never actually fire. Provide at least one " +
+            "of tpPriceUsd / slPriceUsd. Only ever sells tokens already in the wallet — never borrows or shorts.",
         inputSchema: {
             type: "object",
             properties: {
@@ -209,7 +214,9 @@ exports.RH_ORDER_TOOLS = [
         description: "Robinhood Chain — evaluate all active orders and act on any that are due (DCA interval " +
             "reached) or triggered (TP/SL price crossed). PREVIEW by default; pass execute:true to " +
             "broadcast real swaps. Refuses to execute when the kill-switch is set (RH_ORDERS_DISABLED=1 " +
-            "or ~/.finch/rh-orders.OFF). This is the entry point an always-on scheduler calls.",
+            "or ~/.finch/rh-orders.OFF). Nothing calls this automatically — run `finch orders install-scheduler` " +
+            "(OS-level recurring task) or `finch orders daemon` (foreground loop) from a terminal to make " +
+            "orders actually fire unattended; calling this tool by hand only ticks once.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/stake.js

@@ -261,7 +261,7 @@ async function handleStakeTool(name, args) {
                 isError: true,
             };
         }
-        const result = await (0, convex_js_1.callConvex)("/mcp/stake/stake", "POST", { amountWei: amountWei.toString(), lockTier }, "stake_finch");
+        const result = await (0, convex_js_1.callConvex)("/mcp/stake/stake", "POST", { amountWei: amountWei.toString(), lockTier }, "stake_finch", 30000, true);
         if (result.error)
             return { content: [{ type: "text", text: `Stake failed: ${result.error}` }], isError: true };
         const tier = STAKING_TIERS[lockTier ?? 7];
@@ -309,7 +309,7 @@ async function handleStakeTool(name, args) {
         }
         const lines = [];
         for (const id of targetIds) {
-            const result = await (0, convex_js_1.callConvex)("/mcp/stake/unstake", "POST", { stakeId: id }, "unstake_finch");
+            const result = await (0, convex_js_1.callConvex)("/mcp/stake/unstake", "POST", { stakeId: id }, "unstake_finch", 30000, true);
             if (result.error) {
                 lines.push(`🔴 \`${id}\`: ${result.error}`);
             }
@@ -330,7 +330,7 @@ async function handleStakeTool(name, args) {
         const login = requireLogin();
         if (!login)
             return { content: [{ type: "text", text: NOT_LOGGED_IN_MSG }], isError: true };
-        const result = await (0, convex_js_1.callConvex)("/mcp/stake/claim-rewards", "POST", {}, "claim_vested_rewards");
+        const result = await (0, convex_js_1.callConvex)("/mcp/stake/claim-rewards", "POST", {}, "claim_vested_rewards", 30000, true);
         if (result.error)
             return { content: [{ type: "text", text: `Claim failed: ${result.error}` }], isError: true };
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finchagentic/mcp",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "description": "The runtime layer for Agentic AI. Persistent memory, autonomous agents, and workflows that survive every session.",
   "main": "dist/index.js",
   "bin": {