@finchagentic/mcp 4.2.0 → 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.2.0 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.2.0 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.2.0 finch-mcp
   "mcpServers": {
     "finch": {
       "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.2.0", "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.2.0 finch-mcp
     "finch": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.2.0", "finch-mcp"]
+      "args": ["-y", "-p", "@finchagentic/mcp@4.5.0", "finch-mcp"]
     }
   }
 }
@@ -79,7 +79,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.2.0 finch-mcp
 
 </details>
 
-No LLM API key is required to start — 108 of 113 tools are plain reads/writes/on-chain calls that your MCP client's own model already drives; only 5 (`ask_finch`, `deep_research`, and scheduled agent learning) do their own multi-step reasoning server-side and need a key (see [Configuration](#configuration)). Tools load on first use.
+No LLM API key is required to start — 111 of 116 tools are plain reads/writes/on-chain calls that your MCP client's own model already drives; only 5 (`ask_finch`, `deep_research`, and scheduled agent learning) do their own multi-step reasoning server-side and need a key (see [Configuration](#configuration)). Tools load on first use.
 
 ## Quick start
 
@@ -87,6 +87,7 @@ No LLM API key is required to start — 108 of 113 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:
@@ -99,15 +100,19 @@ save this thesis to vault
 
 ## What you get
 
-**113 tools** across four pillars:
+**116 tools** across four pillars:
 
 | Pillar | What it does |
 |--------|----------------|
 | **Memory** | Full-text searchable memory + versioned vault + chronicle |
-| **Agents** | Spawn, recall, update named agents |
-| **Workflows** | Automations, monitors, packets, deep research |
+| **Agents** | Spawn, recall, update named agents — `agent_recall` also pulls related memory/vault context matching the agent's goal, not just its own logged updates |
+| **Workflows** | Automations, monitors, packets, deep research (auto-saves reports + auto-links related past research) |
 | **Execution** | Base DeFi, Robinhood Chain, market data, web, GitHub |
 
+Coding and research sessions persist the same way: `deep_research` auto-saves its report to vault and links it to related past reports; `code_session_save` does the same for coding/debugging sessions (`vault_save type=code`, versioned per project, auto-linked). Both exist so the next session — yours or another agent's — starts with real context instead of cold.
+
+`vault_save` and `agent_spawn` also take an optional `workspaceProject` - the same named Projects a user organizes their Agents/vault content into on the webapp's Agents page. Pass a name and it's matched case-insensitively or created automatically (`list_projects` to browse what exists first). Hosted vault only - local-vault mode has no project concept.
+
 Default palette is `core` (lighter context). Full set:
 
 ```json
@@ -119,7 +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.2.0 finch setup
+npx -y -p @finchagentic/mcp@4.5.0 finch setup
 # enable local vault (and optional local memory)
 ```
 
@@ -146,12 +151,12 @@ Scheduled/cloud features still need an account. Core memory, vault, and public-d
 | `GITHUB_TOKEN` | For `github_search_code` |
 | `ALCHEMY_API_KEY` | Faster Base RPC (optional) |
 
-**Cost model:** almost everything is free to run — the other 108 tools are plain API/RPC calls, and your MCP client's own model (Claude, GPT, whatever's driving the chat) does all the tool-selection reasoning at no cost to Finch. The 5 exceptions above need their own key because their reasoning happens *inside* the tool call, invisible to your client, and can't be delegated to it. Set exactly one of the four env vars and every tool that needs it will use it automatically.
+**Cost model:** almost everything is free to run — the other 110 tools are plain API/RPC calls, and your MCP client's own model (Claude, GPT, whatever's driving the chat) does all the tool-selection reasoning at no cost to Finch. The 5 exceptions above need their own key because their reasoning happens *inside* the tool call, invisible to your client, and can't be delegated to it. Set exactly one of the four env vars and every tool that needs it will use it automatically.
 
 Guided setup:
 
 ```bash
-npx -y -p @finchagentic/mcp@4.2.0 finch setup
+npx -y -p @finchagentic/mcp@4.5.0 finch setup
 ```
 
 ## Security
@@ -160,7 +165,7 @@ npx -y -p @finchagentic/mcp@4.2.0 finch setup
 |:-:|----------|------|
 | 1 | Prompt injection | External content is data only — never instructions |
 | 2 | Mainnet confirm | Estimate → preview → confirm → execute |
-| 3 | Pinned install | Always `@finchagentic/mcp@4.2.0`, 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/annotations.js

