@finchagentic/mcp 4.0.0

package/dist/agent-loop.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgent = runAgent;
+const server_js_1 = require("./server.js");
+const llm_js_1 = require("./llm.js");
+const convex_js_1 = require("./convex.js");
+const SYSTEM_PROMPT = [
+    `You are Finch, the runtime layer for Agentic AI - with ${server_js_1.ALL_TOOLS.length} tools spanning memory, vault, deep research, persistent agents, code, automations, DeFi, and GitHub.`,
+    "Be direct and concise. Pick the right tool - don't narrate the choice. Summarize tool results in plain English.",
+    "",
+    "CRITICAL - on-chain / financial actions (swap, send, transfer, buy, sell, bridge, lend, deposit, withdraw, balance):",
+    "- You MUST call the corresponding tool. NEVER write 'Sent', 'Swapped', 'Tx confirmed', or any execution claim without an actual tool call returning a result first.",
+    "- Tx hash and basescan/explorer URL from the tool output are MANDATORY in your reply - show them verbatim, do not omit or paraphrase.",
+    "- NEVER fabricate a post-transaction balance with arithmetic. If user wants the new balance, call the balance tool again - do not compute it from a prior balance + amount.",
+    "- For ALL Base chain operations, you MUST use the base_mcp_* family: base_mcp_swap (NOT swap_tokens), base_mcp_send (NOT send_token), base_mcp_balance (NOT get_portfolio), base_mcp_estimate, base_mcp_resolve, base_mcp_lend, base_mcp_status. This is non-negotiable - Base operations go through the Base MCP skill, period.",
+    "- For Robinhood Chain tokenized stocks (chainId 4663, NVDA/AAPL/etc on Uniswap V4), you MUST use rh_mcp_*: rh_mcp_status, rh_mcp_list_stocks, rh_mcp_balance, rh_mcp_estimate, rh_mcp_swap. Never use base_mcp_* or 0x for RH stocks. rh_mcp_swap requires confirm:true. Explorer = robinhoodchain.blockscout.com. This is NOT Robinhood Agentic brokerage (agent.robinhood.com).",
+    "- Do NOT claim an address belongs to the user (e.g. 'your own address') unless you have verified ownership. Resolving a basename returns whoever owns that name - usually NOT the caller.",
+    "",
+    "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.",
+].join("\n");
+async function runAgent(userMessage, history, onToolCall) {
+    const bankrKey = process.env.BANKR_API_KEY;
+    const anthropicKey = process.env.ANTHROPIC_API_KEY;
+    const openaiKey = process.env.OPENAI_API_KEY;
+    if (bankrKey)
+        return runBankrLoop(bankrKey, userMessage, history, onToolCall);
+    if (anthropicKey)
+        return runAnthropicLoop(anthropicKey, userMessage, history, onToolCall);
+    if (openaiKey)
+        return runOpenAILoop(openaiKey, userMessage, history, onToolCall);
+    // No direct key - proxy through Finch backend. Wallet auto-creates at ~/.finch/wallet.json
+    // on first use and signs requests transparently. No account or config needed.
+    try {
+        return await runConvexProxiedLoop(userMessage, history, onToolCall);
+    }
+    catch {
+        // Network down or backend unavailable - plain chat fallback
+        const text = await (0, llm_js_1.callLLM)(SYSTEM_PROMPT, userMessage, 1024, history);
+        return { text, toolCalls: [] };
+    }
+}
+// ── Anthropic agent loop ─────────────────────────────────────────────────────
+function toAnthropicTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description ?? "",
+        input_schema: tool.inputSchema ?? { type: "object", properties: {} },
+    };
+}
+async function runAnthropicLoop(apiKey, 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++) {
+        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();
+        messages.push({ role: "assistant", content: data.content });
+        if (data.stop_reason !== "tool_use") {
+            const text = data.content
+                .filter(b => b.type === "text")
+                .map(b => b.text)
+                .join("");
+            return { text, toolCalls };
+        }
+        // Execute all tool_use blocks
+        const toolResults = [];
+        for (const block of data.content) {
+            if (block.type !== "tool_use")
+                continue;
+            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 };
+}
+// ── Convex-proxied Anthropic loop (session token only - platform covers LLM) ──
+async 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
+        const data = await (0, convex_js_1.callConvex)("/llm/complete", "POST", {
+            model,
+            max_tokens: 2048,
+            system: SYSTEM_PROMPT,
+            tools,
+            messages,
+        }, "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 };
+}
+// ── Bankr (OpenAI-compatible) agent loop ─────────────────────────────────────
+function toBankrTool(tool) {
+    return {
+        type: "function",
+        function: {
+            name: tool.name,
+            description: tool.description ?? "",
+            parameters: tool.inputSchema ?? { type: "object", properties: {} },
+        },
+    };
+}
+// Shared tool-calling loop for any OpenAI Chat Completions-compatible
+// endpoint (Bankr's LLM gateway and OpenAI itself both speak this format).
+// Only the URL, auth header, and model differ per provider.
+async function runOpenAICompatibleLoop(url, authHeaders, model, providerLabel, userMessage, history, onToolCall) {
+    const tools = server_js_1.ALL_TOOLS.map(toBankrTool);
+    const toolCalls = [];
+    const messages = [
+        { role: "system", content: SYSTEM_PROMPT },
+        ...history.map(h => ({ role: h.role, content: h.content })),
+        { role: "user", content: userMessage },
+    ];
+    for (let turn = 0; turn < 10; turn++) {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...authHeaders },
+            body: JSON.stringify({ model, messages, tools, max_tokens: 2048 }),
+            signal: AbortSignal.timeout(90000),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`${providerLabel} ${res.status}: ${body.slice(0, 300)}`);
+        }
+        const data = await res.json();
+        const choice = data.choices?.[0]?.message;
+        if (!choice)
+            throw new Error(`Empty response from ${providerLabel}`);
+        messages.push(choice);
+        if (!choice.tool_calls?.length) {
+            return { text: choice.content ?? "", toolCalls };
+        }
+        for (const call of choice.tool_calls) {
+            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}`);
+                const result = await handler(call.function.name, args);
+                resultText = result?.content?.[0]?.text ?? "Done.";
+            }
+            catch (err) {
+                resultText = `Error: ${err.message}`;
+            }
+            messages.push({ role: "tool", tool_call_id: call.id, content: resultText });
+        }
+    }
+    return { text: "Reached max tool iterations.", toolCalls };
+}
+async function runBankrLoop(apiKey, userMessage, history, onToolCall) {
+    const model = process.env.FINCH_MODEL ?? process.env.BANKR_MODEL ?? "claude-haiku-4-5-20251001";
+    return runOpenAICompatibleLoop("https://llm.bankr.bot/v1/chat/completions", { "X-API-Key": apiKey }, model, "Bankr", userMessage, history, onToolCall);
+}
+// Same OPENAI_BASE_URL override as llm.ts's callOpenAI - lets tool-calling
+// route to a self-hosted OpenAI-compatible gateway too.
+function openAiChatUrl() {
+    const base = process.env.OPENAI_BASE_URL?.replace(/\/+$/, "");
+    return base ? `${base}/chat/completions` : "https://api.openai.com/v1/chat/completions";
+}
+async function runOpenAILoop(apiKey, userMessage, history, onToolCall) {
+    const model = process.env.FINCH_MODEL ?? process.env.OPENAI_MODEL ?? "gpt-4o-mini";
+    return runOpenAICompatibleLoop(openAiChatUrl(), { Authorization: `Bearer ${apiKey}` }, model, "OpenAI", userMessage, history, onToolCall);
+}

package/dist/annotations.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MUTATING_TOOL_NAMES = void 0;
+exports.annotationsFor = annotationsFor;
+exports.withAnnotations = withAnnotations;
+const output_schemas_js_1 = require("./output-schemas.js");
+// Read-only AND no network - a purely local computation (static analysis).
+// Read-only but open-world is the default, so this set only exists to flip
+// openWorldHint off for the rare offline tool.
+const READ_ONLY_LOCAL = new Set([
+    "audit_contract", // deterministic static Solidity scan, no backend call
+]);
+// readOnly=false, destructive=false, idempotent=true.
+// Toggles and upserts: re-running with the same args lands in the same state.
+const WRITE_IDEMPOTENT = new Set([
+    "agent_update",
+    "agent_schedule",
+    "agent_pause",
+    "agent_resume",
+    "agent_unschedule",
+    "pause_automation",
+    "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",
+    "miroshark_simulate",
+    "finch_shell_chat", // orchestrator: can spawn/save/create via delegated tools
+]);
+// readOnly=false, destructive=true.
+// Deletes, cancels, irreversible publishes, and anything that moves real funds
+// (or arms an order engine that will). Clients should confirm before running.
+const DESTRUCTIVE = new Set([
+    // removals / cancels
+    "cancel_monitor",
+    "delete_automation",
+    "memory_delete",
+    "miroshark_stop",
+    "rh_order_cancel",
+    "vault_delete",
+    // irreversible public exposure
+    "memory_publish", // "IRREVERSIBLE, PUBLIC" per its own description
+    // money movement (Base)
+    "base_mcp_send",
+    "base_mcp_swap",
+    "base_mcp_lend",
+    // money movement (Robinhood Chain)
+    "rh_mcp_swap",
+    "rh_dca_create", // arms recurring real buys
+    "rh_bracket_create", // arms real TP/SL sells
+    "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",
+]);
+function annotationsFor(name) {
+    if (DESTRUCTIVE.has(name)) {
+        return { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
+    }
+    if (WRITE_IDEMPOTENT.has(name)) {
+        return { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+    }
+    if (WRITE.has(name)) {
+        return { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
+    }
+    if (READ_ONLY_LOCAL.has(name)) {
+        return { readOnlyHint: true, openWorldHint: false };
+    }
+    return { readOnlyHint: true, openWorldHint: true };
+}
+// Decorate a tool list with MCP metadata: behavioural annotations
+// (readOnly/destructive/etc) and, for tools registered in OUTPUT_SCHEMAS, a
+// machine-readable `outputSchema`. A value already present on the tool is left
+// untouched, so a module can always override either.
+function withAnnotations(tools) {
+    return tools.map((t) => {
+        const patch = {};
+        if (!t.annotations)
+            patch.annotations = annotationsFor(t.name);
+        if (!t.outputSchema && output_schemas_js_1.OUTPUT_SCHEMAS[t.name]) {
+            patch.outputSchema = output_schemas_js_1.OUTPUT_SCHEMAS[t.name];
+        }
+        return Object.keys(patch).length ? { ...t, ...patch } : t;
+    });
+}
+// Exported for the test suite to assert the classification only references real
+// tool names (catches typos / tools renamed out from under a set).
+exports.MUTATING_TOOL_NAMES = [
+    ...WRITE_IDEMPOTENT,
+    ...WRITE,
+    ...DESTRUCTIVE,
+    ...READ_ONLY_LOCAL,
+];