keyring-agent-core 0.1.0

package/dist/agent/AgentCore.js

@@ -0,0 +1,950 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentCore = void 0;
+const GeminiProvider_1 = require("../llm/GeminiProvider");
+const ToolRegistry_1 = require("../tools/ToolRegistry");
+const builtin_1 = require("../tools/builtin");
+const ChatHistory_1 = require("../memory/ChatHistory");
+const Summarizer_1 = require("../memory/Summarizer");
+const KnowledgeBase_1 = require("../memory/KnowledgeBase");
+const UpstashKnowledgeBase_1 = require("../memory/UpstashKnowledgeBase");
+const historyUtils_1 = require("../memory/historyUtils");
+const Router_1 = require("./Router");
+const subagents_1 = require("./subagents");
+const Synthesizer_1 = require("./Synthesizer");
+const QueryRewriter_1 = require("./QueryRewriter");
+/** Generate a short stable id for one response turn (8 hex chars). */
+function generateMessageId() {
+    const ts = Date.now().toString(16);
+    const rand = Math.floor(Math.random() * 0xffff)
+        .toString(16)
+        .padStart(4, '0');
+    return (ts + rand).slice(-8);
+}
+const DEFAULT_SYSTEM_PROMPT = 'You are a helpful AI assistant. Answer the user accurately and concisely. ' +
+    'Respond in the same language as the user.';
+/**
+ * Top-level orchestrator. Two-layer architecture:
+ *
+ *   User query
+ *     → Router            (picks 0..N domain subagents)
+ *     → Subagent(s)       (each runs its own ReAct loop over a narrow tool set, in parallel)
+ *     → Synthesizer       (merges subagent answers into the final reply)
+ *
+ * Compared to a flat planner that sees every tool, this keeps per-call prompt
+ * size bounded regardless of how many tools are registered.
+ */
+class AgentCore {
+    llm;
+    registry;
+    history;
+    summarizer;
+    router;
+    rewriter;
+    subagents;
+    synthesizer;
+    systemPrompt;
+    debug;
+    userContext = {};
+    storage;
+    storageKey;
+    persistHistoryEnabled;
+    /** Active KB used at search time. May be the legacy LLM matcher or a vector backend. */
+    kb;
+    /** Always-present in-memory KB that holds the original entries (used for autoIngest + as fallback). */
+    kbEntries;
+    vectorKB = null;
+    vectorKBAutoIngested = false;
+    vectorKBAutoIngestPromise = null;
+    autoIngestEnabled = false;
+    kbAnswerThreshold;
+    suggestionsEnabled;
+    historyLoaded = false;
+    historyLoadingPromise = null;
+    /**
+     * Resolves once the initial persisted-history load attempt has finished
+     * (success or failure). Only meaningful when `persistHistory: true` and a
+     * `storage` provider is configured — in that case consumers rendering a
+     * chat list on mount should `await agent.historyReady` before calling
+     * {@link getHistory} / {@link getDisplayHistory}, otherwise the first read
+     * happens before storage has been hydrated and returns an empty array.
+     * With persistence disabled this still resolves (immediately), so it is
+     * always safe to await.
+     */
+    historyReady;
+    constructor(config) {
+        this.llm = new GeminiProvider_1.GeminiProvider(config.llm);
+        this.registry = new ToolRegistry_1.ToolRegistry();
+        this.history = new ChatHistory_1.ChatHistory(config.maxHistoryMessages ?? 50);
+        this.summarizer = new Summarizer_1.Summarizer(this.llm);
+        this.synthesizer = new Synthesizer_1.Synthesizer(this.llm);
+        this.systemPrompt = config.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+        this.debug = config.debug ?? false;
+        this.suggestionsEnabled = config.generateSuggestions ?? true;
+        this.storage = config.storage ?? null;
+        this.storageKey = config.storageKey ?? 'keyring-agent-history';
+        this.persistHistoryEnabled = config.persistHistory ?? false;
+        // Always build the in-memory KB so callers can add/replace entries at
+        // runtime even when vector mode is enabled (we re-ingest from it).
+        this.kbEntries = new KnowledgeBase_1.KnowledgeBase(config.knowledgeBase);
+        this.kbEntries.setLLM(this.llm);
+        // Resolve which backend handles search: vector (Upstash / custom) or legacy.
+        const vec = config.vectorKB;
+        if (vec?.enabled) {
+            if (vec.provider) {
+                this.kb = vec.provider;
+            }
+            else {
+                this.vectorKB = new UpstashKnowledgeBase_1.UpstashKnowledgeBase({
+                    url: vec.url,
+                    token: vec.token,
+                    namespace: vec.namespace,
+                    minScore: vec.minScore,
+                    defaultTopK: vec.defaultTopK,
+                    debug: this.debug,
+                });
+                this.kb = this.vectorKB;
+                this.autoIngestEnabled = vec.autoIngest === true;
+            }
+            if (this.debug) {
+                console.log(`[AgentCore] vector KB enabled (${vec.provider ? 'custom provider' : 'Upstash'}` +
+                    (vec.namespace ? `, ns=${vec.namespace}` : '') +
+                    ')');
+            }
+        }
+        else {
+            this.kb = this.kbEntries;
+        }
+        // kbAnswerThreshold default differs by backend:
+        //  - LLM matcher: scores are 0.6–1.0, the "high-confidence" cut-off is 0.8.
+        //  - Upstash vector backend (DBSF fusion, hybrid index): scores are
+        //    distribution-fused and unbounded — strong matches sit above ~1.3,
+        //    decent ones around 0.6–1.0, noise near 0. We deliberately keep a
+        //    HIGH cut-off here (1.3) to avoid answer-from-KB false positives when
+        //    sparse keyword overlap pushes a non-matching entry above 1.0 even
+        //    though the dense semantic match is weak. Lower-scoring hits still
+        //    flow to the router/synthesiser as reference context — they are just
+        //    not allowed to bypass the router on their own.
+        const explicitThreshold = config.kbAnswerThreshold;
+        if (typeof explicitThreshold === 'number') {
+            this.kbAnswerThreshold = explicitThreshold;
+        }
+        else if (vec?.enabled && !vec.provider) {
+            this.kbAnswerThreshold = vec.minScore ?? 1.3;
+        }
+        else {
+            this.kbAnswerThreshold = 0.8;
+        }
+        if (this.debug) {
+            console.log(`[AgentCore] kbAnswerThreshold = ${this.kbAnswerThreshold}`);
+        }
+        // Register built-in Moralis tools
+        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 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));
+            this.registry.register(new builtin_1.TokenHoldersTool(moralisConfig));
+            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.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) {
+            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));
+            this.registry.register(new builtin_1.PoolSearchTool(uniswapConfig));
+            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;
+            this.registry.register(new builtin_1.OpenAddLiquidityFormTool({
+                baseUrl: uniswapConfig?.baseUrl,
+                pool: poolServiceConfig,
+                minProvideUsd: uniswapConfig?.minProvideUsd,
+            }));
+            this.registry.register(new builtin_1.PreviewAddLiquidityTool({ pool: poolServiceConfig }));
+        }
+        // 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 subagentList = (0, subagents_1.createDefaultSubagents)(this.llm, this.registry, {
+            maxToolCalls: config.maxIterations ?? 5,
+            debug: this.debug,
+        });
+        this.subagents = new Map(subagentList.map((s) => [s.name, s]));
+        // 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
+        // `agent.historyReady` to ensure persisted storage has been hydrated.
+        this.historyReady = this.loadHistory();
+    }
+    // ---- Tool management ----
+    /** Register a tool so the agent can use it. */
+    registerTool(tool) {
+        this.registry.register(tool);
+    }
+    /** Register multiple tools at once. */
+    registerTools(tools) {
+        for (const tool of tools) {
+            this.registry.register(tool);
+        }
+    }
+    /** Unregister a tool by name. */
+    unregisterTool(name) {
+        return this.registry.unregister(name);
+    }
+    /** List registered tool names. */
+    listTools() {
+        return this.registry.listNames();
+    }
+    /**
+     * Directly invoke a tool with structured args, bypassing the LLM/router.
+     *
+     * Use this from the FE for **deterministic actions** where the user has
+     * already supplied structured input via a UI form (e.g. confirming an
+     * AddLiquidityForm with a chosen strategy + amount). It is faster, cheaper,
+     * and removes the risk of the LLM mis-parsing numeric values from form data.
+     *
+     * The result is returned with the same `AgentResponse` shape as `chat()` —
+     * including `uiActions` collected from the tool's UI payload — so the FE
+     * renders it uniformly. The interaction is also recorded in chat history so
+     * subsequent conversational turns retain context.
+     *
+     * Use `chat()` (the LLM-driven path) for free-form natural-language input.
+     */
+    async invokeTool(name, args, options) {
+        await this.loadHistory();
+        const tool = this.registry.get(name);
+        if (!tool) {
+            const answer = `Unknown tool: "${name}".`;
+            return { answer, messageId: generateMessageId() };
+        }
+        if (this.debug) {
+            console.log(`[AgentCore] invokeTool ${name} ${JSON.stringify(args)}`);
+        }
+        // Record the user's intent in history so the next conversational turn
+        // can reference what the user just confirmed.
+        const userMsg = options?.userMessage ?? `[invoke ${name}]`;
+        this.history.add({ role: 'user', content: userMsg, timestamp: Date.now() });
+        const result = await this.registry.execute(name, args, this.userContext);
+        // Build a synthetic assistant message so chat history stays well-formed
+        // (one assistant reply per user turn). For UI/action tools this is
+        // typically just the tool's own `summary` field.
+        const data = result.data;
+        const answer = result.success ? (data?.summary ?? `Done.`) : `Action failed: ${result.error ?? 'unknown error'}`;
+        const messageId = generateMessageId();
+        // invokeTool() is FE-driven (form confirmation, not free-form chat) — no
+        // chat-message language detection runs here. Stamp 'en' as a safe default
+        // so FE never sees `undefined`; FE may override with its own app locale.
+        const uiActions = result.success && result.ui ? [this.stampLanguage(result.ui, null)] : [];
+        const assistantMsg = {
+            role: 'assistant',
+            content: answer,
+            timestamp: Date.now(),
+            subagents: ['direct-invoke'],
+            messageId,
+        };
+        if (uiActions.length > 0)
+            assistantMsg.uiActions = uiActions;
+        this.history.add(assistantMsg);
+        await this.persistHistory();
+        return {
+            answer,
+            messageId,
+            ...(uiActions.length > 0 ? { uiActions } : {}),
+        };
+    }
+    // ---- Subagent management ----
+    /**
+     * Register a custom subagent. Replaces any existing subagent with the same name.
+     * Advanced: most consumers should rely on the default wallet/token/nft/ai agents.
+     */
+    registerSubagent(agent) {
+        this.subagents.set(agent.name, agent);
+    }
+    /** Unregister a subagent by name. */
+    unregisterSubagent(name) {
+        return this.subagents.delete(name);
+    }
+    /** List registered subagent names. */
+    listSubagents() {
+        return Array.from(this.subagents.keys());
+    }
+    // ---- Knowledge Base ----
+    /**
+     * Replace all in-memory KB entries. When vector mode is enabled, the new
+     * entries become the source of truth for the next `ingestKnowledgeBase()`
+     * call but are NOT auto-pushed to the remote index — call that explicitly.
+     */
+    setKnowledgeBase(entries) {
+        this.kbEntries.setEntries(entries);
+        this.vectorKBAutoIngested = false;
+    }
+    addKnowledgeBase(entries) {
+        this.kbEntries.addEntries(entries);
+        this.vectorKBAutoIngested = false;
+    }
+    /**
+     * Push the current in-memory KB entries to the configured vector backend.
+     * Idempotent. No-op when vector mode is disabled or there are no entries.
+     */
+    async ingestKnowledgeBase() {
+        if (!this.vectorKB)
+            return { count: 0 };
+        const entries = this.kbEntries.getEntries();
+        if (entries.length === 0)
+            return { count: 0 };
+        const res = await this.vectorKB.upsert(entries);
+        this.vectorKBAutoIngested = true;
+        return res;
+    }
+    async maybeAutoIngest(autoIngest) {
+        if (!autoIngest || !this.vectorKB || this.vectorKBAutoIngested)
+            return;
+        if (this.vectorKBAutoIngestPromise)
+            return this.vectorKBAutoIngestPromise;
+        this.vectorKBAutoIngestPromise = (async () => {
+            try {
+                const { count } = await this.ingestKnowledgeBase();
+                if (this.debug && count > 0) {
+                    console.log(`[AgentCore] auto-ingested ${count} KB entr${count === 1 ? 'y' : 'ies'} to vector store`);
+                }
+            }
+            catch (err) {
+                if (this.debug)
+                    console.warn('[AgentCore] auto-ingest failed:', err);
+            }
+            finally {
+                this.vectorKBAutoIngestPromise = null;
+            }
+        })();
+        await this.vectorKBAutoIngestPromise;
+    }
+    // ---- User context (wallet / chain from UI) ----
+    setUserContext(ctx) {
+        this.userContext = { ...ctx };
+    }
+    getUserContext() {
+        return { ...this.userContext };
+    }
+    // ---- Chat ----
+    async loadHistory() {
+        // If already loaded or loading, return the same promise so concurrent
+        // callers (e.g. chat() racing with the consumer's useEffect) don't
+        // trigger duplicate loads.
+        if (this.historyLoaded)
+            return;
+        if (this.historyLoadingPromise)
+            return this.historyLoadingPromise;
+        this.historyLoadingPromise = this._doLoadHistory();
+        await this.historyLoadingPromise;
+    }
+    async _doLoadHistory() {
+        if (!this.storage) {
+            if (this.debug)
+                console.log(`[AgentCore] loadHistory: no storage configured`);
+            this.historyLoaded = true;
+            return;
+        }
+        if (!this.persistHistoryEnabled) {
+            if (this.debug)
+                console.log(`[AgentCore] loadHistory: persistHistory disabled — starting fresh session`);
+            // Best-effort wipe any leftover data from a previous run that had
+            // persistence enabled, so a consumer reading storage directly cannot
+            // accidentally rehydrate the old session.
+            try {
+                await this.storage.removeItem(this.storageKey);
+            }
+            catch (err) {
+                if (this.debug)
+                    console.warn('[AgentCore] failed to clear stale history:', err);
+            }
+            this.historyLoaded = true;
+            return;
+        }
+        try {
+            const raw = await this.storage.getItem(this.storageKey);
+            if (this.debug) {
+                console.log(`[AgentCore] loadHistory: storage key "${this.storageKey}" ${raw ? `has ${raw.length} chars` : 'is empty'}`);
+            }
+            if (raw) {
+                const data = JSON.parse(raw);
+                this.history.restore(data);
+                if (this.debug) {
+                    console.log(`[AgentCore] Restored ${this.history.length} messages from storage`);
+                }
+            }
+        }
+        catch (err) {
+            if (this.debug) {
+                console.warn('[AgentCore] Failed to load history from storage:', err);
+            }
+        }
+        finally {
+            this.historyLoaded = true;
+        }
+    }
+    async persistHistory() {
+        if (!this.storage)
+            return;
+        if (!this.persistHistoryEnabled)
+            return;
+        try {
+            const serialised = JSON.stringify(this.history.serialise());
+            await this.storage.setItem(this.storageKey, serialised);
+        }
+        catch (err) {
+            if (this.debug) {
+                console.warn('[AgentCore] Failed to persist history to storage:', err);
+            }
+        }
+    }
+    /**
+     * Process a user message and return an answer. Main entry point.
+     */
+    async chat(userMessage, options) {
+        const doSuggest = options?.generateSuggestions ?? this.suggestionsEnabled;
+        // 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 });
+        if (this.debug) {
+            console.log(`[AgentCore] turn done in ${Date.now() - turnStart}ms total`);
+            console.log(`${'─'.repeat(60)}\n`);
+        }
+        return {
+            ...response,
+            messageId,
+            trace,
+            routerDecision: decision,
+            subagentResults: subResults,
+            rewrite,
+            ...(uiActions.length > 0 ? { uiActions } : {}),
+        };
+    }
+    /**
+     * Aggregate UI payloads from this turn's tool calls. Tools with kind='ui' or
+     * 'action' attach a `ui` field to their ToolResult; the FE renders one
+     * component per entry in the order they were produced.
+     */
+    collectUiActions(subResults, language) {
+        const out = [];
+        for (const r of subResults) {
+            for (const tr of r.toolResults) {
+                if (tr.success && tr.ui && typeof tr.ui === 'object' && typeof tr.ui.component === 'string') {
+                    out.push(this.stampLanguage(tr.ui, language));
+                }
+            }
+        }
+        if (this.debug && out.length > 0) {
+            const stamped = out.map((u) => `${u.component}=${u.language}`).join(', ');
+            console.log(`[AgentCore] uiActions stamped (rewrite.language="${language ?? ''}"): ${stamped}`);
+        }
+        return out;
+    }
+    /**
+     * Stamp the rewriter-detected user-message language onto a UIPayload so FE
+     * renders the component in whichever language the user just typed in. Tools
+     * never set this themselves — it is a transport-level concern owned by
+     * AgentCore. No-op when the rewriter did not produce a language (FE may
+     * fall back to its own locale in that rare case).
+     */
+    stampLanguage(ui, language) {
+        if (!language || ui.language)
+            return ui;
+        return { ...ui, language };
+    }
+    // ---- Chat sub-steps ----
+    addUserMessage(userMessage) {
+        this.history.add({ role: 'user', content: userMessage, timestamp: Date.now() });
+    }
+    /** Single KB lookup — callers reuse the result for both context + short-circuit. */
+    async searchKB(query) {
+        const kbResults = await this.kb.search(query);
+        if (this.debug) {
+            if (kbResults.length === 0) {
+                console.log(`[AgentCore] KB no hits for "${query}"`);
+            }
+            else {
+                const summary = kbResults
+                    .slice(0, 3)
+                    .map((r) => `${r.score.toFixed(3)} ${this.snippet(r.entry.question, 60)}`)
+                    .join('  |  ');
+                console.log(`[AgentCore] KB hits (${kbResults.length}): ${summary}`);
+            }
+        }
+        return kbResults;
+    }
+    snippet(text, max) {
+        return text.length <= max ? text : text.slice(0, max - 1) + '…';
+    }
+    /** Format KB hits as a reference-block string for LLM consumption. */
+    formatKBContext(hits) {
+        if (hits.length === 0)
+            return '';
+        return hits.map((r, i) => `[Reference ${i + 1}]\nQ: ${r.entry.question}\nA: ${r.entry.answer}`).join('\n\n');
+    }
+    async tryAnswerFromKB(userMessage, kbResults, kbContext, messageId) {
+        if (!kbContext || kbResults.length === 0) {
+            if (this.debug)
+                console.log('[AgentCore] KB skip: no hits → router pipeline');
+            return null;
+        }
+        const top = kbResults[0].score;
+        if (top < this.kbAnswerThreshold) {
+            if (this.debug) {
+                console.log(`[AgentCore] KB skip: top score ${top.toFixed(3)} < threshold ${this.kbAnswerThreshold} → router pipeline`);
+            }
+            return null;
+        }
+        if (this.debug) {
+            console.log(`[AgentCore] KB answer: top score ${top.toFixed(3)} ≥ threshold ${this.kbAnswerThreshold} → verifying intent before KB answer`);
+        }
+        // Intent guard: verify the user message is actually asking about the FAQ
+        // topic before bypassing the router. High embedding similarity alone is not
+        // sufficient — a question like "what is the price of ETH?" can score high
+        // against a KB entry about wallets simply due to shared vocabulary, but it
+        // should be handled by a subagent, not the KB.
+        const topQuestion = kbResults[0].entry.question;
+        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.',
+                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?`,
+                timestamp: Date.now(),
+            },
+        ];
+        const intentResponse = await this.llm.chat(intentCheckMessages);
+        const intentVerdict = intentResponse.text.trim().toLowerCase();
+        if (!intentVerdict.startsWith('yes')) {
+            if (this.debug) {
+                console.log(`[AgentCore] KB intent guard: verdict="${intentVerdict}" → skipping KB, routing to subagent pipeline`);
+            }
+            return null;
+        }
+        if (this.debug) {
+            console.log(`[AgentCore] KB intent guard: verdict="yes" → answering from KB`);
+        }
+        // Strip tool messages (no tools declared here) and send only the system
+        // prompt + KB material + the current user message. Omitting old history
+        // prevents older turns in a different language from overriding language
+        // detection — the LLM must reply in the language of THIS message only.
+        const kbMessages = [
+            {
+                role: 'system',
+                content: this.systemPrompt +
+                    "\n\nYou have reference material below. Use it ONLY if it directly addresses the user's question. " +
+                    'Rephrase and adapt the content naturally — do NOT copy it verbatim. ' +
+                    'Do NOT supplement with general knowledge or speculate beyond what the reference provides. ' +
+                    'If the reference does not fully answer the question, say so honestly.' +
+                    '\n\n---\nREFERENCE MATERIAL:\n' +
+                    kbContext +
+                    '\n---',
+                timestamp: 0,
+            },
+            {
+                role: 'user',
+                content: `${userMessage}\n\n(You MUST reply in the same language as the question above, regardless of the reference material language.)`,
+                timestamp: Date.now(),
+            },
+        ];
+        const kbResponse = await this.llm.chat(kbMessages);
+        const answer = kbResponse.text;
+        // KB turns are persisted to the working window so future turns can reference them.
+        const kbMsg = { role: 'assistant', content: answer, timestamp: Date.now() };
+        if (messageId)
+            kbMsg.messageId = messageId;
+        this.history.add(kbMsg);
+        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
+            ? this.systemPrompt +
+                '\n\nYou may use the following reference material if relevant:\n\n' +
+                '---\nREFERENCE MATERIAL:\n' +
+                kbContext +
+                '\n---'
+            : this.systemPrompt;
+        // 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).
+        const cleanHistory = (0, historyUtils_1.stripToolMessages)(conversationMessages);
+        const directMessages = [
+            { role: 'system', content: systemContent, timestamp: 0 },
+            ...cleanHistory,
+            { role: 'user', content: userMessage, timestamp: Date.now() },
+        ];
+        const directResponse = await this.llm.chat(directMessages, undefined, { googleSearch: true });
+        return await this.finaliseAnswer({ userMessage, answer: directResponse.text, messageId }, { generateSuggestions });
+    }
+    /**
+     * Flatten the per-subagent ReAct steps into a single trace that the
+     * Synthesizer can consume. The `finalAnswer` here is a compact
+     * concatenation of each subagent's own answer, labelled by name.
+     */
+    mergeTrace(results) {
+        const steps = [];
+        for (const r of results) {
+            steps.push({
+                phase: 'think',
+                content: `[${r.subagentName}] begin`,
+                timestamp: Date.now(),
+            });
+            steps.push(...r.steps);
+            steps.push({
+                phase: 'observe',
+                content: `[${r.subagentName}] answer: ${r.finalAnswer}`,
+                timestamp: Date.now(),
+            });
+        }
+        const finalAnswer = results.map((r) => `[${r.subagentName}] ${r.finalAnswer}`).join('\n\n');
+        return { steps, finalAnswer };
+    }
+    async finaliseAnswer(params, options) {
+        const { userMessage, answer, subagents, uiActions, messageId } = params ?? {};
+        const { generateSuggestions = true } = options ?? {};
+        const suggestedPrompts = generateSuggestions
+            ? await this.generateSuggestions(userMessage, answer, subagents ?? [])
+            : [];
+        const msg = { role: 'assistant', content: answer, timestamp: Date.now() };
+        if (subagents && subagents.length > 0)
+            msg.subagents = subagents;
+        if (suggestedPrompts.length > 0)
+            msg.suggestedPrompts = suggestedPrompts;
+        if (uiActions && uiActions.length > 0)
+            msg.uiActions = uiActions;
+        if (messageId)
+            msg.messageId = messageId;
+        this.history.add(msg);
+        await this.persistHistory();
+        return { answer, suggestedPrompts };
+    }
+    // ---- Suggested prompts ----
+    async generateSuggestions(userMessage, answer, subagents) {
+        // The only domain we explicitly funnel is `pool`: once the user is looking
+        // at a pool, the most valuable next step is almost always to add liquidity
+        // or estimate yield on THAT pool, so we hard-code that bias. For every
+        // other domain we let the model derive suggestions from the message + answer.
+        const poolFunnel = subagents.includes('pool')
+            ? '\nPOOL FUNNEL: This turn was handled by the pool subagent. If the answer references a SPECIFIC pool ' +
+                '(token pair + fee tier, or a pool address), the FIRST suggestion MUST propose adding liquidity to ' +
+                'THAT exact pool (e.g. "Add liquidity to USDC/WETH 0.05%"). A second suggestion should propose ' +
+                'estimating yield for a deposit into the same pool. Skip this funnel only if no specific pool is ' +
+                'identifiable in the answer.\n'
+            : '';
+        const handledBy = subagents.length > 0 ? `\nHandled by subagent(s): ${subagents.join(', ')}` : '';
+        try {
+            const response = await this.llm.chat([
+                {
+                    role: 'user',
+                    content: 'Analyze this conversation and propose follow-up prompts the user is likely to want NEXT.\n\n' +
+                        `User: ${userMessage}\nAssistant: ${answer}${handledBy}\n` +
+                        poolFunnel +
+                        '\nRULES:\n' +
+                        '- Derive suggestions from the user message + the assistant answer. Reference concrete entities that appear there (pool name, token symbol, chain, address, NFT, wallet).\n' +
+                        '- Prefer ACTION-ORIENTED suggestions over informational ones whenever the answer makes one possible. Example after showing a pool: "Add liquidity to USDC/WETH 0.05%", not "what is a liquidity pool?".\n' +
+                        '- Reference concrete entities from the answer (pool name, token symbol, chain, address) — never generic placeholders.\n' +
+                        '- If the topic is shallow, closed-ended, or fully resolved (greetings, simple yes/no, trivial facts), return an empty array: []\n' +
+                        '- Return a JSON array of 0 to 3 strings, no other text.\n' +
+                        '- Each suggestion must be concise (under 60 chars) and phrased as something the user would TYPE.\n' +
+                        '- Suggestions must be diverse — do not repeat the same intent in different words.\n' +
+                        '- Use the same language as the user.\n' +
+                        '- Good example (pool): ["Add liquidity to USDC/WETH 0.05%", "Estimate yield for $1000 here", "Compare with 0.3% fee tier"]\n' +
+                        '- Bad example: ["What is a pool?", "How do pools work?", "Tell me more"]  (generic, no action, no specifics)',
+                    timestamp: 0,
+                },
+            ]);
+            const match = response.text.match(/\[[\s\S]*\]/);
+            if (!match)
+                return [];
+            const suggestions = JSON.parse(match[0]);
+            return suggestions.filter((s) => typeof s === 'string' && s.length > 0).slice(0, 3);
+        }
+        catch {
+            return [];
+        }
+    }
+    // ---- History management ----
+    getHistory() {
+        return this.history.getAllFull();
+    }
+    /**
+     * History filtered down to user-facing messages only — the user's prompts
+     * and each turn's final assistant reply. Internal records (tool calls,
+     * tool results, system summaries, and `_intermediate` bridging assistant
+     * messages) are dropped, as is any assistant message with empty content
+     * (a pure tool-call turn). Use this to seed a chat UI on mount.
+     */
+    getDisplayHistory() {
+        return this.history.getAllFull().filter((m) => {
+            if (m.role !== 'user' && m.role !== 'assistant')
+                return false;
+            if (m._intermediate)
+                return false;
+            if (m.role === 'assistant' && !m.content?.trim())
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Suggested follow-up prompts attached to the most recent final assistant
+     * turn, or `[]` if none. Used to re-seed suggestion chips after restoring
+     * a persisted session — the chips travel with the assistant message in
+     * storage, so this just locates the last one.
+     */
+    getLastSuggestions() {
+        const display = this.getDisplayHistory();
+        for (let i = display.length - 1; i >= 0; i--) {
+            const m = display[i];
+            if (m.role === 'assistant')
+                return m.suggestedPrompts ?? [];
+        }
+        return [];
+    }
+    async clearHistory() {
+        this.history.clear();
+        this.historyLoaded = true; // cleared intentionally, no need to re-load
+        this.historyLoadingPromise = null;
+        await this.persistHistory();
+    }
+    restoreHistory(data) {
+        this.history.restore(data);
+    }
+    serialiseHistory() {
+        return this.history.serialise();
+    }
+    // ---- Internals ----
+    async compactHistory() {
+        if (this.debug) {
+            console.log('[AgentCore] Summarizing conversation history…');
+        }
+        const all = this.history.getAll();
+        // Keep the last 6 user turns (plus any tool messages belonging to those
+        // turns) so the working window always has meaningful recent context.
+        // We count backward by user turns rather than raw message count because
+        // tool exchanges inflate the raw count without adding user-visible turns.
+        const USER_TURNS_TO_KEEP = 6;
+        let userTurnsSeen = 0;
+        let keepStart = all.length;
+        for (let i = all.length - 1; i >= 0; i--) {
+            if (all[i].role === 'user') {
+                userTurnsSeen++;
+                if (userTurnsSeen >= USER_TURNS_TO_KEEP) {
+                    keepStart = i;
+                    break;
+                }
+            }
+        }
+        // Never split a tool-call group at the boundary.
+        const rawTail = all.slice(keepStart);
+        const keepTail = (0, historyUtils_1.trimPreservingToolPairs)(rawTail, rawTail.length);
+        const tailStart = all.length - keepTail.length;
+        const toSummarize = (0, historyUtils_1.stripToolMessages)(all.slice(0, tailStart));
+        const existingSummary = this.history.getSummary();
+        // Prepend the existing summary as a User turn so Summarizer includes it
+        // in the rolling summary (Summarizer filters to user/assistant only).
+        const messagesForSummary = [];
+        if (existingSummary) {
+            messagesForSummary.push({
+                role: 'user',
+                content: `[Previous context summary]: ${existingSummary}`,
+                timestamp: 0,
+            });
+        }
+        messagesForSummary.push(...toSummarize);
+        const summary = await this.summarizer.summarize(messagesForSummary);
+        this.history.compactWith(summary, keepTail);
+    }
+    /**
+     * Persist the interleaved assistant+toolCalls / role:'tool' messages from
+     * each subagent run into ChatHistory, followed by the subagent's finalAnswer
+     * as a plain assistant turn.
+     *
+     * The full sequence stored per subagent is:
+     *   model(functionCall) → function(response) → ... → model(text: finalAnswer)
+     *
+     * This satisfies Gemini's strict turn-order rule: a function-response turn
+     * must always be followed by a model turn before the next user message.
+     * Without the trailing model(text), the history ends with function(response)
+     * and the next user message causes a 400 "function call turn must come
+     * immediately after a user turn" error.
+     */
+    persistToolMessages(results) {
+        for (const r of results) {
+            if (r.toolMessages.length > 0) {
+                this.history.addMany(r.toolMessages);
+                // Append the subagent's final text answer so the history always ends
+                // with model(text) after a tool exchange — never with function(response).
+                this.history.add({
+                    role: 'assistant',
+                    content: r.finalAnswer,
+                    _intermediate: true,
+                    timestamp: Date.now(),
+                });
+                if (this.debug) {
+                    console.log(`[AgentCore] stored ${r.toolMessages.length} tool message(s) + finalAnswer from ${r.subagentName}`);
+                }
+            }
+        }
+    }
+    /** Expose the LLM provider for advanced usage. */
+    getLLMProvider() {
+        return this.llm;
+    }
+    /** Expose the tool registry for advanced usage. */
+    getToolRegistry() {
+        return this.registry;
+    }
+}
+exports.AgentCore = AgentCore;
+//# sourceMappingURL=AgentCore.js.map