@@ -26,7 +26,7 @@ const WRITE_IDEMPOTENT = new Set([
 const WRITE = new Set([
     "agent_spawn",
     "chronicle_add",
-    "create_automation",
+    "code_session_save",
     "memory_add",
     "memory_extract",
     "memory_consolidate",
@@ -65,6 +65,13 @@ const DESTRUCTIVE = new Set([
     "rh_mcp_swap",
     "rh_dca_create", // arms recurring real buys
     "rh_bracket_create", // arms real TP/SL sells
+    // a swap/send automation arms unattended, REPEATING real fund movement
+    // (the backend's 1-minute cron evaluator fires it) - same risk class as
+    // rh_dca_create/rh_bracket_create above, not a plain additive write. An
+    // alert-only automation doesn't move funds, but the tool can't tell which
+    // kind it's about to create until AFTER the backend parses rawInput, so
+    // it's classified by its worst case, same reasoning as rh_orders_tick.
+    "create_automation",
     "rh_orders_tick", // preview by default, but can execute:true and move funds
     // executors that run other (possibly fund-moving) tools
     "run_automation",
@@ -73,6 +80,7 @@ const DESTRUCTIVE = new Set([
     // for a fixed period; unstake moves it (plus rewards) back
     "stake_finch",
     "unstake_finch",
+    "claim_vested_rewards", // treasury -> custodial wallet USDG transfer
 ]);
 function annotationsFor(name) {
     if (DESTRUCTIVE.has(name)) {

package/dist/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/index.js

@@ -66,14 +66,17 @@ const C = {
     reset: "\x1b[0m",
     bold: "\x1b[1m",
 };
+// Was still spelling out the pre-rebrand "NOELCLAW" wordmark in ASCII art -
+// leftover from before the Finch rebrand, never caught because nothing
+// visually diffs a banner string.
 const BANNER = `
 ${C.cyan}
-  ███╗   ██╗ ██████╗ ███████╗██╗      ██████╗██╗      █████╗ ██╗    ██╗
-  ████╗  ██║██╔═══██╗██╔════╝██║     ██╔════╝██║     ██╔══██╗██║    ██║
-  ██╔██╗ ██║██║   ██║█████╗  ██║     ██║     ██║     ███████║██║ █╗ ██║
-  ██║╚██╗██║██║   ██║██╔══╝  ██║     ██║     ██║     ██╔══██║██║███╗██║
-  ██║ ╚████║╚██████╔╝███████╗███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝
-  ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝
+  ███████╗██╗███╗   ██╗ ██████╗██╗  ██╗
+  ██╔════╝██║████╗  ██║██╔════╝██║  ██║
+  █████╗  ██║██╔██╗ ██║██║     ███████║
+  ██╔══╝  ██║██║╚██╗██║██║     ██╔══██║
+  ██║     ██║██║ ╚████║╚██████╗██║  ██║
+  ╚═╝     ╚═╝╚═╝  ╚═══╝ ╚═════╝╚═╝  ╚═╝
 ${C.reset}`;
 function line(label, value, color = C.cyan) {
     const pad = " ".repeat(Math.max(0, 12 - label.length));
@@ -114,9 +117,9 @@ async function main() {
         { label: "Base MCP", match: n => n.startsWith("base_mcp_") },
         { label: "RH MCP", match: n => n.startsWith("rh_") },
         { label: "Automation", match: n => /^(create_automation|list_automations|pause_automation|delete_automation|get_automation_runs|run_automation)$/.test(n) },
-        { label: "Vault", match: n => n.startsWith("vault_") },
+        { label: "Vault", match: n => n.startsWith("vault_") || n === "code_session_save" || n === "list_projects" },
         { label: "Wallet", match: n => /^(get_wallet_address|get_wallet_balance|wallet_sign_message)$/.test(n) },
-        { label: "Staking", match: n => /^(stake_finch|unstake_finch|stake_finch_status|stake_auto_restake)$/.test(n) },
+        { label: "Staking", match: n => /^(stake_finch|unstake_finch|stake_finch_status|stake_auto_restake|claim_vested_rewards)$/.test(n) },
         { label: "MiroShark", match: n => n.startsWith("miroshark_") },
         { label: "Scanner", match: n => /^(scan_market|score_token|check_token)$/.test(n) },
         { label: "Agents", match: n => n.startsWith("agent_") },

package/dist/project.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLocalVaultActive = isLocalVaultActive;
+exports.resolveProjectId = resolveProjectId;
+const convex_js_1 = require("./convex.js");
+const local_vault_js_1 = require("./local-vault.js");
+// MCP has no persistent "active project" UI state the way the webapp Sidebar
+// switcher does - a caller (vault_save, agent_spawn) names the project it
+// wants by string on each call instead. Resolution + auto-create both happen
+// server-side (POST /projects/resolve, see convex/http.ts +
+// convex/projects.ts's resolveOrCreateProjectForUser) so the match/dedup
+// logic exists in exactly one place, shared with the webapp's own project
+// picker.
+//
+// Local-vault mode (vaultBackend: "local") has no project concept at all -
+// it's a flat, unauthenticated file store on the user's own machine with no
+// server to resolve a name against. Callers should check
+// isLocalVaultActive() first and skip resolution entirely rather than call
+// this and get a confusing network-style failure.
+function isLocalVaultActive() {
+    return !!(0, local_vault_js_1.getLocalVaultConfig)();
+}
+async function resolveProjectId(name) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return await (0, convex_js_1.callConvex)("/projects/resolve", "POST", { name: trimmed }, "vault_save");
+    }
+    catch {
+        // Resolution is best-effort - a save should never fail just because the
+        // project lookup did. Falls back to unassigned, same as the webapp's
+        // agent_spawn membership check when a stale/bad id doesn't match.
+        return null;
+    }
+}

package/dist/server.js

@@ -115,7 +115,7 @@ exports.ALL_TOOLS = [
     // SWARM_TOOLS removed v3.19 - multi-agent research is now built into
     // deep_research (depth=standard|deep). Handler fully removed v3.21.
     // FRAMEWORK_TOOLS removed - list_playbooks/run_playbook/get_finch_ledger backend routes never existed, see tools/ import comment above.
-    ...vault_js_1.VAULT_TOOLS, // 15 - save, read, list, search, history, diff, export, pin, unpublish, tag, delete, link, related, store_credential, get_credential
+    ...vault_js_1.VAULT_TOOLS, // 17 - save, code_session_save, read, list, search, history, diff, export, pin, unpublish, tag, delete, link, related, store_credential, get_credential, list_projects
     ...wallet_js_1.WALLET_TOOLS, // 3 - get_wallet_address, get_wallet_balance, wallet_sign_message
     ...miroshark_js_1.MIROSHARK_TOOLS, // 3 - simulate, status, stop
     ...agents_js_1.AGENT_TOOLS, // 4 - agent_spawn, agent_recall, agent_update, agent_ledger (vault-backed, all working). list_agents/hire_agent and the autonomous-schedule tools (agent_identity/agent_schedule/agent_unschedule/agent_pause/agent_resume/agent_runs) removed - their backend routes were never implemented, see tools/agents.ts
@@ -139,14 +139,22 @@ exports.ALL_TOOLS = [
     ...github_js_1.GITHUB_TOOLS, // 8 - list_repos, list_prs, get_pr, list_issues, get_issue, get_file, get_commits, search_code
     ...chronicle_js_1.CHRONICLE_TOOLS, // 4 - chronicle_add, chronicle_list, chronicle_search, chronicle_stats
     ...packets_js_1.PACKET_TOOLS, // 4 - packet_create, packet_run, packet_list, packet_share
-    ...stake_js_1.STAKE_TOOLS, // 4 - stake_finch_status, stake_finch, unstake_finch, stake_auto_restake (custodial wallet; requires `finch login`)
-    // total: 113 tools as measured by ALL_TOOLS.length - do not hand-maintain a
+    ...stake_js_1.STAKE_TOOLS, // 5 - stake_finch_status, stake_finch, unstake_finch, claim_vested_rewards, stake_auto_restake (custodial wallet; requires `finch login`)
+    // total: 116 tools as measured by ALL_TOOLS.length - do not hand-maintain a
     // count in this comment (drifted stale multiple times already: before
     // staking was added, after the P1 audit removed 9 dead framework/agent-
     // schedule tools, after memory_publish was removed for promising a
-    // marketplace that doesn't exist, and after stake_auto_restake was added;
-    // ALL_TOOLS.length is the only number that can't lie). Per-category counts
-    // above are best-effort documentation, not load-bearing anywhere.
+    // marketplace that doesn't exist, after stake_auto_restake was added,
+    // after claim_vested_rewards was added to close the gap where the
+    // stake-lifecycle notification told users to "run claimVestedRewards" but
+    // no MCP tool by that name existed, after code_session_save was added so
+    // coding sessions persist the same way deep_research already auto-saves
+    // research, and after list_projects was added alongside `workspaceProject`
+    // support on vault_save/agent_spawn - MCP tools can now file into the same
+    // Projects the webapp Agents page organizes by, resolved/auto-created
+    // server-side via POST /projects/resolve; ALL_TOOLS.length is the only
+    // number that can't lie). Per-category counts above are best-effort
+    // documentation, not load-bearing anywhere.
 ];
 exports.HANDLER_MAP = new Map([
     ...market_js_1.MARKET_TOOLS.map(t => [t.name, market_js_1.handleMarketTool]),

package/dist/tool-filter.js

@@ -27,11 +27,11 @@ exports.filterTools = filterTools;
 // through that same preset). New tools MUST match a preset or the test fails
 // the build, instead of quietly vanishing like these did.
 const PRESETS = {
-    core: /^(memory_|vault_|agent_|ask_finch|finch_status|finch_diagnostics|finch_shell_chat|get_wallet_address|get_wallet_balance|wallet_sign_message|chronicle_|packet_)/,
-    defi: /^(get_market_data|get_token_data|compare_tokens|market_overview|token_history|get_base_token_data|stock_fundamentals|stock_insider|stock_events|market_thesis|trade_plan|base_mcp_|rh_|base_|get_defi_yields|score_token|check_token|scan_market|get_wallet_balance|wallet_sign_message|create_automation|list_automations|pause_automation|delete_automation|get_automation_runs|run_automation|miroshark_|stake_|unstake_finch)/,
-    research: /^(memory_|vault_|deep_research|research_compare|research_chain|web_search|web_scrape|schedule_research|list_monitors|cancel_monitor|ask_finch|stock_fundamentals|stock_insider|stock_events)/,
-    memory: /^(memory_|vault_|agent_|chronicle_)/,
-    coder: /^(audit_contract|github_)/,
+    core: /^(memory_|vault_|code_session_save|list_projects|agent_|ask_finch|finch_status|finch_diagnostics|finch_shell_chat|get_wallet_address|get_wallet_balance|wallet_sign_message|chronicle_|packet_)/,
+    defi: /^(get_market_data|get_token_data|compare_tokens|market_overview|token_history|get_base_token_data|stock_fundamentals|stock_insider|stock_events|market_thesis|trade_plan|base_mcp_|rh_|base_|get_defi_yields|score_token|check_token|scan_market|get_wallet_balance|wallet_sign_message|create_automation|list_automations|pause_automation|delete_automation|get_automation_runs|run_automation|miroshark_|stake_|unstake_finch|claim_vested_rewards)/,
+    research: /^(memory_|vault_|code_session_save|list_projects|deep_research|research_compare|research_chain|web_search|web_scrape|schedule_research|list_monitors|cancel_monitor|ask_finch|stock_fundamentals|stock_insider|stock_events)/,
+    memory: /^(memory_|vault_|code_session_save|list_projects|agent_|chronicle_)/,
+    coder: /^(audit_contract|github_|code_session_save)/,
 };
 function filterTools(allTools) {
     // Default is "core" - keeps LLM context cost low while everything

package/dist/tools/agents.js

@@ -7,6 +7,8 @@ const zod_1 = require("zod");
 const convex_js_1 = require("../convex.js");
 const llm_js_1 = require("../llm.js");
 const local_vault_js_1 = require("../local-vault.js");
+const memory_js_1 = require("./memory.js");
+const project_js_1 = require("../project.js");
 // ─── Agent Learning Memory (v3.25) ──────────────────────────────────────────
 // After every agent_update, an LLM reviews the new progress in context of the
 // agent's goal + prior learnings to extract a single repeatable insight. The
@@ -41,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.
@@ -133,6 +135,12 @@ exports.AGENT_TOOLS = [
                 name: { type: "string", description: "Unique agent name (e.g. 'market-researcher', 'onboarding-helper')" },
                 goal: { type: "string", description: "What this agent is trying to accomplish" },
                 context: { type: "string", description: "Optional starting context, data, or notes for the agent" },
+                workspaceProject: {
+                    type: "string",
+                    description: "Optional: file this agent into a named Finch workspace project (visible on the Agents page's " +
+                        "project switcher). Matched case-insensitively by name; created automatically if it doesn't exist " +
+                        "yet. Hosted vault only (no effect in local-vault mode).",
+                },
             },
             required: ["name", "goal"],
         },
@@ -140,6 +148,8 @@ exports.AGENT_TOOLS = [
     {
         name: "agent_recall",
         description: "Recall a persistent agent by name - loads its goal, current progress, findings, full history, and accumulated learnings (patterns the agent extracted from past runs). " +
+            "Also pulls related context from memory/vault (code_session_save entries, deep_research reports, notes) matching the agent's goal, " +
+            "so recall reflects everything relevant to the goal - not just what agent_update explicitly logged. " +
             "Use this to resume a long-running task, check what an agent last did, or hand context to a fresh LLM session. " +
             "Learnings compound over time - the more an agent runs, the smarter recall becomes.",
         inputSchema: {
@@ -192,6 +202,7 @@ const SpawnAgentSchema = zod_1.z.object({
     name: zod_1.z.string().min(1).max(60).regex(/^[a-z0-9-]+$/, "name must be lowercase alphanumeric with hyphens"),
     goal: zod_1.z.string().min(1),
     context: zod_1.z.string().optional(),
+    workspaceProject: zod_1.z.string().optional(),
 });
 const RecallAgentSchema = zod_1.z.object({ name: zod_1.z.string().min(1) });
 const UpdateAgentSchema = zod_1.z.object({
@@ -217,8 +228,8 @@ async function handleAgentTool(name, args) {
     if (name === "agent_spawn") {
         const parsed = SpawnAgentSchema.safeParse(args);
         if (!parsed.success)
-            return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
-        const { name: agentName, goal, context } = parsed.data;
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
+        const { name: agentName, goal, context, workspaceProject } = parsed.data;
         const content = JSON.stringify({
             goal,
             status: "active",
@@ -237,19 +248,30 @@ async function handleAgentTool(name, args) {
             commitMsg: "spawned",
         };
         const localVault = (0, local_vault_js_1.getLocalVaultConfig)();
+        // Resolve the project name -> id server-side (auto-creates on first use).
+        // No-op in local-vault mode - there is no project concept there.
+        let resolvedProjectName = null;
+        if (workspaceProject && !localVault) {
+            const resolved = await (0, project_js_1.resolveProjectId)(workspaceProject);
+            if (resolved) {
+                savePayload.projectId = resolved.projectId;
+                resolvedProjectName = resolved.name;
+            }
+        }
         const data = localVault
             ? (0, local_vault_js_1.localVaultSave)(localVault, savePayload)
             : await (0, convex_js_1.callConvex)("/vault/save", "POST", savePayload, "vault_save");
         if (data.error)
             return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
+        const projectLine = resolvedProjectName ? `\n**Project:** ${resolvedProjectName}` : "";
         return {
-            content: [{ type: "text", text: `🤖 Agent **${agentName}** spawned${localVault ? " locally" : ""}.\n\n**Goal:** ${goal}\n\nRecall with \`agent_recall\` · Update progress with \`agent_update\`` }],
+            content: [{ type: "text", text: `🤖 Agent **${agentName}** spawned${localVault ? " locally" : ""}.\n\n**Goal:** ${goal}${projectLine}\n\nRecall with \`agent_recall\` · Update progress with \`agent_update\`` }],
         };
     }
     if (name === "agent_recall") {
         const parsed = RecallAgentSchema.safeParse(args);
         if (!parsed.success)
-            return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
         const localVault = (0, local_vault_js_1.getLocalVaultConfig)();
         let data;
         try {
@@ -291,12 +313,30 @@ async function handleAgentTool(name, args) {
             lines.push(`\n**Recent updates:**\n${updates.join("\n")}`);
         if (state.nextStep)
             lines.push(`\n**Next step:** ${state.nextStep}`);
+        // Related context - best-effort pull of relevant memory/vault knowledge
+        // (code_session_save entries, deep_research reports, manual notes) so the
+        // agent isn't blind to work done on its goal outside its own update log.
+        // This is what makes recall "continuously have context" rather than only
+        // ever knowing what agent_update explicitly logged.
+        if (state.goal) {
+            try {
+                const related = await (0, memory_js_1.hybridMemorySearch)(state.goal, 4);
+                if (related.length) {
+                    lines.push(`\n**📎 Related context (${related.length}):**`);
+                    related.forEach((r) => {
+                        const title = r.metadata?.title ?? r.content.slice(0, 70).replace(/\n/g, " ");
+                        lines.push(`  • ${title}`);
+                    });
+                }
+            }
+            catch { /* best-effort - recall must never fail because of this */ }
+        }
         return { content: [{ type: "text", text: lines.join("\n") }] };
     }
     if (name === "agent_update") {
         const parsed = UpdateAgentSchema.safeParse(args);
         if (!parsed.success)
-            return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
         const { name: agentName, progress, findings, status = "active", nextStep } = parsed.data;
         return withAgentLock(agentName, async () => {
             const localVault = (0, local_vault_js_1.getLocalVaultConfig)();