@t2000/engine 0.46.12 → 0.46.14

package/dist/index.d.ts

@@ -236,6 +236,17 @@ interface GuardConfig {
      * tool would silently ship USDC. Default on.
      */
     assetIntent?: boolean;
+    /**
+     * Root-cause fix for "LLM hallucinates a stale training-data price
+     * (e.g. '$3.50/SUI') and shows the user a wildly wrong estimate before
+     * the swap card renders". When enabled (default), `swap_execute` is
+     * blocked unless a matching `swap_quote(from, to, amount)` ran in the
+     * recent past (60s window, ±1% amount tolerance). The block forces the
+     * LLM to fetch a real on-chain quote and cite its actual numbers, not
+     * a guess. Set to `false` only if the host has its own pre-execution
+     * quote requirement.
+     */
+    swapPreview?: boolean;
 }
 declare const DEFAULT_GUARD_CONFIG: GuardConfig;
 declare class BalanceTracker {
@@ -255,11 +266,39 @@ declare class RetryTracker {
         previousResult?: unknown;
     };
 }
+declare class SwapQuoteTracker {
+    /** Quotes recorded in the recent window. Trimmed lazily on every check. */
+    private quotes;
+    /** Match window: 60s is generous enough for slow LLM turns but tight enough
+     * to invalidate stale quotes from earlier in the session. */
+    private readonly windowMs;
+    /** Amount tolerance: ±1% (covers gas-padding, integer-rounding, and the
+     * rare case where the LLM rounds the input differently between quote and
+     * execute). Prices barely move in 60s so 1% is forgiving but meaningful. */
+    private readonly amountTolerance;
+    /**
+     * Normalize a token identifier so symbol vs. coinType vs. case don't
+     * cause spurious mismatches. Lowercase + trim is sufficient because the
+     * SDK's resolver itself is case-insensitive on symbols.
+     */
+    private normalize;
+    record(input: {
+        from: string;
+        to: string;
+        amount: number;
+    }): void;
+    hasMatchingQuote(input: {
+        from: string;
+        to: string;
+        amount: number;
+    }): boolean;
+}
 declare function guardArtifactPreview(result: unknown): GuardInjection | null;
 declare function guardStaleData(toolFlags: ToolFlags): GuardInjection | null;
 interface GuardRunnerState {
     balanceTracker: BalanceTracker;
     retryTracker: RetryTracker;
+    swapQuoteTracker: SwapQuoteTracker;
     lastHealthFactor: number | null;
 }
 declare function createGuardRunnerState(): GuardRunnerState;
