@t2000/engine 0.7.5 → 0.7.7

package/README.md

@@ -87,7 +87,7 @@ QueryEngine.submitMessage()
 
 ## Built-in Tools
 
-### Read Tools (19 — parallel, auto-approved)
+### Read Tools (20 — parallel, auto-approved)
 
 | Tool | Description |
 |------|-------------|
@@ -96,6 +96,7 @@ QueryEngine.submitMessage()
 | `health_check` | Health factor with risk assessment |
 | `rates_info` | Current supply/borrow APYs |
 | `transaction_history` | Recent transaction log |
+| `allowance_status` | Agent budget allowance and permissions |
 | `explain_tx` | Human-readable transaction explanation from digest |
 | `web_search` | Web search via Brave Search API |
 | `swap_quote` | Preview swap route, output amount, and price impact (no execution) |

package/dist/index.d.ts

@@ -790,6 +790,7 @@ declare const balanceCheckTool: Tool<{}, {
     total: number;
     stables: number;
     holdings: any[];
+    saveableUsdc: number;
 }>;
 
 declare const savingsInfoTool: Tool<{}, SavingsResult>;
@@ -849,6 +850,7 @@ declare const withdrawTool: Tool<{
 declare const sendTransferTool: Tool<{
     amount: number;
     to: string;
+    memo?: string | undefined;
 }, {
     success: boolean;
     tx: string;
@@ -858,6 +860,7 @@ declare const sendTransferTool: Tool<{
     gasCost: number;
     gasMethod: _t2000_sdk.GasMethod;
     balance: _t2000_sdk.BalanceResponse;
+    memo: string | null;
 }>;
 
 declare const borrowTool: Tool<{
@@ -1175,6 +1178,6 @@ declare function fetchWalletCoins(address: string, rpcUrl?: string): Promise<Wal
 declare function fetchTokenPrices(coinTypes: string[]): Promise<Record<string, number>>;
 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## 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- save_deposit: USDC only. To save other tokens, swap to USDC first.\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.";
+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, type BuildToolOptions, type ChatParams, type CompactOptions, type ContentBlock, type CostSnapshot, CostTracker, type CostTrackerConfig, DEFAULT_SYSTEM_PROMPT, type EngineConfig, type EngineEvent, 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 PendingAction, type PendingReward, type PendingToolCall, type PermissionLevel, type PermissionResponse, type PositionEntry, type ProtocolStats, type ProviderEvent, QueryEngine, READ_TOOLS, type RatesResult, type SSEEvent, type SavingsResult, type ServerPositionData, type SessionData, type SessionStore, type StopReason, type SuiCoinBalance, type Tool, type ToolChoice, type ToolContext, type ToolDefinition, type ToolJsonSchema, type ToolResult, TxMutex, WRITE_TOOLS, type WalletCoin, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, balanceCheckTool, borrowTool, buildMcpTools, buildTool, claimRewardsTool, clearPriceCache, compactMessages, defillamaChainTvlTool, defillamaPriceChangeTool, defillamaProtocolFeesTool, defillamaProtocolInfoTool, defillamaSuiProtocolsTool, defillamaTokenPricesTool, defillamaYieldPoolsTool, engineToSSE, estimateTokens, explainTxTool, extractMcpText, fetchAvailableRewards, fetchBalance, fetchHealthFactor, fetchPositions, fetchProtocolStats, fetchRates, fetchSavings, fetchTokenPrices, fetchWalletCoins, findTool, getDefaultTools, getMcpManager, getWalletAddress, hasNaviMcp, healthCheckTool, mppServicesTool, parseMcpJson, parseSSE, payApiTool, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, registerEngineTools, repayDebtTool, requireAgent, runTools, saveContactTool, saveDepositTool, savingsInfoTool, sendTransferTool, serializeSSE, swapExecuteTool, swapQuoteTool, toolsToDefinitions, transactionHistoryTool, transformBalance, transformHealthFactor, transformPositions, transformRates, transformRewards, transformSavings, validateHistory, voloStakeTool, voloStatsTool, voloUnstakeTool, webSearchTool, withdrawTool };

package/dist/index.js

@@ -480,7 +480,7 @@ async function callNavi(manager, tool, args = {}) {
 }
 var balanceCheckTool = buildTool({
   name: "balance_check",
-  description: "Get the user's full balance breakdown: available USDC, savings deposits, outstanding debt, pending rewards, gas reserve, and total net worth.",
+  description: "Get the user's full balance breakdown. Returns wallet holdings (tokens the user owns \u2014 NOT savings), NAVI savings deposits (USDC deposited into NAVI Protocol earning yield), outstanding debt, pending rewards, gas reserve, total net worth, and saveableUsdc (only USDC can be deposited into savings). IMPORTANT: wallet holdings like GOLD, SUI, USDT are NOT savings positions \u2014 they are just tokens sitting in the wallet.",
   inputSchema: z.object({}),
   jsonSchema: { type: "object", properties: {}, required: [] },
   isReadOnly: true,
@@ -578,6 +578,8 @@ var balanceCheckTool = buildTool({
         pendingRewardsUsd = rewardEntries.reduce((sum, r) => sum + r.valueUsd, 0);
       }
       const visibleHoldings = holdings.filter((h) => h.usdValue >= 0.01).sort((a, b) => b.usdValue - a.usdValue);
+      const usdcHolding2 = holdings.find((h) => h.symbol === "USDC");
+      const saveableUsdc = usdcHolding2 ? usdcHolding2.balance : 0;
       const bal = {
         available: availableUsd,
         savings,
@@ -586,11 +588,13 @@ var balanceCheckTool = buildTool({
         gasReserve: gasReserveUsd2,
         total: availableUsd + savings + gasReserveUsd2 + pendingRewardsUsd - debt,
         stables: stablesUsd,
-        holdings: visibleHoldings
+        holdings: visibleHoldings,
+        saveableUsdc
       };
+      const holdingsList = visibleHoldings.map((h) => `${h.symbol}: ${h.balance < 1 ? h.balance.toFixed(6) : h.balance.toFixed(2)} ($${h.usdValue.toFixed(2)})`).join(", ");
       return {
         data: bal,
-        displayText: `Balance: $${bal.total.toFixed(2)} (Available: $${bal.available.toFixed(2)}, Savings: $${bal.savings.toFixed(2)})`
+        displayText: `Balance: $${bal.total.toFixed(2)} total. Wallet holdings (NOT savings): ${holdingsList || "none"}. NAVI savings deposits: $${bal.savings.toFixed(2)}. Saveable USDC (only USDC can be saved): ${saveableUsdc.toFixed(2)} USDC.`
       };
     }
     const agent = requireAgent(context);
@@ -599,6 +603,8 @@ var balanceCheckTool = buildTool({
     const stablesTotal = typeof balance.stables === "number" ? balance.stables : Object.values(balance.stables).reduce((a, b) => a + b, 0);
     const sdkHoldings = balance.holdings;
     const holdingsArr = Array.isArray(sdkHoldings) ? sdkHoldings : [];
+    const usdcHolding = holdingsArr.find((h) => h.symbol === "USDC");
+    const sdkSaveableUsdc = usdcHolding ? usdcHolding.balance ?? 0 : 0;
     return {
       data: {
         available: balance.available,
@@ -608,9 +614,10 @@ var balanceCheckTool = buildTool({
         gasReserve: gasReserveUsd,
         total: balance.total,
         stables: stablesTotal,
-        holdings: holdingsArr
+        holdings: holdingsArr,
+        saveableUsdc: sdkSaveableUsdc
       },
-      displayText: `Balance: $${balance.total.toFixed(2)} (Available: $${balance.available.toFixed(2)}, Savings: $${balance.savings.toFixed(2)})`
+      displayText: `Balance: $${balance.total.toFixed(2)} total. Wallet: $${balance.available.toFixed(2)} available. NAVI savings deposits: $${balance.savings.toFixed(2)}. Saveable USDC (only USDC can be saved): ${sdkSaveableUsdc.toFixed(2)} USDC.`
     };
   }
 });
@@ -1128,7 +1135,8 @@ var sendTransferTool = buildTool({
   description: "Send USDC to another Sui address or contact name. Validates the address, checks balance, and executes the on-chain transfer. Returns tx hash, gas cost, and updated balance.",
   inputSchema: z.object({
     to: z.string().min(1),
-    amount: z.number().positive()
+    amount: z.number().positive(),
+    memo: z.string().optional()
   }),
   jsonSchema: {
     type: "object",
@@ -1140,6 +1148,10 @@ var sendTransferTool = buildTool({
       amount: {
         type: "number",
         description: "Amount in USD to send"
+      },
+      memo: {
+        type: "string",
+        description: "Optional note attached to the transfer (shown in transaction receipt)"
       }
     },
     required: ["to", "amount"]
@@ -1158,7 +1170,8 @@ var sendTransferTool = buildTool({
         contactName: result.contactName,
         gasCost: result.gasCost,
         gasMethod: result.gasMethod,
-        balance: result.balance
+        balance: result.balance,
+        memo: input.memo ?? null
       },
       displayText: `Sent $${result.amount.toFixed(2)} to ${result.contactName ?? result.to.slice(0, 10)}\u2026 (tx: ${result.tx.slice(0, 8)}\u2026)`
     };
@@ -1288,7 +1301,15 @@ var payApiTool = buildTool({
 
 Use mpp_services tool first to discover available services and get the correct endpoint URL, required body parameters, and pricing. Then call this tool with the full URL and JSON body.
 
-Always use POST. Construct the URL from the gateway base + service path. Pass parameters as a JSON string in body.`,
+Always use POST. Construct the URL from the gateway base + service path. Pass parameters as a JSON string in body.
+
+CRITICAL \u2014 non-retryable errors: If the result contains "doNotRetry": true or "paymentConfirmed": true, the user has ALREADY been charged. NEVER call pay_api again for the same request. Report the error to the user.
+
+Lob (postcards/letters) \u2014 MULTI-STEP, NEVER skip:
+1. Generate design image FIRST via fal/fal-ai/flux/dev ($0.03). Show the image to the user as markdown ![design](url).
+2. Ask the user to confirm before mailing ("Here's the design. Print and mail for $1.00?").
+3. ONLY after user confirms: call lob/v1/postcards with the image URL in the front HTML (<img src="URL" style="width:100%;height:100%;object-fit:cover"/>).
+Always use ISO-3166 country codes (GB not UK, US not USA). A return address ("from") is added automatically \u2014 do not include one.`,
   inputSchema: z.object({
     url: z.string().url(),
     method: z.enum(["GET", "POST", "PUT", "DELETE"]).optional(),
@@ -1964,6 +1985,56 @@ Risks: ${riskFactors.join("; ")}`
     };
   }
 });
+var allowanceStatusTool = buildTool({
+  name: "allowance_status",
+  description: "Check the agent spending allowance status: whether it is enabled, the daily USDC limit, amount spent today, remaining budget, which service categories are permitted, and when the budget resets. Use this when the user asks about their agent budget, spending limits, or autonomous transaction permissions.",
+  inputSchema: z.object({}),
+  jsonSchema: { type: "object", properties: {}, required: [] },
+  isReadOnly: true,
+  async call(_input, context) {
+    if (!context.env?.ALLOWANCE_API_URL || !context.walletAddress) {
+      return {
+        data: {
+          enabled: false,
+          dailyLimit: 0,
+          spent: 0,
+          remaining: 0,
+          permissions: [],
+          resetsAt: null
+        },
+        displayText: "Agent allowance is not configured."
+      };
+    }
+    const disabledResult = {
+      data: {
+        enabled: false,
+        dailyLimit: 0,
+        spent: 0,
+        remaining: 0,
+        permissions: [],
+        resetsAt: null
+      },
+      displayText: "Unable to fetch allowance status."
+    };
+    let allowance;
+    try {
+      const url = `${context.env.ALLOWANCE_API_URL}/api/allowance/${context.walletAddress}`;
+      const res = await fetch(url, {
+        signal: context.signal,
+        headers: context.env.AUDRIC_INTERNAL_KEY ? { "x-internal-key": context.env.AUDRIC_INTERNAL_KEY } : void 0
+      });
+      if (!res.ok) return disabledResult;
+      allowance = await res.json();
+    } catch {
+      return disabledResult;
+    }
+    const statusText = allowance.enabled ? `Allowance active: $${allowance.spent.toFixed(2)} / $${allowance.dailyLimit.toFixed(2)} used today. ${allowance.permissions.length} service categories enabled.` : "Agent allowance is disabled.";
+    return {
+      data: allowance,
+      displayText: statusText
+    };
+  }
+});
 var LLAMA_API2 = "https://api.llama.fi";
 var YIELDS_API2 = "https://yields.llama.fi";
 var COINS_API = "https://coins.llama.fi";
@@ -2266,7 +2337,8 @@ var READ_TOOLS = [
   defillamaPriceChangeTool,
   defillamaChainTvlTool,
   defillamaProtocolFeesTool,
-  defillamaSuiProtocolsTool
+  defillamaSuiProtocolsTool,
+  allowanceStatusTool
 ];
 var WRITE_TOOLS = [
   saveDepositTool,
@@ -2311,12 +2383,17 @@ Only offer to execute actions you have tools for. If you retrieved a quote, data
 - Run multiple read-only tools in parallel when you need several data points.
 - If a tool errors, say what went wrong and what to try instead. One sentence.
 
+## Savings = USDC only (critical)
+- save_deposit accepts ONLY USDC. No other token can be deposited into savings.
+- 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.
+- 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.
+- If user wants to save non-USDC tokens, tell them to swap to USDC first. Do NOT auto-chain swap + deposit.
+
 ## Multi-step flows
 - "How much X for Y?": swap_quote first, then swap_execute if user confirms.
 - "Swap then save": swap_execute \u2192 balance_check \u2192 save_deposit. Confirm each step.
 - "Buy $X of token": defillama_token_prices \u2192 calculate amount \u2192 swap_execute.
 - "Best yield on SUI": compare rates_info (NAVI lending) + defillama_yield_pools (broader) + volo_stats.
-- save_deposit: USDC only. To save other tokens, swap to USDC first.
 - withdraw supports legacy positions: USDC, USDe, USDsui, SUI. Pass asset param to withdraw a specific token.
 - "Deposit SUI to earn yield": volo_stake for SUI liquid staking. save_deposit is USDC only.
 - "What protocols are on Sui?": defillama_sui_protocols \u2192 defillama_protocol_info for details.