@t2000/engine 0.33.2 → 0.35.0

package/dist/index.d.ts

@@ -152,6 +152,12 @@ declare class TxMutex {
     release(): void;
 }
 declare function runTools(pending: PendingToolCall[], tools: Tool[], context: ToolContext, txMutex: TxMutex): AsyncGenerator<EngineEvent>;
+/**
+ * Enforce per-tool result size limits. When a serialized result exceeds
+ * `maxResultSizeChars`, truncate it with a hint to re-call with narrower
+ * parameters. Uses the tool's custom `summarizeOnTruncate` when available.
+ */
+declare function budgetToolResult(data: unknown, tool: Tool): unknown;
 
 type GuardVerdict = 'pass' | 'hint' | 'warn' | 'block';
 type GuardTier = 'safety' | 'financial' | 'ux';
@@ -240,6 +246,106 @@ declare function extractConversationText(messages: Array<{
     lastAssistantText: string;
 };
 
+/**
+ * USD-aware permission resolution for write tools.
+ *
+ * Replaces the binary auto/confirm/explicit system with dollar-threshold
+ * tiers that resolve at runtime based on the transaction value and
+ * per-user configuration.
+ */
+type PermissionOperation = 'save' | 'withdraw' | 'send' | 'borrow' | 'repay' | 'swap' | 'pay';
+interface PermissionRule {
+    operation: PermissionOperation;
+    /** Auto-execute if USD amount is below this threshold. */
+    autoBelow: number;
+    /** Confirm if between autoBelow and this. Explicit for anything above. */
+    confirmBetween: number;
+}
+interface UserPermissionConfig {
+    rules: PermissionRule[];
+    /** Fallback auto threshold for operations without a specific rule. */
+    globalAutoBelow: number;
+    /** Max total USD of autonomous actions per day (safety net). */
+    autonomousDailyLimit: number;
+}
+declare const DEFAULT_PERMISSION_CONFIG: UserPermissionConfig;
+declare const PERMISSION_PRESETS: {
+    conservative: {
+        globalAutoBelow: number;
+        autonomousDailyLimit: number;
+        rules: ({
+            operation: "save";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "send";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "borrow";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "withdraw";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "swap";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "pay";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "repay";
+            autoBelow: number;
+            confirmBetween: number;
+        })[];
+    };
+    balanced: UserPermissionConfig;
+    aggressive: {
+        globalAutoBelow: number;
+        autonomousDailyLimit: number;
+        rules: ({
+            operation: "save";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "send";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "borrow";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "withdraw";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "swap";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "pay";
+            autoBelow: number;
+            confirmBetween: number;
+        } | {
+            operation: "repay";
+            autoBelow: number;
+            confirmBetween: number;
+        })[];
+    };
+};
+declare function resolvePermissionTier(operation: string, amountUsd: number, config: UserPermissionConfig): 'auto' | 'confirm' | 'explicit';
+declare function toolNameToOperation(toolName: string): PermissionOperation | undefined;
+/**
+ * Resolve the USD value of a tool call from its inputs.
+ * USDC-denominated tools return 1:1. Others multiply by the price cache.
+ */
+declare function resolveUsdValue(toolName: string, input: Record<string, unknown>, priceCache: Map<string, number>): number;
+
 type ContentBlock = {
     type: 'text';
     text: string;
@@ -358,6 +464,10 @@ interface ToolContext {
     /** Environment variables passed to tools (e.g. API keys not in process.env) */
     env?: Record<string, string>;
     signal?: AbortSignal;
+    /** Token symbol → USD price map for USD-aware permission resolution (B.4). */
+    priceCache?: Map<string, number>;
+    /** Per-user permission config for USD-threshold write tool gating (B.4). */
+    permissionConfig?: UserPermissionConfig;
 }
 interface ServerPositionData {
     savings: number;
@@ -412,6 +522,10 @@ interface Tool<TInput = unknown, TOutput = unknown> {
     permissionLevel: PermissionLevel;
     flags: ToolFlags;
     preflight?: (input: unknown) => PreflightResult;
+    /** Max chars for the serialized tool result. Truncated with a re-call hint when exceeded. */
+    maxResultSizeChars?: number;
+    /** Custom truncation strategy. Falls back to generic slice + hint when omitted. */
+    summarizeOnTruncate?: (result: string, maxChars: number) => string;
 }
 type ThinkingEffort = 'low' | 'medium' | 'high' | 'max';
 type ThinkingConfig = {
@@ -469,6 +583,10 @@ interface EngineConfig {
     contextBudget?: ContextBudgetConfig;
     /** LLM-based summarizer for context compaction (RE-3.3). */
     contextSummarizer?: (messages: Message[]) => Promise<string>;
+    /** Token symbol → USD price map for USD-aware permission resolution (B.4). */
+    priceCache?: Map<string, number>;
+    /** Per-user permission config for USD-threshold write tool gating (B.4). */
+    permissionConfig?: UserPermissionConfig;
 }
 interface LLMProvider {
     chat(params: ChatParams): AsyncGenerator<ProviderEvent>;
@@ -589,6 +707,8 @@ declare class QueryEngine {
     private readonly recipes;
     private readonly contextBudget;
     private readonly contextSummarizer;
+    private readonly priceCache;
+    private readonly permissionConfig;
     private matchedRecipe;
     private messages;
     private abortController;
@@ -650,6 +770,8 @@ interface BuildToolOptions<TInput, TOutput> {
     permissionLevel?: PermissionLevel;
     flags?: ToolFlags;
     preflight?: (input: TInput) => PreflightResult;
+    maxResultSizeChars?: number;
+    summarizeOnTruncate?: (result: string, maxChars: number) => string;
 }
 declare function buildTool<TInput, TOutput>(opts: BuildToolOptions<TInput, TOutput>): Tool<TInput, TOutput>;
 declare function toolsToDefinitions(tools: Tool[]): {
@@ -861,6 +983,52 @@ interface ConversationStateStore {
 }
 declare function buildStateContext(state: ConversationState): string;
 
+/**
+ * Zero-cost deduplication pass: if the same tool was called with identical
+ * inputs earlier in the conversation and the result hasn't changed, replace
+ * the full prior result with a compact back-reference. Runs before any
+ * LLM-based compaction and costs nothing.
+ *
+ * Returns a new array — does not mutate the input.
+ */
+declare function microcompact(messages: readonly Message[]): Message[];
+
+/**
+ * EarlyToolDispatcher — dispatches read-only tools mid-stream.
+ *
+ * When the LLM emits `tool_use_done` for a read-only tool, the dispatcher
+ * fires it immediately in the background rather than waiting for the full
+ * stream to finish. Results are collected in original call order after the
+ * stream exits.
+ *
+ * Write tools are NOT dispatched — they go through the existing permission
+ * gate and TxMutex flow.
+ */
+
+declare class EarlyToolDispatcher {
+    private entries;
+    private readonly tools;
+    private readonly context;
+    private abortController;
+    constructor(tools: Tool[], context: ToolContext);
+    /**
+     * Attempt to dispatch a tool call. Returns true if the tool was dispatched
+     * (read-only + concurrency-safe), false if it should be queued for later.
+     */
+    tryDispatch(call: PendingToolCall): boolean;
+    /** True if any tools have been dispatched. */
+    hasPending(): boolean;
+    /** List of call IDs that were early-dispatched. */
+    dispatchedIds(): Set<string>;
+    /**
+     * Collect all results in original dispatch order.
+     * Yields `tool_result` events as each promise resolves.
+     */
+    collectResults(): AsyncGenerator<EngineEvent>;
+    /** Cancel all in-flight tool calls. */
+    abort(): void;
+}
+
 interface McpToolDescriptor {
     name: string;
     description: string;
@@ -1666,4 +1834,4 @@ declare function clearPriceCache(): void;
 
 declare const DEFAULT_SYSTEM_PROMPT = "You are a financial agent on Sui. You manage money and access paid APIs via MPP micropayments.\n\n## Response rules\n- 1-2 sentences max. No bullet lists unless asked. No preambles.\n- Never say \"Would you like me to...\", \"Sure!\", \"Great question!\", \"Absolutely!\" \u2014 just do it or say you can't.\n- Lead with the result. After tool calls, state the outcome with real numbers. Done.\n- Present amounts as $1,234.56 and rates as X.XX% APY.\n- Show top 3 results unless asked for more. Summarize totals in one line.\n\n## Execution rule\nOnly offer to execute actions you have tools for. If you retrieved a quote, data, or information but have no tool to act on it, give the user the result and tell them where to execute manually \u2014 in one sentence. Never say \"Would you like me to proceed?\" unless you have a tool that can actually proceed.\n\n## Before acting\n- ALWAYS call a read tool first before any write tool \u2014 balance_check before save/send/borrow, savings_info before withdraw.\n- Show real numbers from tools \u2014 never fabricate rates, amounts, or balances.\n- When user says \"all\" or an imprecise amount, call the read tool first to get the exact number.\n\n## Tool usage\n- Use tools proactively \u2014 don't refuse requests you can handle.\n- For real-world questions (weather, search, news, prices), use pay_api. Tell the user the cost first.\n- For broad market data (yields across protocols, token prices, TVL, protocol comparisons), use defillama_* tools.\n- To discover Sui protocols, use defillama_sui_protocols first, then defillama_protocol_info with the slug.\n- Run multiple read-only tools in parallel when you need several data points.\n- If a tool errors, say what went wrong and what to try instead. One sentence.\n\n## Savings = USDC only (critical)\n- save_deposit accepts ONLY USDC. No other token can be deposited into savings.\n- When asked \"how much can I save?\", report only the user's USDC wallet balance (saveableUsdc field from balance_check). Other tokens like GOLD, SUI, USDT are NOT saveable and NOT savings positions \u2014 they are just wallet holdings.\n- NEVER say a non-USDC token is \"in savings\" or \"earning APY in savings\" unless it appears in the savings_info positions list. Wallet holdings \u2260 savings.\n- If user wants to save non-USDC tokens, tell them to swap to USDC first. Do NOT auto-chain swap + deposit.\n\n## Multi-step flows\n- \"How much X for Y?\": swap_quote first, then swap_execute if user confirms.\n- \"Swap then save\": swap_execute \u2192 balance_check \u2192 save_deposit. Confirm each step.\n- \"Buy $X of token\": defillama_token_prices \u2192 calculate amount \u2192 swap_execute.\n- \"Best yield on SUI\": compare rates_info (NAVI lending) + defillama_yield_pools (broader) + volo_stats.\n- withdraw supports legacy positions: USDC, USDe, USDsui, SUI. Pass asset param to withdraw a specific token.\n- \"Deposit SUI to earn yield\": volo_stake for SUI liquid staking. save_deposit is USDC only.\n- \"What protocols are on Sui?\": defillama_sui_protocols \u2192 defillama_protocol_info for details.\n\n## Safety\n- Never encourage risky financial behavior.\n- Warn when health factor < 1.5.\n- All amounts in USDC unless stated otherwise.";
 
-export { AnthropicProvider, type AnthropicProviderConfig, type BalancePrices, type BalanceResult, BalanceTracker, type BuildToolOptions, CANVAS_TEMPLATES, type CanvasTemplate, type ChatParams, type CompactOptions, type ContentBlock, ContextBudget, type ContextBudgetConfig, type ConversationState, type ConversationStateStore, type CostSnapshot, CostTracker, type CostTrackerConfig, DEFAULT_GUARD_CONFIG, DEFAULT_SYSTEM_PROMPT, type EngineConfig, type EngineEvent, type GuardCheckResult, type GuardConfig, type GuardEvent, type GuardInjection, type GuardResult, type GuardRunnerState, type GuardTier, type GuardVerdict, type HealthFactorResult, type LLMProvider, type McpCallResult, McpClientManager, McpResponseCache, type McpServerConfig, type McpServerConnection, type McpToolAdapterConfig, type McpToolDescriptor, MemorySessionStore, type Message, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_SERVER_NAME, type NaviRawCoin, type NaviRawHealthFactor, type NaviRawPool, type NaviRawPosition, type NaviRawPositionsResponse, type NaviRawProtocolStats, type NaviRawRewardsResponse, type NaviReadOptions, NaviTools, type OutputConfig, type PendingAction, type PendingReward, type PendingToolCall, type PermissionLevel, type PermissionResponse, type PositionEntry, type PreflightResult, type ProtocolStats, type ProviderEvent, QueryEngine, READ_TOOLS, type RatesResult, type Recipe, type RecipePrerequisite, RecipeRegistry, type RecipeStep, type RecipeStepOnError, RetryTracker, type SSEEvent, type SavingsResult, type ServerPositionData, type SessionData, type SessionStore, type StateType, type StopReason, type SuiCoinBalance, type SystemBlock, type SystemPrompt, TOOL_FLAGS, type ThinkingConfig, type ThinkingEffort, type Tool, type ToolChoice, type ToolContext, type ToolDefinition, type ToolFlags, type ToolJsonSchema, type ToolResult, TxMutex, type UserFinancialProfile, WRITE_TOOLS, type WalletCoin, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, applyToolFlags, balanceCheckTool, borrowTool, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, claimRewardsTool, classifyEffort, clearPriceCache, compactMessages, createGuardRunnerState, defillamaChainTvlTool, defillamaPriceChangeTool, defillamaProtocolFeesTool, defillamaProtocolInfoTool, defillamaSuiProtocolsTool, defillamaTokenPricesTool, defillamaYieldPoolsTool, engineToSSE, estimateTokens, explainTxTool, extractConversationText, extractMcpText, fetchAvailableRewards, fetchBalance, fetchHealthFactor, fetchPositions, fetchProtocolStats, fetchRates, fetchSavings, fetchTokenPrices, fetchWalletCoins, findTool, getDefaultTools, getMcpManager, getToolFlags, getWalletAddress, guardArtifactPreview, guardStaleData, hasNaviMcp, healthCheckTool, loadRecipes, mppServicesTool, parseMcpJson, parseRecipe, parseSSE, payApiTool, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, registerEngineTools, renderCanvasTool, repayDebtTool, requireAgent, runGuards, runTools, saveContactTool, saveDepositTool, savingsInfoTool, sendTransferTool, serializeSSE, spendingAnalyticsTool, swapExecuteTool, swapQuoteTool, toolsToDefinitions, transactionHistoryTool, transformBalance, transformHealthFactor, transformPositions, transformRates, transformRewards, transformSavings, updateGuardStateAfterToolResult, validateHistory, voloStakeTool, voloStatsTool, voloUnstakeTool, webSearchTool, withdrawTool, yieldSummaryTool };
+export { AnthropicProvider, type AnthropicProviderConfig, type BalancePrices, type BalanceResult, BalanceTracker, type BuildToolOptions, CANVAS_TEMPLATES, type CanvasTemplate, type ChatParams, type CompactOptions, type ContentBlock, ContextBudget, type ContextBudgetConfig, type ConversationState, type ConversationStateStore, type CostSnapshot, CostTracker, type CostTrackerConfig, DEFAULT_GUARD_CONFIG, DEFAULT_PERMISSION_CONFIG, DEFAULT_SYSTEM_PROMPT, EarlyToolDispatcher, type EngineConfig, type EngineEvent, type GuardCheckResult, type GuardConfig, type GuardEvent, type GuardInjection, type GuardResult, type GuardRunnerState, type GuardTier, type GuardVerdict, type HealthFactorResult, type LLMProvider, type McpCallResult, McpClientManager, McpResponseCache, type McpServerConfig, type McpServerConnection, type McpToolAdapterConfig, type McpToolDescriptor, MemorySessionStore, type Message, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_SERVER_NAME, type NaviRawCoin, type NaviRawHealthFactor, type NaviRawPool, type NaviRawPosition, type NaviRawPositionsResponse, type NaviRawProtocolStats, type NaviRawRewardsResponse, type NaviReadOptions, NaviTools, type OutputConfig, PERMISSION_PRESETS, type PendingAction, type PendingReward, type PendingToolCall, type PermissionLevel, type PermissionOperation, type PermissionResponse, type PermissionRule, type PositionEntry, type PreflightResult, type ProtocolStats, type ProviderEvent, QueryEngine, READ_TOOLS, type RatesResult, type Recipe, type RecipePrerequisite, RecipeRegistry, type RecipeStep, type RecipeStepOnError, RetryTracker, type SSEEvent, type SavingsResult, type ServerPositionData, type SessionData, type SessionStore, type StateType, type StopReason, type SuiCoinBalance, type SystemBlock, type SystemPrompt, TOOL_FLAGS, type ThinkingConfig, type ThinkingEffort, type Tool, type ToolChoice, type ToolContext, type ToolDefinition, type ToolFlags, type ToolJsonSchema, type ToolResult, TxMutex, type UserFinancialProfile, type UserPermissionConfig, WRITE_TOOLS, type WalletCoin, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, applyToolFlags, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, claimRewardsTool, classifyEffort, clearPriceCache, compactMessages, createGuardRunnerState, defillamaChainTvlTool, defillamaPriceChangeTool, defillamaProtocolFeesTool, defillamaProtocolInfoTool, defillamaSuiProtocolsTool, defillamaTokenPricesTool, defillamaYieldPoolsTool, engineToSSE, estimateTokens, explainTxTool, extractConversationText, extractMcpText, fetchAvailableRewards, fetchBalance, fetchHealthFactor, fetchPositions, fetchProtocolStats, fetchRates, fetchSavings, fetchTokenPrices, fetchWalletCoins, findTool, getDefaultTools, getMcpManager, getToolFlags, getWalletAddress, guardArtifactPreview, guardStaleData, hasNaviMcp, healthCheckTool, loadRecipes, microcompact, mppServicesTool, parseMcpJson, parseRecipe, parseSSE, payApiTool, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, registerEngineTools, renderCanvasTool, repayDebtTool, requireAgent, resolvePermissionTier, resolveUsdValue, runGuards, runTools, saveContactTool, saveDepositTool, savingsInfoTool, sendTransferTool, serializeSSE, spendingAnalyticsTool, swapExecuteTool, swapQuoteTool, toolNameToOperation, toolsToDefinitions, transactionHistoryTool, transformBalance, transformHealthFactor, transformPositions, transformRates, transformRewards, transformSavings, updateGuardStateAfterToolResult, validateHistory, voloStakeTool, voloStatsTool, voloUnstakeTool, webSearchTool, withdrawTool, yieldSummaryTool };