@t2000/engine 0.47.1 → 0.48.0

package/dist/index.d.ts

@@ -1990,8 +1990,10 @@ declare const ratesInfoTool: Tool<{
 declare const transactionHistoryTool: Tool<{
     action?: "send" | "swap" | "transaction" | "lending" | undefined;
     date?: string | undefined;
+    address?: string | undefined;
     direction?: "out" | "in" | undefined;
     limit?: number | undefined;
+    counterparty?: string | undefined;
     minUsd?: number | undefined;
     assetSymbol?: string | undefined;
 }, Record<string, unknown>>;

package/dist/index.js

@@ -1317,7 +1317,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 +1327,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 +1344,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 +1365,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_REGEX = /^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_REGEX, "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_REGEX, "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 +1421,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 +1501,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 +1518,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 +1538,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 +1557,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 +1577,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 +3026,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)
+- 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)
 - 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)
+- 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 aggregates all data)
 
+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" \u2014 pass that wallet's address as \`params.address\`. The four address-aware templates (activity_heatmap, portfolio_timeline, spending_breakdown, watch_address) will scope their data fetch to that address; the rest target the signed-in user regardless of params.
+
 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 four address-aware templates (activity_heatmap, portfolio_timeline, spending_breakdown, watch_address). Defaults to the signed-in user; pass an explicit address to inspect a contact, watched wallet, or any other public address."
+      )
     }).optional()
   }),
   jsonSchema: {
@@ -3015,6 +3069,13 @@ 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 rate = normalizeSavingsRate(pos?.savingsRate);
@@ -3061,45 +3122,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;
@@ -3770,7 +3873,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_REGEX2 = /^0x[a-fA-F0-9]{64}$/;
 function normalizeAddress(addr) {
   return addr.trim().toLowerCase();
 }
@@ -3835,7 +3938,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_REGEX2.test(rawTo)) {
     return { verdict: "pass", gate: "address_source", tier: "safety" };
   }
   const normalizedTo = normalizeAddress(rawTo);