@@ -1421,6 +1460,13 @@ declare class EarlyToolDispatcher {
     hasPending(): boolean;
     /** List of call IDs that were early-dispatched. */
     dispatchedIds(): Set<string>;
+    /**
+     * Look up the original tool input by `tool_use_id`. Used by the engine to
+     * feed `updateGuardStateAfterToolResult` (which needs the call input to
+     * record swap_quote → swap_execute pairing, etc.) for tools that were
+     * dispatched here instead of going through the normal post-stream loop.
+     */
+    getInputById(toolUseId: string): unknown | undefined;
     /**
      * Collect all results in original dispatch order.
      * Yields `tool_result` events as each promise resolves.

package/dist/index.js

@@ -3628,7 +3628,8 @@ var DEFAULT_GUARD_CONFIG = {
   retryProtection: true,
   inputValidation: true,
   addressSource: true,
-  assetIntent: true
+  assetIntent: true,
+  swapPreview: true
 };
 var BalanceTracker = class {
   lastBalanceAt = 0;
@@ -3669,6 +3670,45 @@ var RetryTracker = class {
     return { blocked: true, previousResult: prev.result };
   }
 };
+var SwapQuoteTracker = class {
+  /** Quotes recorded in the recent window. Trimmed lazily on every check. */
+  quotes = [];
+  /** Match window: 60s is generous enough for slow LLM turns but tight enough
+   * to invalidate stale quotes from earlier in the session. */
+  windowMs = 6e4;
+  /** Amount tolerance: ±1% (covers gas-padding, integer-rounding, and the
+   * rare case where the LLM rounds the input differently between quote and
+   * execute). Prices barely move in 60s so 1% is forgiving but meaningful. */
+  amountTolerance = 0.01;
+  /**
+   * Normalize a token identifier so symbol vs. coinType vs. case don't
+   * cause spurious mismatches. Lowercase + trim is sufficient because the
+   * SDK's resolver itself is case-insensitive on symbols.
+   */
+  normalize(token) {
+    return token.trim().toLowerCase();
+  }
+  record(input) {
+    const now = Date.now();
+    this.quotes.push({
+      from: this.normalize(input.from),
+      to: this.normalize(input.to),
+      amount: input.amount,
+      ts: now
+    });
+    const cutoff = now - this.windowMs;
+    this.quotes = this.quotes.filter((q) => q.ts > cutoff);
+  }
+  hasMatchingQuote(input) {
+    const cutoff = Date.now() - this.windowMs;
+    const fromN = this.normalize(input.from);
+    const toN = this.normalize(input.to);
+    const target = input.amount;
+    return this.quotes.some(
+      (q) => q.ts > cutoff && q.from === fromN && q.to === toN && target > 0 && Math.abs(q.amount - target) / target <= this.amountTolerance
+    );
+  }
+};
 function guardRetryProtection(tool, call, retryTracker) {
   const check = retryTracker.isBlocked(tool.name, call.input);
   if (check.blocked) {
@@ -3842,6 +3882,27 @@ function guardAssetIntent(tool, call, userText) {
     message: `Asset mismatch: the user's recent messages mention "${mentioned.symbol}" but send_transfer was called without an \`asset\` field (defaults to USDC). If the user asked you to send ${mentioned.symbol}, re-issue send_transfer with \`asset: "${mentioned.symbol}"\`. If the user really meant USDC, set \`asset: "USDC"\` explicitly to confirm intent. Never default to USDC when the user named a different token.`
   };
 }
+function guardSwapPreview(tool, call, swapQuoteTracker) {
+  if (tool.name !== "swap_execute") {
+    return { verdict: "pass", gate: "swap_preview", tier: "safety" };
+  }
+  const input = call.input;
+  const from = typeof input.from === "string" ? input.from : "";
+  const to = typeof input.to === "string" ? input.to : "";
+  const amount = Number(input.amount ?? 0);
+  if (!from || !to || !(amount > 0)) {
+    return { verdict: "pass", gate: "swap_preview", tier: "safety" };
+  }
+  if (swapQuoteTracker.hasMatchingQuote({ from, to, amount })) {
+    return { verdict: "pass", gate: "swap_preview", tier: "safety" };
+  }
+  return {
+    verdict: "block",
+    gate: "swap_preview",
+    tier: "safety",
+    message: `swap_execute requires a recent matching swap_quote so the user sees an accurate preview. Call swap_quote({ from: "${from}", to: "${to}", amount: ${amount} }) first, then re-issue swap_execute with the same params. swap_quote is read-only and returns the real on-chain output, route, and price impact \u2014 never estimate from memory.`
+  };
+}
 function guardAddressSource(tool, call, userText, contacts, walletAddress) {
   if (tool.name !== "send_transfer") {
     return { verdict: "pass", gate: "address_source", tier: "safety" };
@@ -3897,6 +3958,7 @@ function createGuardRunnerState() {
   return {
     balanceTracker: new BalanceTracker(),
     retryTracker: new RetryTracker(),
+    swapQuoteTracker: new SwapQuoteTracker(),
     lastHealthFactor: null
   };
 }
@@ -3955,6 +4017,9 @@ function runGuards(tool, call, state, config, conversationContext, onGuardFired,
   if (config.assetIntent !== false) {
     results.push(guardAssetIntent(tool, call, conversationContext.recentUserText));
   }
+  if (config.swapPreview !== false) {
+    results.push(guardSwapPreview(tool, call, state.swapQuoteTracker));
+  }
   if (config.irreversibility !== false) {
     results.push(guardIrreversibility(tool, call, conversationContext.fullText));
   }
@@ -4021,6 +4086,15 @@ function updateGuardStateAfterToolResult(toolName, tool, input, result, isError,
       state.lastHealthFactor = hf;
     }
   }
+  if (toolName === "swap_quote" && input && typeof input === "object") {
+    const i = input;
+    const from = typeof i.from === "string" ? i.from : "";
+    const to = typeof i.to === "string" ? i.to : "";
+    const amount = Number(i.amount ?? 0);
+    if (from && to && amount > 0) {
+      state.swapQuoteTracker.record({ from, to, amount });
+    }
+  }
   state.retryTracker.record(toolName, input, result);
 }
 function extractConversationText(messages) {
@@ -4534,6 +4608,15 @@ var EarlyToolDispatcher = class {
   dispatchedIds() {
     return new Set(this.entries.map((e) => e.call.id));
   }
+  /**
+   * Look up the original tool input by `tool_use_id`. Used by the engine to
+   * feed `updateGuardStateAfterToolResult` (which needs the call input to
+   * record swap_quote → swap_execute pairing, etc.) for tools that were
+   * dispatched here instead of going through the normal post-stream loop.
+   */
+  getInputById(toolUseId) {
+    return this.entries.find((e) => e.call.id === toolUseId)?.call.input;
+  }
   /**
    * Collect all results in original dispatch order.
    * Yields `tool_result` events as each promise resolves.
@@ -5089,10 +5172,11 @@ ${recipeCtx}`;
               }
             }
             const tool = findTool(this.tools, earlyEvent.toolName);
+            const earlyInput = dispatcher.getInputById(earlyEvent.toolUseId) ?? null;
             updateGuardStateAfterToolResult(
               earlyEvent.toolName,
               tool,
-              null,
+              earlyInput,
               earlyEvent.result,
               earlyEvent.isError,
               this.guardState