keyring-agent-core 0.1.1 → 0.2.1

package/dist/agent/AgentCore.js

@@ -13,6 +13,9 @@ const Router_1 = require("./Router");
 const subagents_1 = require("./subagents");
 const Synthesizer_1 = require("./Synthesizer");
 const QueryRewriter_1 = require("./QueryRewriter");
+const chatGraph_1 = require("./chatGraph");
+const chainResolver_1 = require("../tools/chainResolver");
+const rpc_1 = require("../services/rpc");
 /** Generate a short stable id for one response turn (8 hex chars). */
 function generateMessageId() {
     const ts = Date.now().toString(16);
@@ -43,6 +46,8 @@ class AgentCore {
     rewriter;
     subagents;
     synthesizer;
+    /** Compiled LangGraph that orchestrates one chat turn. */
+    chatGraph;
     systemPrompt;
     debug;
     userContext = {};
@@ -73,6 +78,11 @@ class AgentCore {
      */
     historyReady;
     constructor(config) {
+        // Install the core-wide RPC overrides before any RPC-using tool/service is
+        // constructed. A single shared map drives every on-chain read (gas-reserve
+        // estimation, swap allowance check, pool tools); chains not listed fall back
+        // to the built-in public defaults.
+        (0, rpc_1.setRpcOverrides)(config.rpcUrls);
         this.llm = new GeminiProvider_1.GeminiProvider(config.llm);
         this.registry = new ToolRegistry_1.ToolRegistry();
         this.history = new ChatHistory_1.ChatHistory(config.maxHistoryMessages ?? 50);
@@ -142,10 +152,8 @@ class AgentCore {
         if (config.moralis !== false) {
             const moralisConfig = typeof config.moralis === 'object' ? config.moralis : undefined;
             this.registry.register(new builtin_1.WalletTokenBalancesTool(moralisConfig));
+            // this.registry.register(new WalletNetWorthTool(moralisConfig)); deprecated
             this.registry.register(new builtin_1.TokenInfoTool(moralisConfig));
-            this.registry.register(new builtin_1.WalletNFTsTool(moralisConfig));
-            this.registry.register(new builtin_1.NFTContractInfoTool(moralisConfig));
-            this.registry.register(new builtin_1.NFTMetadataTool(moralisConfig));
             this.registry.register(new builtin_1.WalletHistoryTool(moralisConfig));
             this.registry.register(new builtin_1.WalletTokenTransfersTool(moralisConfig));
             this.registry.register(new builtin_1.WalletNftTransfersTool(moralisConfig));
@@ -153,20 +161,39 @@ class AgentCore {
             this.registry.register(new builtin_1.WalletPnlSummaryTool(moralisConfig));
             this.registry.register(new builtin_1.WalletPnlTool(moralisConfig));
             this.registry.register(new builtin_1.TransactionByHashTool(moralisConfig));
-            this.registry.register(new builtin_1.SolanaCortexTool(moralisConfig));
             this.registry.register(new builtin_1.WalletDefiSummaryTool(moralisConfig));
             this.registry.register(new builtin_1.WalletDefiPositionsTool(moralisConfig));
             this.registry.register(new builtin_1.WalletDefiProtocolPositionsTool(moralisConfig));
             this.registry.register(new builtin_1.WalletApprovalsTool(moralisConfig));
             this.registry.register(new builtin_1.TrendingTokensTool(moralisConfig));
-            // this.registry.register(new TopGainersTool(moralisConfig)); //Deprecated
-            // this.registry.register(new TopLosersTool(moralisConfig));  //Deprecated
+            this.registry.register(new builtin_1.TopGainersTool(moralisConfig));
             this.registry.register(new builtin_1.TokenAnalyticsTool(moralisConfig));
             this.registry.register(new builtin_1.TokenScoreTool(moralisConfig));
-            this.registry.register(new builtin_1.MoralisCortexTool(moralisConfig));
         }
-        // Register built-in Uniswap (DEX pool) tools
-        if (config.uniswap !== false) {
+        // NFT tools — point the user to the NFT website instead of returning
+        // on-chain data. Independent of Moralis; the only config is the optional
+        // link, which turns the "this website" phrase into a Markdown link when
+        // present. The NFT notice tools (send-nft + the nft-agent view/detail
+        // tools) all share the single `nftLink`.
+        const nftUrl = config.nftLink;
+        this.registry.register(new builtin_1.SendNftTool({ url: nftUrl }));
+        this.registry.register(new builtin_1.WalletNFTsTool({ url: nftUrl }));
+        this.registry.register(new builtin_1.NFTContractInfoTool({ url: nftUrl }));
+        this.registry.register(new builtin_1.NFTMetadataTool({ url: nftUrl }));
+        // Search-grounded Gemini fallback. Independent of Moralis — uses the same
+        // LLM proxy as the rest of the agent. Subagents wire this in as their
+        // `cortexFallbackTool` so they always have a tool to call.
+        this.registry.register(new builtin_1.GeminiSearchAiTool(config.llm));
+        // Pool subagent toggles — mirrors the mutually-exclusive logic in
+        // createDefaultSubagents (subagents/index.ts). When `pool-subgraph` is
+        // enabled it auto-disables `pool` unless the caller explicitly set it
+        // back to true. We use the same rule here so we never register a tool set
+        // whose subagent is off.
+        const poolSubgraphSubagentOn = config.subagents?.['pool-subgraph'] === true;
+        const poolSubagentOn = poolSubgraphSubagentOn ? config.subagents?.pool === true : config.subagents?.pool !== false;
+        // Register built-in Uniswap (DEX pool) tools — only when the `pool`
+        // subagent is enabled AND `uniswap` config is not turned off.
+        if (poolSubagentOn && config.uniswap !== false) {
             const uniswapConfig = typeof config.uniswap === 'object' ? config.uniswap : undefined;
             this.registry.register(new builtin_1.TopPoolsTool(uniswapConfig));
             this.registry.register(new builtin_1.PoolDetailTool(uniswapConfig));
@@ -174,12 +201,9 @@ class AgentCore {
             this.registry.register(new builtin_1.PoolByAddressTool(uniswapConfig));
             this.registry.register(new builtin_1.EstimatePoolYieldTool(uniswapConfig));
             // Add-liquidity action tools (need on-chain RPC + gateway addresses).
-            const poolServiceConfig = uniswapConfig
-                ? {
-                    rpcUrls: uniswapConfig.rpcUrls,
-                    isProduction: uniswapConfig.isProduction,
-                }
-                : undefined;
+            // RPC endpoints come from the shared core-wide `rpcUrls` (installed via
+            // setRpcOverrides above), so PoolService takes no per-chain RPC config here.
+            const poolServiceConfig = uniswapConfig ? { isProduction: uniswapConfig.isProduction } : undefined;
             this.registry.register(new builtin_1.OpenAddLiquidityFormTool({
                 baseUrl: uniswapConfig?.baseUrl,
                 pool: poolServiceConfig,
@@ -187,16 +211,51 @@ class AgentCore {
             }));
             this.registry.register(new builtin_1.PreviewAddLiquidityTool({ pool: poolServiceConfig }));
         }
+        // Register built-in subgraph-backed pool tools — only when the
+        // `pool-subgraph` subagent is enabled AND `subgraph` config is not off.
+        if (poolSubgraphSubagentOn && config.subgraph !== false) {
+            const subgraphConfig = typeof config.subgraph === 'object' ? config.subgraph : undefined;
+            this.registry.register(new builtin_1.SubgraphPoolSearchTool(subgraphConfig));
+            this.registry.register(new builtin_1.SubgraphTrendingPoolsTool(subgraphConfig));
+            this.registry.register(new builtin_1.SubgraphPoolByAddressTool(subgraphConfig));
+            this.registry.register(new builtin_1.SubgraphPoolByPositionIdTool(subgraphConfig));
+            this.registry.register(new builtin_1.SubgraphPositionDetailTool(subgraphConfig));
+            this.registry.register(new builtin_1.SubgraphCoinPoolPairsTool(subgraphConfig));
+        }
+        // Wallet-action tools — emit UI payloads only; the FE renders the form and
+        // executes the tx itself. Tools that accept `token_symbol` use Moralis to
+        // resolve the symbol → contract address (wallet balances first, then a
+        // Pantograph search). When the moralis tool family is disabled, symbol
+        // resolution is unavailable and the tools require an explicit
+        // contract_address.
+        const walletActionMoralisConfig = config.moralis === false ? undefined : typeof config.moralis === 'object' ? config.moralis : {};
+        this.registry.register(new builtin_1.SendNativeTool(walletActionMoralisConfig));
+        this.registry.register(new builtin_1.SendTokenTool(walletActionMoralisConfig));
+        this.registry.register(new builtin_1.ApproveTokenTool(walletActionMoralisConfig));
+        // Wrap/unwrap forward the Moralis config too: wrap_native sizes the amount
+        // off the SPENDABLE native balance (held − gas reserve), which needs to read
+        // the wallet balance first. Without a Moralis service the balance read bails
+        // early, so the gas reserve is never estimated and spendable falls back to
+        // the full balance (no gas withheld).
+        this.registry.register(new builtin_1.WrapNativeTool(walletActionMoralisConfig));
+        this.registry.register(new builtin_1.UnwrapNativeTool(walletActionMoralisConfig));
+        this.registry.register(new builtin_1.BuyTokenTool(walletActionMoralisConfig, { debug: this.debug }));
+        this.registry.register(new builtin_1.SwapTokenTool(walletActionMoralisConfig, { debug: this.debug }));
         // Wire router + subagents. Subagents share the same registry, so any custom
         // tools registered later via `registerTool()` become available as long as
         // their name matches one of the subagent's declared tool names.
         this.router = new Router_1.Router(this.llm, { debug: this.debug });
         this.rewriter = new QueryRewriter_1.QueryRewriter(this.llm, { debug: this.debug });
+        const subgraphConfigObj = typeof config.subgraph === 'object' ? config.subgraph : undefined;
         const subagentList = (0, subagents_1.createDefaultSubagents)(this.llm, this.registry, {
             maxToolCalls: config.maxIterations ?? 5,
             debug: this.debug,
-        });
+            linkAddLiquidity: subgraphConfigObj?.linkAddLiquidity,
+        }, config.subagents);
         this.subagents = new Map(subagentList.map((s) => [s.name, s]));
+        // Compile the LangGraph that drives one chat turn. Nodes reuse the helpers
+        // below via a host object, so the graph is pure orchestration.
+        this.chatGraph = (0, chatGraph_1.buildChatGraph)(this.createGraphHost());
         // Kick off the initial history load eagerly so consumers that read
         // history synchronously right after `new AgentCore(...)` (e.g. a React
         // component reading `getHistory()` during its first render) can await
@@ -429,138 +488,105 @@ class AgentCore {
      */
     async chat(userMessage, options) {
         const doSuggest = options?.generateSuggestions ?? this.suggestionsEnabled;
+        // FE-provided language hint — set when this turn originates from an
+        // action-button click (the button's synthetic prompt is often English even
+        // though the conversation is in another language). When present it wins
+        // over auto-detection so the resulting form/reply stays in the user's
+        // language. See SuggestedAction.language.
+        const overrideLang = typeof options?.language === 'string' && options.language.trim() ? options.language.trim() : '';
         // Ensure history is loaded from storage before processing the first message.
         // This is a no-op if already loaded, and deduplicates concurrent calls so
         // a racing useEffect loadHistory() and this call don't double-load.
         await this.loadHistory();
         // First-call auto-ingest for vector KB (if configured). Idempotent.
         await this.maybeAutoIngest(this.autoIngestEnabled);
-        this.addUserMessage(userMessage);
-        if (this.history.needsSummary()) {
-            await this.compactHistory();
-        }
-        // Drop the trailing user message itself so Router/Subagent prompts don't
-        // duplicate it (we pass the query separately as "User query: …"). Keeping
-        // it would cause Gemini to focus on the last (standalone) user message
-        // and lose the prior context needed to resolve follow-ups.
-        const rawHistory = this.history.getConversation();
-        const conversationMessages = rawHistory.length > 0 && rawHistory[rawHistory.length - 1].role === 'user' ? rawHistory.slice(0, -1) : rawHistory;
         const turnStart = Date.now();
         if (this.debug) {
             console.log(`\n${'─'.repeat(60)}`);
             console.log(`[AgentCore] query: "${userMessage}"`);
         }
-        // Look up which subagent handled the previous assistant turn. This is a
-        // strong hint for short follow-ups ("more", "tiếp", "yes") — they almost
-        // always continue the same domain.
-        const lastSubagents = (0, historyUtils_1.getLastAssistantSubagents)(conversationMessages);
-        if (this.debug && lastSubagents.length > 0) {
-            console.log(`[AgentCore] previous turn handled by: ${lastSubagents.join(', ')}`);
-        }
-        // Stage 1 — Contextualize. Resolve coreferences / ellipsis / follow-ups
-        // BEFORE the Router so every downstream component (KB, Router, Subagent)
-        // operates on a fully-specified standalone question.
-        // See Alhena "Contextualizer" (2025) + "LLMs Get Lost in Multi-Turn" (ICLR 2025).
-        const rewrite = await this.rewriter.rewrite(userMessage, conversationMessages, lastSubagents);
-        if (this.debug) {
-            console.log('🚀 ~ AgentCore ~ chat ~ rewrite:', rewrite);
-        }
-        const effectiveQuery = rewrite.rewrittenQuery;
-        // Stage 2 — KB search.
-        //   - For follow-ups ("yes" / "tiếp" / "thế còn..."), search with the
-        //     rewritten query so we have enough signal to match anything.
-        //   - For self-contained turns, search with the ORIGINAL message: it is
-        //     what the user actually typed and is therefore the closest possible
-        //     input to what the embedding model saw at upsert time. The rewriter
-        //     is an LLM and may paraphrase even when told not to — which silently
-        //     degrades retrieval (e.g. "CoinPool an toàn không?" gets reworded
-        //     into something that no longer scores high against the indexed
-        //     phrasing).
-        const kbQuery = rewrite.isFollowUp ? effectiveQuery : userMessage;
-        if (this.debug && kbQuery !== effectiveQuery) {
-            console.log(`[AgentCore] KB search using original message (not rewritten): "${kbQuery}"`);
-        }
-        const kbHits = await this.searchKB(kbQuery);
-        const kbContext = this.formatKBContext(kbHits);
-        // High-confidence KB match → answer via KB, then rollback the user message
-        // from the working window so this exchange never enters the LLM context.
-        // Both messages are written to fullMessages only (UI log).
-        const messageId = generateMessageId();
-        const kbAnswer = await this.tryAnswerFromKB(userMessage, kbHits, kbContext, messageId);
-        if (kbAnswer) {
-            return { ...kbAnswer, messageId, rewrite };
-        }
-        const cards = Array.from(this.subagents.values()).map((s) => s.getCard());
-        const decision = await this.router.route(effectiveQuery, conversationMessages, cards, this.userContext, lastSubagents);
-        // No subagent needed → answer directly via LLM
-        if (decision.assignments.length === 0) {
-            const direct = await this.answerDirectly(effectiveQuery, conversationMessages, kbContext, doSuggest, messageId);
-            if (this.debug)
-                console.log(`[AgentCore] turn done in ${Date.now() - turnStart}ms (direct LLM)\n`);
-            return { ...direct, messageId, routerDecision: decision, rewrite };
-        }
-        // Dispatch subagents in parallel
-        const subResults = await this.router.dispatch(decision, this.subagents, conversationMessages, this.userContext);
-        // Persist tool call/result messages BEFORE synthesising so the synthesiser
-        // (and all future turns) can see this turn's tool data via history.
-        this.persistToolMessages(subResults);
-        if (this.debug) {
-            const totalToolMsgs = subResults.reduce((n, r) => n + r.toolMessages.length, 0);
-            const totalToolCalls = subResults.reduce((n, r) => n + r.toolResults.length, 0);
-            const perSubagent = subResults
-                .map((r) => {
-                const tools = r.toolResults.map((t) => t.toolName);
-                const counts = tools.reduce((acc, name) => {
-                    acc[name] = (acc[name] ?? 0) + 1;
-                    return acc;
-                }, {});
-                const toolStr = Object.keys(counts).length === 0
-                    ? 'no tools'
-                    : Object.entries(counts)
-                        .map(([name, c]) => (c > 1 ? `${name}×${c}` : name))
-                        .join(', ');
-                return `${r.subagentName} (${r.toolResults.length} tool call${r.toolResults.length === 1 ? '' : 's'}: ${toolStr})`;
-            })
-                .join(' | ');
-            console.log(`\n[AgentCore] turn summary — subagents: ${subResults.length}, total tool calls: ${totalToolCalls}\n  ${perSubagent}`);
-            console.log(`[AgentCore] synthesising ${subResults.length} subagent result(s), stored ${totalToolMsgs} tool message(s) in history…`);
-        }
-        // Synthesiser runs WITHOUT tools — strip tool messages from the history
-        // slice to avoid sending orphan functionResponse parts to Gemini. Also
-        // drop the trailing user message (Synthesiser already receives userQuery
-        // as a separate argument; keeping it here would duplicate it).
-        const synthHistoryRaw = this.history.getConversation();
-        const synthHistoryTrimmed = synthHistoryRaw.length > 0 && synthHistoryRaw[synthHistoryRaw.length - 1].role === 'user'
-            ? synthHistoryRaw.slice(0, -1)
-            : synthHistoryRaw;
-        const synthesiserHistory = (0, historyUtils_1.stripToolMessages)(synthHistoryTrimmed);
-        const trace = this.mergeTrace(subResults);
-        // Pass the ORIGINAL user message to the synthesiser so the final answer
-        // addresses what the user actually typed (the rewritten query was only
-        // for routing/tool-selection purposes, not user-facing phrasing).
-        // Note: kbContext is intentionally NOT forwarded here. When the router
-        // chose to dispatch subagents it judged the query needs live tool data —
-        // injecting (potentially loose-match) KB material into the synthesiser
-        // would let an unrelated reference override correct tool results. To
-        // make more KB hits answer from KB, lower `kbAnswerThreshold` instead.
-        const synthesised = await this.synthesizer.synthesise(userMessage, trace, synthesiserHistory, rewrite.language);
-        // Tag the assistant message with the subagents that handled it — used by
-        // QueryRewriter and Router on the NEXT turn to resolve "more" / "tiếp" / etc.
-        const handledBy = subResults.map((r) => r.subagentName);
-        const uiActions = this.collectUiActions(subResults, rewrite.language || null);
-        const response = await this.finaliseAnswer({ userMessage, answer: synthesised, subagents: handledBy, uiActions, messageId }, { generateSuggestions: doSuggest });
+        // Run the turn through the compiled LangGraph. All orchestration logic
+        // (setup → rewrite → kb → route → direct | subagent fan-out → synthesize)
+        // lives in chatGraph.ts; the nodes reuse the helpers on this class via the
+        // host object, so behaviour is identical to the previous imperative flow.
+        const finalState = await this.chatGraph.invoke({ userMessage, doSuggest, overrideLang });
         if (this.debug) {
             console.log(`[AgentCore] turn done in ${Date.now() - turnStart}ms total`);
             console.log(`${'─'.repeat(60)}\n`);
         }
+        // A terminal node (kb / direct / synthesize) always sets `response`.
+        return finalState.response ?? { answer: '', messageId: generateMessageId() };
+    }
+    /**
+     * Build the host object the chat graph's nodes call into. Each method is a
+     * thin closure over an existing (private) helper, so the graph stays pure
+     * orchestration and AgentCore exposes no new public surface.
+     */
+    createGraphHost() {
         return {
-            ...response,
-            messageId,
-            trace,
-            routerDecision: decision,
-            subagentResults: subResults,
-            rewrite,
-            ...(uiActions.length > 0 ? { uiActions } : {}),
+            debug: this.debug,
+            // setup
+            addUserMessage: (message) => this.addUserMessage(message),
+            needsSummary: () => this.history.needsSummary(),
+            compactHistory: () => this.compactHistory(),
+            conversationForTurn: () => {
+                // Drop the trailing user message so Router/Subagent prompts don't
+                // duplicate it (the query is passed separately as "User query: …").
+                const raw = this.history.getConversation();
+                return raw.length > 0 && raw[raw.length - 1].role === 'user' ? raw.slice(0, -1) : raw;
+            },
+            lastAssistantSubagents: (conversation) => (0, historyUtils_1.getLastAssistantSubagents)(conversation),
+            generateMessageId: () => generateMessageId(),
+            // rewrite
+            rewrite: (userMessage, conversation, lastSubagents) => this.rewriter.rewrite(userMessage, conversation, lastSubagents),
+            // knowledge base
+            searchKB: (query) => this.searchKB(query),
+            formatKBContext: (hits) => this.formatKBContext(hits),
+            tryAnswerFromKB: (userMessage, hits, kbContext, messageId) => this.tryAnswerFromKB(userMessage, hits, kbContext, messageId),
+            // router
+            subagentCards: () => Array.from(this.subagents.values()).map((s) => s.getCard()),
+            route: (query, conversation, cards, lastSubagents) => this.router.route(query, conversation, cards, this.userContext, lastSubagents),
+            // unsupported chain
+            connectedChain: () => this.userContext.chain,
+            answerUnsupportedChain: (rawChain, language, messageId) => this.answerUnsupportedChain(rawChain, language, messageId),
+            // direct answer
+            answerDirectly: (query, conversation, kbContext, generateSuggestions, messageId, useWebSearch) => this.answerDirectly(query, conversation, kbContext, generateSuggestions, messageId, useWebSearch),
+            // subagent — mirrors Router.dispatch's per-assignment handling, but for a
+            // single assignment (the graph fans out one Send per assignment).
+            runSubagent: async (assignment, conversation, turnLanguage) => {
+                const agent = this.subagents.get(assignment.subagent);
+                if (!agent) {
+                    if (this.debug)
+                        console.log(`[AgentCore] WARN: subagent "${assignment.subagent}" not registered`);
+                    return {
+                        subagentName: assignment.subagent,
+                        steps: [],
+                        finalAnswer: `Subagent "${assignment.subagent}" is not registered.`,
+                        toolResults: [],
+                        toolMessages: [],
+                    };
+                }
+                const t1 = Date.now();
+                const result = await agent.run({ query: assignment.query, reasoning: assignment.reasoning, language: turnLanguage }, conversation, this.userContext);
+                if (this.debug) {
+                    const toolNames = result.toolResults.map((r) => r.toolName).join(', ') || '—';
+                    console.log(`[AgentCore] ${assignment.subagent} done in ${Date.now() - t1}ms | tools: ${toolNames}`);
+                }
+                return result;
+            },
+            // synthesise
+            persistToolMessages: (results) => this.persistToolMessages(results),
+            synthesiserHistory: () => {
+                const raw = this.history.getConversation();
+                const trimmed = raw.length > 0 && raw[raw.length - 1].role === 'user' ? raw.slice(0, -1) : raw;
+                return (0, historyUtils_1.stripToolMessages)(trimmed);
+            },
+            mergeTrace: (results) => this.mergeTrace(results),
+            synthesise: (userMessage, trace, history, language) => this.synthesizer.synthesise(userMessage, trace, history, language),
+            collectUiActions: (results, language) => this.collectUiActions(results, language),
+            collectActionButtons: (results, language) => this.collectActionButtons(results, language),
+            subResultsTriggerNoSuggestions: (results) => this.subResultsTriggerNoSuggestions(results),
+            finaliseAnswer: (params, options) => this.finaliseAnswer(params, options),
         };
     }
     /**
@@ -568,6 +594,59 @@ class AgentCore {
      * 'action' attach a `ui` field to their ToolResult; the FE renders one
      * component per entry in the order they were produced.
      */
+    /**
+     * Return true when ANY tool successfully executed across the dispatched
+     * subagents carries `noSuggestions: true` in its registry definition. Used to
+     * skip the suggester for turns where the user is already pointed at a
+     * concrete next action (a form / preview).
+     */
+    subResultsTriggerNoSuggestions(subResults) {
+        for (const r of subResults) {
+            for (const tr of r.toolResults) {
+                if (!tr.success)
+                    continue;
+                const def = this.registry.get(tr.toolName);
+                if (def?.noSuggestions === true)
+                    return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Aggregate `actionButtons` emitted by tools across all subagent tool calls
+     * this turn (e.g. a token-picker after the user said "send token" without
+     * naming one). Preserves emission order; drops malformed entries.
+     */
+    collectActionButtons(subResults, language) {
+        const out = [];
+        // Dedup by label+prompt: the same tool result can be observed across more
+        // than one subagent (or a tool emits an identical set twice), which would
+        // otherwise render duplicate quick-pick chips (e.g. 25/50/75/100% twice).
+        const seen = new Set();
+        for (const r of subResults) {
+            for (const tr of r.toolResults) {
+                if (!tr.success || !Array.isArray(tr.actionButtons))
+                    continue;
+                for (const btn of tr.actionButtons) {
+                    if (btn &&
+                        typeof btn === 'object' &&
+                        typeof btn.label === 'string' &&
+                        btn.label.trim() &&
+                        typeof btn.prompt === 'string' &&
+                        btn.prompt.trim()) {
+                        const key = `${btn.label}${btn.prompt}`;
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        // Stamp the turn language so the FE can echo it back on click,
+                        // keeping the follow-up turn in the user's language.
+                        out.push({ label: btn.label, prompt: btn.prompt, ...(language ? { language } : {}) });
+                    }
+                }
+            }
+        }
+        return out;
+    }
     collectUiActions(subResults, language) {
         const out = [];
         for (const r of subResults) {
@@ -650,14 +729,26 @@ class AgentCore {
         const intentCheckMessages = [
             {
                 role: 'system',
-                content: 'You are a strict intent classifier. Respond with ONLY "yes" or "no" — no other text.' +
-                    '\n\nAnswer "yes" if the user message is genuinely asking about the same topic as the FAQ question.' +
-                    '\nAnswer "no" if the user message is asking for real-time data, live lookups, prices, balances, transactions, or anything that requires fetching external data — even if the FAQ question looks similar.',
+                content: 'You are a STRICT intent classifier. Respond with ONLY "yes" or "no" — no other text.' +
+                    '\n\nDefault to "no". Only answer "yes" when you are confident.' +
+                    '\n\nAnswer "yes" ONLY IF the user message and the FAQ question are genuinely EQUIVALENT — i.e. ' +
+                    'they ask the SAME thing and a single answer to the FAQ question would fully and directly answer the ' +
+                    'user message. Merely sharing a topic, a keyword, or a domain is NOT enough.' +
+                    '\n\nAnswer "no" if ANY of these hold:' +
+                    '\n- The user is asking about a DIFFERENT aspect, sub-question, or angle of the same general topic ' +
+                    '(e.g. FAQ = "what is staking?" vs user = "how do I unstake?").' +
+                    '\n- The user message is broader, narrower, or only partially overlaps with the FAQ question.' +
+                    '\n- They merely share vocabulary or a domain but ask for different things.' +
+                    '\n- The user is asking for real-time data, live lookups, prices, balances, transactions, or anything ' +
+                    'that requires fetching external data — even if the FAQ question looks similar.' +
+                    '\n- You are uncertain.',
                 timestamp: 0,
             },
             {
                 role: 'user',
-                content: `FAQ question: "${topQuestion}"\nUser message: "${userMessage}"\n\nIs the user message genuinely asking about the same topic as the FAQ question?`,
+                content: `FAQ question: "${topQuestion}"\nUser message: "${userMessage}"\n\n` +
+                    'Are these two questions EQUIVALENT — asking the same thing such that one answer fully answers both? ' +
+                    'Answer "yes" only if equivalent, otherwise "no".',
                 timestamp: Date.now(),
             },
         ];
@@ -705,16 +796,28 @@ class AgentCore {
         await this.persistHistory();
         return { answer, suggestedPrompts: [] };
     }
-    async answerDirectly(userMessage, conversationMessages, kbContext, generateSuggestions = true, messageId) {
-        if (this.debug)
-            console.log('[AgentCore] Router returned no assignments, answering directly via LLM…');
-        const systemContent = kbContext
+    async answerDirectly(userMessage, conversationMessages, kbContext, generateSuggestions = true, messageId, useWebSearch = false) {
+        if (this.debug) {
+            console.log(`[AgentCore] Router returned no assignments, answering directly via LLM… (webSearch=${useWebSearch})`);
+        }
+        // When the query does NOT need live web data (greetings, chit-chat,
+        // references to the conversation, evergreen knowledge), we answer from the
+        // model's own knowledge. Without search grounding the model is more prone
+        // to fabricate, so we add an explicit guard: it must admit uncertainty
+        // instead of inventing real-time facts (prices, news, current events).
+        const noSearchGuard = useWebSearch
+            ? ''
+            : '\n\nYou are answering WITHOUT live web access. Rely only on knowledge you are ' +
+                'confident about. If the question needs real-time or recent information you do not ' +
+                "have (current prices, today's news, latest events), say plainly that you do not have " +
+                'up-to-date data instead of guessing. Never fabricate numbers, dates, or facts.';
+        const systemContent = (kbContext
             ? this.systemPrompt +
                 '\n\nYou may use the following reference material if relevant:\n\n' +
                 '---\nREFERENCE MATERIAL:\n' +
                 kbContext +
                 '\n---'
-            : this.systemPrompt;
+            : this.systemPrompt) + noSearchGuard;
         // Direct LLM call has NO tools declared → strip tool messages to avoid
         // orphan functionResponse parts (Gemini 400). Also append the current
         // user message (caller dropped it from the history slice).
@@ -724,9 +827,47 @@ class AgentCore {
             ...cleanHistory,
             { role: 'user', content: userMessage, timestamp: Date.now() },
         ];
-        const directResponse = await this.llm.chat(directMessages, undefined, { googleSearch: true });
+        const directResponse = await this.llm.chat(directMessages, undefined, { googleSearch: useWebSearch });
         return await this.finaliseAnswer({ userMessage, answer: directResponse.text, messageId }, { generateSuggestions });
     }
+    /**
+     * Deterministic short-circuit for the unsupported-connected-chain case: the
+     * wallet is on a chain this core does not support and the user did not name a
+     * supported one, so chain-scoped tools cannot serve the request. We produce a
+     * short, localized "chain X is not supported" reply (no tools, no suggestions)
+     * and persist it like any other assistant turn.
+     */
+    async answerUnsupportedChain(rawChain, language, messageId) {
+        if (this.debug) {
+            console.log(`[AgentCore] connected chain "${rawChain}" is not supported → short-circuit with notice`);
+        }
+        const lang = (language || '').trim();
+        // Deliberately do NOT name the unsupported network or echo its chain id:
+        // identifying an arbitrary chain id is unreliable (a wrong name is worse than
+        // none). We only state that the current network is unsupported + list the
+        // supported ones. The LLM call is purely for localization.
+        const messages = [
+            {
+                role: 'system',
+                content: 'Write ONE short, polite message telling the user that the blockchain network they want to use is ' +
+                    'NOT supported by this assistant, and inviting them to use one of the supported networks. ' +
+                    `List the supported networks: ${chainResolver_1.SUPPORTED_CHAINS_LABEL}. ` +
+                    'Do NOT mention or guess the name or chain id of the unsupported network. ' +
+                    (lang ? `Reply in BCP-47 language "${lang}".` : 'Reply in the same language the user has been using.') +
+                    ' Do NOT mention tools or internal implementation details.',
+                timestamp: 0,
+            },
+            {
+                role: 'user',
+                content: 'Is my currently connected network supported?',
+                timestamp: Date.now(),
+            },
+        ];
+        const response = await this.llm.chat(messages);
+        const answer = response.text?.trim() ||
+            `Your currently connected network is not supported yet. Supported networks: ${chainResolver_1.SUPPORTED_CHAINS_LABEL}.`;
+        return await this.finaliseAnswer({ userMessage: `[unsupported chain: ${rawChain}]`, answer, messageId }, { generateSuggestions: false });
+    }
     /**
      * Flatten the per-subagent ReAct steps into a single trace that the
      * Synthesizer can consume. The `finalAnswer` here is a compact
@@ -751,7 +892,7 @@ class AgentCore {
         return { steps, finalAnswer };
     }
     async finaliseAnswer(params, options) {
-        const { userMessage, answer, subagents, uiActions, messageId } = params ?? {};
+        const { userMessage, answer, subagents, uiActions, actionButtons, messageId } = params ?? {};
         const { generateSuggestions = true } = options ?? {};
         const suggestedPrompts = generateSuggestions
             ? await this.generateSuggestions(userMessage, answer, subagents ?? [])
@@ -763,11 +904,13 @@ class AgentCore {
             msg.suggestedPrompts = suggestedPrompts;
         if (uiActions && uiActions.length > 0)
             msg.uiActions = uiActions;
+        if (actionButtons && actionButtons.length > 0)
+            msg.actionButtons = actionButtons;
         if (messageId)
             msg.messageId = messageId;
         this.history.add(msg);
         await this.persistHistory();
-        return { answer, suggestedPrompts };
+        return { answer, suggestedPrompts, ...(actionButtons && actionButtons.length > 0 ? { actionButtons } : {}) };
     }
     // ---- Suggested prompts ----
     async generateSuggestions(userMessage, answer, subagents) {