@t2000/engine 0.47.1 → 0.49.0

package/dist/index.js

@@ -725,6 +725,7 @@ function clearPriceMapCache() {
 
 // src/tools/balance.ts
 var GAS_RESERVE_SUI2 = 0.05;
+var SUI_ADDRESS_REGEX = /^0x[a-fA-F0-9]{1,64}$/;
 var VSUI_COIN_TYPE = "0x549e8b69270defbfafd4f94e17ec44cdbdd99820b33bda2278dea3b9a32d3f55::cert::CERT";
 var SUI_COIN_TYPE = "0x2::sui::SUI";
 var VSUI_FALLBACK_RATE = 1.05;
@@ -776,20 +777,37 @@ async function loadPortfolio(address, blockvisionApiKey, fallbackRpcUrl, cache)
 }
 var balanceCheckTool = buildTool({
   name: "balance_check",
-  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: [] },
+  description: "Get the full balance breakdown for the signed-in user OR any public Sui address. Returns wallet holdings (tokens the address 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. Pass `address` to inspect a contact / watched / public wallet; defaults to the signed-in user when omitted.",
+  inputSchema: z.object({
+    address: z.string().regex(SUI_ADDRESS_REGEX).optional().describe("Sui address to inspect (defaults to the signed-in wallet)")
+  }),
+  jsonSchema: {
+    type: "object",
+    properties: {
+      address: {
+        type: "string",
+        pattern: "^0x[a-fA-F0-9]{1,64}$",
+        description: "Sui address to inspect (defaults to the signed-in wallet)"
+      }
+    },
+    required: []
+  },
   isReadOnly: true,
   // [v1.4 BlockVision] Wallet contents change after every send / swap /
   // save / etc. and the price half of this result is sourced from
   // BlockVision's Indexer REST API. Microcompact must NEVER dedupe these
   // calls — each one reflects a different on-chain + market snapshot.
   cacheable: false,
-  async call(_input, context) {
-    if (hasNaviMcp(context)) {
-      const address = getWalletAddress(context);
+  async call(input, context) {
+    const targetAddress = input.address ?? context.walletAddress;
+    const isSelfQuery = !!context.walletAddress && !!targetAddress && targetAddress.toLowerCase() === context.walletAddress.toLowerCase();
+    if (hasNaviMcpGlobal(context)) {
+      if (!targetAddress) {
+        throw new Error("No wallet address provided. Sign in or pass `address` to inspect a public wallet.");
+      }
+      const address = targetAddress;
       const mgr = getMcpManager(context);
-      const hasPositionFetcher = !!(context.positionFetcher && context.walletAddress);
+      const hasPositionFetcher = !!context.positionFetcher;
       const [portfolio, positions, rewards, serverPositions] = await Promise.all([
         loadPortfolio(
           address,
@@ -818,7 +836,7 @@ var balanceCheckTool = buildTool({
           console.warn("[balance_check] NAVI GET_AVAILABLE_REWARDS failed:", err);
           return null;
         }),
-        hasPositionFetcher ? context.positionFetcher(context.walletAddress).catch((err) => {
+        hasPositionFetcher ? context.positionFetcher(address).catch((err) => {
           console.warn("[balance_check] positionFetcher failed:", err);
           return null;
         }) : Promise.resolve(null)
@@ -878,14 +896,22 @@ var balanceCheckTool = buildTool({
         stables: stablesUsd,
         holdings: visibleHoldings,
         saveableUsdc,
-        priceSource: portfolio.source
+        priceSource: portfolio.source,
+        address,
+        isSelfQuery
       };
       const holdingsList = visibleHoldings.map((h) => `${h.symbol}: ${h.balance < 1 ? h.balance.toFixed(6) : h.balance.toFixed(2)} ($${h.usdValue.toFixed(2)})`).join(", ");
+      const subjectPrefix = isSelfQuery ? "Balance" : `Balance for ${address.slice(0, 6)}\u2026${address.slice(-4)}`;
       return {
         data: bal,
-        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.`
+        displayText: `${subjectPrefix}: $${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.`
       };
     }
+    if (input.address && context.walletAddress && input.address.toLowerCase() !== context.walletAddress.toLowerCase()) {
+      throw new Error(
+        `Cannot inspect ${input.address.slice(0, 8)}\u2026 without NAVI MCP enabled. Configure NAVI MCP to enable third-party address reads.`
+      );
+    }
     const agent = requireAgent(context);
     const balance = await agent.balance();
     const gasReserveUsd = typeof balance.gasReserve === "number" ? balance.gasReserve : balance.gasReserve.usdEquiv ?? 0;
@@ -904,7 +930,9 @@ var balanceCheckTool = buildTool({
         total: balance.total,
         stables: stablesTotal,
         holdings: holdingsArr,
-        saveableUsdc: sdkSaveableUsdc
+        saveableUsdc: sdkSaveableUsdc,
+        address: targetAddress ?? "",
+        isSelfQuery: true
       },
       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.`
     };
@@ -998,6 +1026,7 @@ async function fetchProtocolStats(manager, opts) {
 
 // src/tools/savings.ts
 var DUST_THRESHOLD_USD = 0.01;
+var SUI_ADDRESS_REGEX2 = /^0x[a-fA-F0-9]{1,64}$/;
 function buildSavingsFromPositions(sp) {
   const positions = [
     ...sp.supplies.filter((s) => s.amountUsd >= DUST_THRESHOLD_USD).map((s) => ({
@@ -1039,18 +1068,19 @@ function buildSavingsFromPositions(sp) {
     }
   };
 }
-function formatSavingsDisplay(result) {
+function formatSavingsDisplay(result, isSelfQuery = true, address) {
   const { positions, earnings, fundStatus } = result;
   const supplies = positions.filter((p) => p.type === "supply");
   const borrows = positions.filter((p) => p.type === "borrow");
+  const subjectPrefix = isSelfQuery || !address ? "" : `${address.slice(0, 6)}\u2026${address.slice(-4)} \u2014 `;
   const lines = [];
   if (supplies.length > 0) {
-    lines.push(`Savings: $${fundStatus.supplied.toFixed(2)} at ${(earnings.currentApy * 100).toFixed(2)}% blended APY`);
+    lines.push(`${subjectPrefix}Savings: $${fundStatus.supplied.toFixed(2)} at ${(earnings.currentApy * 100).toFixed(2)}% blended APY`);
     for (const s of supplies) {
       lines.push(`  ${s.symbol}: ${s.amount.toFixed(s.amount < 1 ? 6 : 2)} ($${s.valueUsd.toFixed(2)}) at ${(s.apy * 100).toFixed(2)}% APY`);
     }
   } else {
-    lines.push("No savings positions.");
+    lines.push(`${subjectPrefix}No savings positions.`);
   }
   if (borrows.length > 0) {
     const totalDebt = borrows.reduce((s, b) => s + b.valueUsd, 0);
@@ -1062,26 +1092,44 @@ function formatSavingsDisplay(result) {
 }
 var savingsInfoTool = buildTool({
   name: "savings_info",
-  description: "Get detailed savings positions and earnings: current deposits by protocol, APY, total yield earned, daily earning rate, and projected monthly returns.",
-  inputSchema: z.object({}),
-  jsonSchema: { type: "object", properties: {}, required: [] },
+  description: "Get detailed savings positions and earnings for the signed-in user OR any public Sui address: current deposits by protocol, APY, total yield earned, daily earning rate, and projected monthly returns. Pass `address` to inspect a contact / watched / public wallet; defaults to the signed-in user when omitted.",
+  inputSchema: z.object({
+    address: z.string().regex(SUI_ADDRESS_REGEX2).optional().describe("Sui address to inspect (defaults to the signed-in wallet)")
+  }),
+  jsonSchema: {
+    type: "object",
+    properties: {
+      address: {
+        type: "string",
+        pattern: "^0x[a-fA-F0-9]{1,64}$",
+        description: "Sui address to inspect (defaults to the signed-in wallet)"
+      }
+    },
+    required: []
+  },
   isReadOnly: true,
   // [v1.5.1] NAVI deposits change on save_deposit / withdraw / claim.
   // Each call reflects a fresh on-chain snapshot — never dedupe.
   cacheable: false,
-  async call(_input, context) {
-    if (context.positionFetcher && context.walletAddress) {
-      const sp = await context.positionFetcher(context.walletAddress);
+  async call(input, context) {
+    const targetAddress = input.address ?? context.walletAddress;
+    const isSelfQuery = !!context.walletAddress && !!targetAddress && targetAddress.toLowerCase() === context.walletAddress.toLowerCase();
+    if (context.positionFetcher && targetAddress) {
+      const sp = await context.positionFetcher(targetAddress);
       const result2 = buildSavingsFromPositions(sp);
-      return { data: result2, displayText: formatSavingsDisplay(result2) };
+      const stamped2 = { ...result2, address: targetAddress, isSelfQuery };
+      return { data: stamped2, displayText: formatSavingsDisplay(result2, isSelfQuery, targetAddress) };
     }
-    if (hasNaviMcp(context)) {
-      const savings = await fetchSavings(
-        getMcpManager(context),
-        getWalletAddress(context)
-      );
+    if (hasNaviMcpGlobal(context) && targetAddress) {
+      const savings = await fetchSavings(getMcpManager(context), targetAddress);
       savings.positions = savings.positions.filter((p) => p.valueUsd >= DUST_THRESHOLD_USD);
-      return { data: savings, displayText: formatSavingsDisplay(savings) };
+      const stamped2 = { ...savings, address: targetAddress, isSelfQuery };
+      return { data: stamped2, displayText: formatSavingsDisplay(savings, isSelfQuery, targetAddress) };
+    }
+    if (input.address && context.walletAddress && input.address.toLowerCase() !== context.walletAddress.toLowerCase()) {
+      throw new Error(
+        `Cannot inspect ${input.address.slice(0, 8)}\u2026 without NAVI MCP or a positionFetcher. Configure NAVI MCP to enable third-party address reads.`
+      );
     }
     const agent = requireAgent(context);
     const [posResult, earnings, fundStatus] = await Promise.all([
@@ -1114,9 +1162,11 @@ var savingsInfoTool = buildTool({
         projectedMonthly: fundStatus.projectedMonthly
       }
     };
-    return { data: result, displayText: formatSavingsDisplay(result) };
+    const stamped = { ...result, address: targetAddress ?? "", isSelfQuery: true };
+    return { data: stamped, displayText: formatSavingsDisplay(result, true, void 0) };
   }
 });
+var SUI_ADDRESS_REGEX3 = /^0x[a-fA-F0-9]{1,64}$/;
 var DEBT_DUST_USD = 0.01;
 function hfStatus(hf, borrowed) {
   if (borrowed <= DEBT_DUST_USD) return "healthy";
@@ -1130,24 +1180,39 @@ function serializeHf(hf, borrowed) {
   if (hf == null || !Number.isFinite(hf)) return null;
   return hf;
 }
-function displayHfText(hf, borrowed, status) {
+function displayHfText(hf, borrowed, status, isSelfQuery = true, address) {
+  const subject = isSelfQuery || !address ? "Health Factor" : `Health Factor for ${address.slice(0, 6)}\u2026${address.slice(-4)}`;
   if (hf == null) {
-    return `Health Factor: \u221E (${status} \u2014 no debt)`;
+    return `${subject}: \u221E (${status} \u2014 no debt)`;
   }
-  return `Health Factor: ${hf.toFixed(2)} (${status})`;
+  return `${subject}: ${hf.toFixed(2)} (${status})`;
 }
 var healthCheckTool = buildTool({
   name: "health_check",
-  description: 'Check the lending health factor: current HF ratio, total supplied collateral, total borrowed, max additional borrow capacity, and liquidation threshold. HF < 1.5 is risky, < 1.2 is critical. When the user has no debt the tool returns healthFactor=null (semantically infinity) \u2014 render that as "Healthy" / \u221E, never as 0 or "Critical".',
-  inputSchema: z.object({}),
-  jsonSchema: { type: "object", properties: {}, required: [] },
+  description: 'Check the lending health factor for the signed-in user OR any public Sui address: current HF ratio, total supplied collateral, total borrowed, max additional borrow capacity, and liquidation threshold. HF < 1.5 is risky, < 1.2 is critical. When the address has no debt the tool returns healthFactor=null (semantically infinity) \u2014 render that as "Healthy" / \u221E, never as 0 or "Critical". Pass `address` to inspect a contact / watched / public wallet; defaults to the signed-in user when omitted.',
+  inputSchema: z.object({
+    address: z.string().regex(SUI_ADDRESS_REGEX3).optional().describe("Sui address to inspect (defaults to the signed-in wallet)")
+  }),
+  jsonSchema: {
+    type: "object",
+    properties: {
+      address: {
+        type: "string",
+        pattern: "^0x[a-fA-F0-9]{1,64}$",
+        description: "Sui address to inspect (defaults to the signed-in wallet)"
+      }
+    },
+    required: []
+  },
   isReadOnly: true,
   // [v1.5.1] Health factor changes on every borrow / repay / collateral
   // movement and even passively as oracle prices update. Never dedupe.
   cacheable: false,
-  async call(_input, context) {
-    if (context.positionFetcher && context.walletAddress) {
-      const sp = await context.positionFetcher(context.walletAddress);
+  async call(input, context) {
+    const targetAddress = input.address ?? context.walletAddress;
+    const isSelfQuery = !!context.walletAddress && !!targetAddress && targetAddress.toLowerCase() === context.walletAddress.toLowerCase();
+    if (context.positionFetcher && targetAddress) {
+      const sp = await context.positionFetcher(targetAddress);
       const borrowed2 = sp.borrows;
       const rawHf = sp.healthFactor ?? (borrowed2 > 0 ? 0 : Infinity);
       const status2 = hfStatus(rawHf, borrowed2);
@@ -1159,24 +1224,28 @@ var healthCheckTool = buildTool({
           borrowed: borrowed2,
           maxBorrow: sp.maxBorrow,
           liquidationThreshold: 0,
-          status: status2
+          status: status2,
+          address: targetAddress,
+          isSelfQuery
         },
-        displayText: displayHfText(transportHf2, borrowed2, status2)
+        displayText: displayHfText(transportHf2, borrowed2, status2, isSelfQuery, targetAddress)
       };
     }
-    if (hasNaviMcp(context)) {
-      const hf2 = await fetchHealthFactor(
-        getMcpManager(context),
-        getWalletAddress(context)
-      );
+    if (hasNaviMcpGlobal(context) && targetAddress) {
+      const hf2 = await fetchHealthFactor(getMcpManager(context), targetAddress);
       const borrowed2 = hf2.borrowed;
       const status2 = hfStatus(hf2.healthFactor, borrowed2);
       const transportHf2 = serializeHf(hf2.healthFactor, borrowed2);
       return {
-        data: { ...hf2, healthFactor: transportHf2, status: status2 },
-        displayText: displayHfText(transportHf2, borrowed2, status2)
+        data: { ...hf2, healthFactor: transportHf2, status: status2, address: targetAddress, isSelfQuery },
+        displayText: displayHfText(transportHf2, borrowed2, status2, isSelfQuery, targetAddress)
       };
     }
+    if (input.address && context.walletAddress && input.address.toLowerCase() !== context.walletAddress.toLowerCase()) {
+      throw new Error(
+        `Cannot inspect ${input.address.slice(0, 8)}\u2026 without NAVI MCP or a positionFetcher. Configure NAVI MCP to enable third-party address reads.`
+      );
+    }
     const agent = requireAgent(context);
     const hf = await agent.healthFactor();
     const borrowed = hf.borrowed;
@@ -1189,9 +1258,11 @@ var healthCheckTool = buildTool({
         borrowed,
         maxBorrow: hf.maxBorrow,
         liquidationThreshold: hf.liquidationThreshold,
-        status
+        status,
+        address: targetAddress ?? "",
+        isSelfQuery: true
       },
-      displayText: displayHfText(transportHf, borrowed, status)
+      displayText: displayHfText(transportHf, borrowed, status, true, void 0)
     };
   }
 });
@@ -1317,7 +1388,8 @@ function parseRpcTx(tx, address) {
     gasCost
   };
 }
-async function queryHistoryPage(rpcUrl, address, limit, cursor) {
+async function queryHistoryPage(rpcUrl, address, direction, limit, cursor) {
+  const filter = direction === "from" ? { FromAddress: address } : { ToAddress: address };
   const res = await fetch(rpcUrl, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -1326,7 +1398,7 @@ async function queryHistoryPage(rpcUrl, address, limit, cursor) {
       id: 1,
       method: "suix_queryTransactionBlocks",
       params: [
-        { filter: { FromAddress: address }, options: { showEffects: true, showInput: true, showBalanceChanges: true } },
+        { filter, options: { showEffects: true, showInput: true, showBalanceChanges: true } },
         cursor,
         limit,
         true
@@ -1343,9 +1415,20 @@ async function queryHistoryPage(rpcUrl, address, limit, cursor) {
     hasNextPage: json.result?.hasNextPage ?? false
   };
 }
+function mergeAndDedupe(a, b) {
+  const byDigest = /* @__PURE__ */ new Map();
+  for (const tx of [...a, ...b]) {
+    if (!byDigest.has(tx.digest)) byDigest.set(tx.digest, tx);
+  }
+  return [...byDigest.values()].sort((x, y) => Number(y.timestampMs ?? 0) - Number(x.timestampMs ?? 0));
+}
 async function queryHistoryRpc(rpcUrl, address, limit) {
-  const page = await queryHistoryPage(rpcUrl, address, limit, null);
-  return page.data.map((tx) => parseRpcTx(tx, address));
+  const [fromPage, toPage] = await Promise.all([
+    queryHistoryPage(rpcUrl, address, "from", limit, null).catch(() => ({ data: [], nextCursor: null, hasNextPage: false })),
+    queryHistoryPage(rpcUrl, address, "to", limit, null).catch(() => ({ data: [], nextCursor: null, hasNextPage: false }))
+  ]);
+  const merged = mergeAndDedupe(fromPage.data, toPage.data);
+  return merged.slice(0, limit).map((tx) => parseRpcTx(tx, address));
 }
 async function queryHistoryByDate(rpcUrl, address, targetDate, limit) {
   const target = new Date(targetDate);
@@ -1353,33 +1436,49 @@ async function queryHistoryByDate(rpcUrl, address, targetDate, limit) {
   const dayEnd = dayStart + 864e5;
   const MAX_PAGES = 20;
   const PAGE_SIZE = 50;
-  const results = [];
-  let cursor = null;
-  for (let page = 0; page < MAX_PAGES; page++) {
-    const res = await queryHistoryPage(rpcUrl, address, PAGE_SIZE, cursor);
-    if (res.data.length === 0) break;
-    for (const tx of res.data) {
-      const ts = Number(tx.timestampMs ?? 0);
-      if (ts === 0) continue;
-      if (ts < dayStart) {
-        return results.slice(0, limit);
+  async function paginateDirection(direction) {
+    const collected = [];
+    let cursor = null;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      let res;
+      try {
+        res = await queryHistoryPage(rpcUrl, address, direction, PAGE_SIZE, cursor);
+      } catch {
+        break;
       }
-      if (ts >= dayStart && ts < dayEnd) {
-        results.push(parseRpcTx(tx, address));
+      if (res.data.length === 0) break;
+      let reachedOld = false;
+      for (const tx of res.data) {
+        const ts = Number(tx.timestampMs ?? 0);
+        if (ts === 0) continue;
+        if (ts < dayStart) {
+          reachedOld = true;
+          break;
+        }
+        if (ts >= dayStart && ts < dayEnd) collected.push(tx);
       }
+      if (reachedOld || !res.hasNextPage || !res.nextCursor) break;
+      cursor = res.nextCursor;
     }
-    if (!res.hasNextPage || !res.nextCursor) break;
-    cursor = res.nextCursor;
+    return collected;
   }
-  return results.slice(0, limit);
+  const [fromTxs, toTxs] = await Promise.all([
+    paginateDirection("from"),
+    paginateDirection("to")
+  ]);
+  const merged = mergeAndDedupe(fromTxs, toTxs);
+  return merged.slice(0, limit).map((tx) => parseRpcTx(tx, address));
 }
 var HISTORY_ACTIONS = ["send", "lending", "swap", "transaction"];
 var DEFAULT_LOOKBACK_DAYS = 30;
+var SUI_ADDRESS_REGEX4 = /^0x[0-9a-fA-F]{64}$/;
 var transactionHistoryTool = buildTool({
   name: "transaction_history",
-  description: 'Retrieve recent transaction history (last 30 days by default): sends, saves, withdrawals, borrows, repayments, swaps, and rewards claims. Renders a rich transaction card. Filter args: `date` (YYYY-MM-DD), `action` (send/lending/swap), `minUsd` (minimum amount in USD \u2014 use this for "transactions over $X" instead of post-filtering), `assetSymbol` (e.g. "USDC", "SUI"), `direction` ("in" or "out"). The card itself respects all filters \u2014 never re-list the rows in narration.',
+  description: 'Retrieve recent transaction history (last 30 days by default): sends, saves, withdrawals, borrows, repayments, swaps, and rewards claims. Renders a rich transaction card.\n\nBy default, queries the SIGNED-IN USER\'S history. To inspect another wallet (a saved contact, a watched address, any public Sui address), pass `address` \u2014 e.g. user asks "show funkii\'s recent transactions" with funkii at 0x40cd\u20263e62, call with `address: "0x40cd\u20263e62"`. To filter the user\'s own history to a specific counterparty (user asks "show transactions WITH funkii"), pass `counterparty` \u2014 keeps the query rooted in the user\'s wallet but shows only rows where funkii is the recipient or sender.\n\nFilter args: `date` (YYYY-MM-DD), `action` (send/lending/swap), `minUsd` (minimum amount in USD \u2014 use this for "transactions over $X" instead of post-filtering), `assetSymbol` (e.g. "USDC", "SUI"), `direction` ("in" or "out"). The card itself respects all filters \u2014 never re-list the rows in narration.\n\nInternally queries both `FromAddress` and `ToAddress` filters in parallel and dedupes by digest, so pure-receive transactions (someone sends to the queried address with no balance-affecting outbound) are no longer dropped.',
   inputSchema: z.object({
     limit: z.number().int().min(1).max(50).optional(),
+    address: z.string().regex(SUI_ADDRESS_REGEX4, "Must be a 0x-prefixed 64-hex Sui address").optional().describe("Sui address to query history FOR. When omitted, defaults to the signed-in user's wallet. Pass this when the user asks about a contact's, watched address's, or any other public wallet's history."),
+    counterparty: z.string().regex(SUI_ADDRESS_REGEX4, "Must be a 0x-prefixed 64-hex Sui address").optional().describe('Sui address to filter rows by \u2014 only transactions where the queried address sent to or received from this counterparty are returned. Use for "show transactions with <contact>" queries. Compares against `tx.recipient` (case-insensitive).'),
     date: z.string().optional().describe("Specific date to search for transactions (YYYY-MM-DD format). Paginates back to find that day."),
     action: z.enum(HISTORY_ACTIONS).optional().describe("Filter by action: send, lending, swap, or transaction."),
     minUsd: z.number().min(0).optional().describe('Minimum transaction amount in USD. Use this for "transactions over $X" \u2014 the amount is converted to USD using the asset price snapshot.'),
@@ -1393,6 +1492,14 @@ var transactionHistoryTool = buildTool({
         type: "number",
         description: "Maximum number of transactions to return (1-50, default 10)"
       },
+      address: {
+        type: "string",
+        description: "Sui address to query history FOR (defaults to the signed-in user when omitted). Use for queries about a contact's, watched address's, or any other wallet's history."
+      },
+      counterparty: {
+        type: "string",
+        description: 'Sui address to filter rows by \u2014 only transactions where the queried address sent to or received from this counterparty are returned. Use for "show transactions with <contact>" queries.'
+      },
       date: {
         type: "string",
         description: "Specific date to search for transactions (YYYY-MM-DD format). Paginates back to find that day."
@@ -1465,6 +1572,9 @@ var transactionHistoryTool = buildTool({
     const assetSymbol = input.assetSymbol?.toLowerCase();
     const direction = input.direction;
     const minUsd = input.minUsd;
+    const counterpartyLower = input.counterparty?.toLowerCase();
+    const targetAddress = input.address ?? context.walletAddress;
+    const isSelfQuery = !!targetAddress && !!context.walletAddress && targetAddress.toLowerCase() === context.walletAddress.toLowerCase();
     const prices = context.tokenPrices;
     const priceFor = (sym) => {
       if (!sym || !prices) return void 0;
@@ -1479,6 +1589,9 @@ var transactionHistoryTool = buildTool({
       if (direction) {
         scoped = scoped.filter((r) => r.direction === direction);
       }
+      if (counterpartyLower) {
+        scoped = scoped.filter((r) => r.recipient?.toLowerCase() === counterpartyLower);
+      }
       if (minUsd != null && minUsd > 0) {
         scoped = scoped.filter((r) => {
           if (r.amount == null) return false;
@@ -1496,9 +1609,17 @@ var transactionHistoryTool = buildTool({
       action: action ?? null,
       minUsd: minUsd ?? null,
       assetSymbol: input.assetSymbol ?? null,
-      direction: direction ?? null
+      direction: direction ?? null,
+      counterparty: input.counterparty ?? null,
+      address: targetAddress ?? null,
+      isSelfQuery
     };
     if (context.agent) {
+      if (input.address && !isSelfQuery) {
+        throw new Error(
+          "transaction_history `address` parameter is not supported in CLI/SDK agent mode \u2014 only the signed-in user's history is available. Use the web client for third-party address queries."
+        );
+      }
       const agent = requireAgent(context);
       const records2 = await agent.history({ limit: input.date ? limit : Math.max(limit * 4, 50) });
       const filtered2 = finalize(records2);
@@ -1507,13 +1628,13 @@ var transactionHistoryTool = buildTool({
         displayText: `${filtered2.length} recent transaction(s)`
       };
     }
-    if (!context.walletAddress || !context.suiRpcUrl) {
+    if (!targetAddress || !context.suiRpcUrl) {
       throw new Error("Transaction history requires a wallet address");
     }
     if (input.date) {
       const records2 = await queryHistoryByDate(
         context.suiRpcUrl,
-        context.walletAddress,
+        targetAddress,
         input.date,
         Math.max(limit * 4, 50)
       );
@@ -1527,7 +1648,7 @@ var transactionHistoryTool = buildTool({
     const cutoffMs = Date.now() - DEFAULT_LOOKBACK_DAYS * 864e5;
     const records = await queryHistoryRpc(
       context.suiRpcUrl,
-      context.walletAddress,
+      targetAddress,
       Math.max(limit * 4, 50)
     );
     const recent = records.filter((r) => r.timestamp >= cutoffMs);
@@ -2976,21 +3097,25 @@ var renderCanvasTool = buildTool({
 
 Use when the user asks for a visual chart, simulator, or financial overview. Pick the most relevant template:
 
-- activity_heatmap \u2014 on-chain transaction history as a GitHub-style heatmap (WORKS NOW \u2014 loads from wallet)
-- portfolio_timeline \u2014 net worth over time, wallet/savings/debt breakdown (WORKS NOW \u2014 daily snapshots)
-- yield_projector \u2014 compound yield simulator with amount/APY/period sliders (WORKS NOW \u2014 client-side)
-- health_simulator \u2014 borrow health factor simulator with collateral/debt sliders (WORKS NOW \u2014 uses current position)
-- dca_planner \u2014 savings plan curve for regular monthly deposits (WORKS NOW \u2014 client-side)
-- spending_breakdown \u2014 spending by service category (WORKS NOW \u2014 from AppEvent + ServicePurchase)
-- watch_address \u2014 portfolio overview for any public Sui address (WORKS NOW \u2014 pass address in params)
-- full_portfolio \u2014 4-panel overview: savings, health, activity, spending (WORKS NOW \u2014 aggregates all data)
+- activity_heatmap \u2014 on-chain transaction history as a GitHub-style heatmap (WORKS NOW \u2014 accepts \`params.address\` to inspect any public Sui wallet; defaults to the signed-in user)
+- portfolio_timeline \u2014 net worth over time, wallet/savings/debt breakdown (WORKS NOW \u2014 accepts \`params.address\` for any public wallet; defaults to the signed-in user)
+- yield_projector \u2014 compound yield simulator with amount/APY/period sliders (WORKS NOW \u2014 client-side, no address needed)
+- health_simulator \u2014 borrow health factor simulator with collateral/debt sliders (WORKS NOW \u2014 accepts \`params.address\` for any public wallet; defaults to the signed-in user's current position)
+- dca_planner \u2014 savings plan curve for regular monthly deposits (WORKS NOW \u2014 client-side, no address needed)
+- spending_breakdown \u2014 spending by service category (WORKS NOW \u2014 accepts \`params.address\` for any public wallet; defaults to the signed-in user)
+- watch_address \u2014 portfolio overview for any public Sui address (WORKS NOW \u2014 pass \`params.address\`)
+- full_portfolio \u2014 4-panel overview: savings, health, activity, spending (WORKS NOW \u2014 accepts \`params.address\` for any public wallet; defaults to the signed-in user)
+
+When the user asks to inspect a saved contact or watched address \u2014 e.g. "show funkii's activity heatmap", "what's funkii's portfolio look like", "spending breakdown for 0x40cd\u2026", "give me a full portfolio overview of 0x40cd\u2026" \u2014 pass that wallet's address as \`params.address\`. Six of the eight templates (activity_heatmap, portfolio_timeline, spending_breakdown, watch_address, health_simulator, full_portfolio) will scope their data fetch to that address; only the pure client-side simulators (yield_projector, dca_planner) ignore params.address.
 
 Always prefer the canvas for visualisation requests. After rendering, offer to explain what the user sees.`,
   inputSchema: z.object({
     template: z.enum(CANVAS_TEMPLATES).describe("Which canvas template to render"),
     params: z.object({
       period: z.enum(["1m", "3m", "6m", "1y"]).optional().describe("Time period for time-based templates"),
-      address: z.string().optional().describe("Sui address for watch_address template")
+      address: z.string().optional().describe(
+        "Sui address for the six address-aware templates (activity_heatmap, portfolio_timeline, spending_breakdown, watch_address, health_simulator, full_portfolio). Defaults to the signed-in user; pass an explicit address to inspect a contact, watched wallet, or any other public address."
+      )
     }).optional()
   }),
   jsonSchema: {
@@ -3015,8 +3140,28 @@ Always prefer the canvas for visualisation requests. After rendering, offer to e
   async call(input, context) {
     const { template, params } = input;
     const title = CANVAS_TITLES[template];
+    const resolveAddressTarget = () => {
+      const fromParams = params?.address;
+      const fromContext = context.walletAddress;
+      const target = fromParams ?? fromContext ?? null;
+      const isSelfRender = !!target && !!fromContext && target.toLowerCase() === fromContext.toLowerCase();
+      return { address: target, isSelfRender };
+    };
     if (template === "full_portfolio") {
-      const pos = context.serverPositions;
+      const { address, isSelfRender } = resolveAddressTarget();
+      if (!address) {
+        return {
+          data: {
+            __canvas: true,
+            template,
+            title,
+            templateData: { available: false, message: "Full Portfolio needs an address." }
+          },
+          displayText: "Full Portfolio requires an address."
+        };
+      }
+      const titleSuffix = isSelfRender ? "" : ` \u2014 ${address.slice(0, 6)}\u2026${address.slice(-4)}`;
+      const pos = isSelfRender ? context.serverPositions : null;
       const rate = normalizeSavingsRate(pos?.savingsRate);
       const savings = pos?.savings ?? 0;
       const borrows = pos?.borrows ?? 0;
@@ -3024,17 +3169,18 @@ Always prefer the canvas for visualisation requests. After rendering, offer to e
         data: {
           __canvas: true,
           template,
-          title,
+          title: `${title}${titleSuffix}`,
           templateData: {
             available: true,
-            address: context.walletAddress ?? "",
+            address,
+            isSelfRender,
             currentSavings: savings,
             currentDebt: borrows,
             healthFactor: pos?.healthFactor ?? null,
             savingsRate: rate
           }
         },
-        displayText: `Opened Full Portfolio Overview.`
+        displayText: isSelfRender ? `Opened Full Portfolio Overview.` : `Opened Full Portfolio Overview for ${address.slice(0, 6)}\u2026${address.slice(-4)}.`
       };
     }
     if (template === "watch_address") {
@@ -3061,45 +3207,87 @@ Always prefer the canvas for visualisation requests. After rendering, offer to e
       };
     }
     if (template === "portfolio_timeline") {
+      const { address, isSelfRender } = resolveAddressTarget();
+      if (!address) {
+        return {
+          data: {
+            __canvas: true,
+            template,
+            title,
+            templateData: { available: false, message: "Portfolio Timeline needs an address." }
+          },
+          displayText: "Portfolio Timeline requires an address."
+        };
+      }
+      const titleSuffix = isSelfRender ? "" : ` \u2014 ${address.slice(0, 6)}\u2026${address.slice(-4)}`;
       return {
         data: {
           __canvas: true,
           template,
-          title,
+          title: `${title}${titleSuffix}`,
           templateData: {
             available: true,
-            address: context.walletAddress ?? ""
+            address,
+            isSelfRender
           }
         },
-        displayText: `Opened Portfolio Timeline. Shows your net worth, savings, and debt over time.`
+        displayText: isSelfRender ? `Opened Portfolio Timeline. Shows your net worth, savings, and debt over time.` : `Opened Portfolio Timeline for ${address.slice(0, 6)}\u2026${address.slice(-4)}.`
       };
     }
     if (template === "spending_breakdown") {
+      const { address, isSelfRender } = resolveAddressTarget();
+      if (!address) {
+        return {
+          data: {
+            __canvas: true,
+            template,
+            title,
+            templateData: { available: false, message: "Spending Breakdown needs an address." }
+          },
+          displayText: "Spending Breakdown requires an address."
+        };
+      }
+      const titleSuffix = isSelfRender ? "" : ` \u2014 ${address.slice(0, 6)}\u2026${address.slice(-4)}`;
       return {
         data: {
           __canvas: true,
           template,
-          title,
+          title: `${title}${titleSuffix}`,
           templateData: {
             available: true,
-            address: context.walletAddress ?? ""
+            address,
+            isSelfRender
           }
         },
-        displayText: `Opened Spending Breakdown. Shows your service spending by category.`
+        displayText: isSelfRender ? `Opened Spending Breakdown. Shows your service spending by category.` : `Opened Spending Breakdown for ${address.slice(0, 6)}\u2026${address.slice(-4)}.`
       };
     }
     if (template === "activity_heatmap") {
+      const { address, isSelfRender } = resolveAddressTarget();
+      if (!address) {
+        return {
+          data: {
+            __canvas: true,
+            template,
+            title,
+            templateData: { available: false, message: "Activity Heatmap needs an address." }
+          },
+          displayText: "Activity Heatmap requires an address."
+        };
+      }
+      const titleSuffix = isSelfRender ? "" : ` \u2014 ${address.slice(0, 6)}\u2026${address.slice(-4)}`;
       return {
         data: {
           __canvas: true,
           template,
-          title,
+          title: `${title}${titleSuffix}`,
           templateData: {
             available: true,
-            address: context.walletAddress ?? ""
+            address,
+            isSelfRender
           }
         },
-        displayText: `Opened Activity Heatmap for your wallet. Click any day to explore transactions.`
+        displayText: isSelfRender ? `Opened Activity Heatmap for your wallet. Click any day to explore transactions.` : `Opened Activity Heatmap for ${address.slice(0, 6)}\u2026${address.slice(-4)}. Click any day to explore that address's transactions.`
       };
     }
     const positions = context.serverPositions;
@@ -3123,20 +3311,28 @@ Always prefer the canvas for visualisation requests. After rendering, offer to e
       };
     }
     if (template === "health_simulator") {
-      const roundedDebt = totalBorrows >= 1 ? Math.round(totalBorrows) : totalBorrows > 0 ? parseFloat(totalBorrows.toFixed(4)) : 0;
+      const { address: targetAddress, isSelfRender } = resolveAddressTarget();
+      const seedFromPos = isSelfRender;
+      const seedSavings = seedFromPos ? totalSavings : 0;
+      const seedBorrows = seedFromPos ? totalBorrows : 0;
+      const seedHf = seedFromPos ? healthFactor : null;
+      const roundedDebt = seedBorrows >= 1 ? Math.round(seedBorrows) : seedBorrows > 0 ? parseFloat(seedBorrows.toFixed(4)) : 0;
+      const titleSuffix = !targetAddress || isSelfRender ? "" : ` \u2014 ${targetAddress.slice(0, 6)}\u2026${targetAddress.slice(-4)}`;
       return {
         data: {
           __canvas: true,
           template,
-          title,
+          title: `${title}${titleSuffix}`,
           templateData: {
             available: true,
-            initialCollateral: totalSavings > 0 ? Math.round(totalSavings) : 1500,
-            initialDebt: roundedDebt > 0 ? roundedDebt : totalSavings > 0 ? 0 : 500,
-            currentHf: healthFactor
+            address: targetAddress ?? "",
+            isSelfRender,
+            initialCollateral: seedSavings > 0 ? Math.round(seedSavings) : 1500,
+            initialDebt: roundedDebt > 0 ? roundedDebt : seedSavings > 0 ? 0 : 500,
+            currentHf: seedHf
           }
         },
-        displayText: `Opened Health Factor Simulator. Current HF: ${healthFactor !== null ? healthFactor.toFixed(2) : "no active position"}.`
+        displayText: isSelfRender ? `Opened Health Factor Simulator. Current HF: ${healthFactor !== null ? healthFactor.toFixed(2) : "no active position"}.` : `Opened Health Factor Simulator${titleSuffix}. The simulator will fetch the current health factor for that wallet.`
       };
     }
     if (template === "dca_planner") {
@@ -3251,49 +3447,62 @@ var yieldSummaryTool = buildTool({
     }
   }
 });
+var SUI_ADDRESS_REGEX5 = /^0x[a-fA-F0-9]{1,64}$/;
 var activitySummaryTool = buildTool({
   name: "activity_summary",
-  description: "Returns a categorised DeFi activity summary for a period: transaction count, breakdown by action type (saves, sends, borrows, repayments, swaps, payments), total moved, net savings change, and yield earned. Use when the user asks about their activity, transaction history summary, or what they have done recently.",
+  description: "Returns a categorised DeFi activity summary for the signed-in user OR any public Sui address: transaction count, breakdown by action type (saves, sends, borrows, repayments, swaps, payments), total moved, net savings change, and yield earned. Use when the user asks about activity, transaction history summary, or what someone has done recently. Pass `address` to inspect a contact / watched / public wallet; defaults to the signed-in user when omitted.",
   inputSchema: z.object({
-    period: z.enum(["week", "month", "year", "all"]).optional().describe("Time period. Defaults to current month.")
+    period: z.enum(["week", "month", "year", "all"]).optional().describe("Time period. Defaults to current month."),
+    address: z.string().regex(SUI_ADDRESS_REGEX5).optional().describe("Sui address to inspect (defaults to the signed-in wallet)")
   }),
   jsonSchema: {
     type: "object",
     properties: {
-      period: { type: "string", enum: ["week", "month", "year", "all"] }
+      period: { type: "string", enum: ["week", "month", "year", "all"] },
+      address: {
+        type: "string",
+        pattern: "^0x[a-fA-F0-9]{1,64}$",
+        description: "Sui address to inspect (defaults to the signed-in wallet)"
+      }
     }
   },
   isReadOnly: true,
   async call(input, context) {
     const period = input.period ?? "month";
     const apiUrl = context.env?.AUDRIC_INTERNAL_API_URL;
-    const address = context.walletAddress;
+    const targetAddress = input.address ?? context.walletAddress;
+    const isSelfQuery = !!context.walletAddress && !!targetAddress && targetAddress.toLowerCase() === context.walletAddress.toLowerCase();
     const empty = {
       period,
       totalTransactions: 0,
       byAction: [],
       totalMovedUsd: 0,
       netSavingsUsd: 0,
-      yieldEarnedUsd: 0
+      yieldEarnedUsd: 0,
+      address: targetAddress,
+      isSelfQuery
     };
-    if (!apiUrl || !address) {
+    if (!apiUrl || !targetAddress) {
       return { data: empty, displayText: "Activity summary not available." };
     }
     try {
+      const callerHeader = context.walletAddress ?? targetAddress;
       const res = await fetch(
-        `${apiUrl}/api/analytics/activity-summary?address=${address}&period=${period}`,
-        { headers: { "x-sui-address": address }, signal: context.signal }
+        `${apiUrl}/api/analytics/activity-summary?address=${targetAddress}&period=${period}`,
+        { headers: { "x-sui-address": callerHeader }, signal: context.signal }
       );
       if (!res.ok) {
         return { data: empty, displayText: `Could not fetch activity data (HTTP ${res.status}).` };
       }
-      const data = await res.json();
+      const raw = await res.json();
+      const data = { ...raw, address: targetAddress, isSelfQuery };
       const sorted = [...data.byAction ?? []].sort((a, b) => b.count - a.count);
       const top = sorted.slice(0, 3).map((a) => `${a.action} (${a.count})`).join(", ");
       const periodLabel = data.period === "all" ? "all time" : `this ${data.period}`;
+      const subjectPrefix = isSelfQuery ? "" : `${targetAddress.slice(0, 6)}\u2026${targetAddress.slice(-4)} \u2014 `;
       return {
         data,
-        displayText: data.totalTransactions > 0 ? `${data.totalTransactions} transactions ${periodLabel}. Top: ${top}. Total moved: $${data.totalMovedUsd.toFixed(2)}. Net savings: $${data.netSavingsUsd.toFixed(2)}.` : `No activity recorded for ${periodLabel}.`
+        displayText: data.totalTransactions > 0 ? `${subjectPrefix}${data.totalTransactions} transactions ${periodLabel}. Top: ${top}. Total moved: $${data.totalMovedUsd.toFixed(2)}. Net savings: $${data.netSavingsUsd.toFixed(2)}.` : `${subjectPrefix}No activity recorded for ${periodLabel}.`
       };
     } catch {
       return { data: empty, displayText: "Error fetching activity summary." };
@@ -3770,7 +3979,7 @@ function guardCostWarning(tool, _call, conversationText) {
     message: "This action has a monetary cost. Confirm the user is aware before proceeding."
   };
 }
-var SUI_ADDRESS_REGEX = /^0x[a-fA-F0-9]{64}$/;
+var SUI_ADDRESS_REGEX6 = /^0x[a-fA-F0-9]{64}$/;
 function normalizeAddress(addr) {
   return addr.trim().toLowerCase();
 }
@@ -3835,7 +4044,7 @@ function guardAddressSource(tool, call, userText, contacts, walletAddress) {
   if (!rawTo) {
     return { verdict: "pass", gate: "address_source", tier: "safety" };
   }
-  if (!SUI_ADDRESS_REGEX.test(rawTo)) {
+  if (!SUI_ADDRESS_REGEX6.test(rawTo)) {
     return { verdict: "pass", gate: "address_source", tier: "safety" };
   }
   const normalizedTo = normalizeAddress(rawTo);