@t2000/engine 0.46.7 → 0.46.9

package/dist/index.d.ts

@@ -888,6 +888,8 @@ declare class QueryEngine {
     private messages;
     private abortController;
     private guardEvents;
+    private readonly turnReadCache;
+    private turnPaused;
     constructor(config: EngineConfig);
     /**
      * Submit a user message and stream engine events.
@@ -1241,6 +1243,89 @@ interface MicrocompactResult extends Array<Message> {
  */
 declare function microcompact(messages: readonly Message[], tools?: readonly Tool[]): MicrocompactResult;
 
+/**
+ * [v0.46.8] Intra-turn deduplication of read-only tool calls.
+ *
+ * # Problem
+ * Two independent execution paths can call the same read-only tool within
+ * the same user turn:
+ *   1. Host pre-dispatch via `engine.invokeReadTool()` (deterministic — runs
+ *      before the LLM ever sees the message; injects a synthetic
+ *      `tool_use`+`tool_result` pair into the ledger so the card renders
+ *      immediately and the LLM has the data).
+ *   2. The LLM itself, mid-turn, emitting a `tool_use` block for the same
+ *      tool (often because the prompt says "always call balance_check on
+ *      direct read questions" and the model doesn't trust the synthetic
+ *      pair).
+ *
+ * Both paths emit a `tool_result` SSE event, the host renders BOTH cards,
+ * the user sees a duplicate. Coordinating these two paths via prompt rules
+ * is probabilistic ("DO NOT re-call when you see a synthetic pair") and
+ * has empirically shown ~30% miss rate — the LLM still re-calls anyway.
+ *
+ * # Fix
+ * Idempotent intra-turn cache. Within one user turn:
+ *   - Calling the same read-only tool with the same args twice returns the
+ *     cached result on the second call.
+ *   - The second call yields a `tool_result` event with `resultDeduped:true`
+ *     so hosts can skip rendering a duplicate card while the LLM still gets
+ *     the data it needs to satisfy its `tool_use` id.
+ *
+ * # Lifecycle
+ *   - Cache lives on the `QueryEngine` instance.
+ *   - Populated by `invokeReadTool` (host pre-dispatch) AND by the agent
+ *     loop's tool-execution path (LLM-driven calls).
+ *   - Cleared on `turn_complete` (clean slate for the next user turn).
+ *   - Cleared whenever a WRITE tool executes successfully (writes mutate
+ *     on-chain state, so any subsequent read in the same turn must re-fetch
+ *     for freshness).
+ *   - Cleared on errors / abort (defensive cleanup).
+ *
+ * # Why not just extend microcompact?
+ * `microcompact` does CROSS-turn dedup, but explicitly excludes
+ * `cacheable: false` tools (balance_check, health_check, savings_info,
+ * transaction_history) so post-write refreshes always surface fresh data.
+ * Within a single turn (pre-write), those same tools are perfectly
+ * dedup-able — state can't change. This cache fills that exact gap.
+ *
+ * # Invariants
+ *   - Read-only tools only. Write tools never enter the cache.
+ *   - Errored results are NEVER cached (the next call should retry).
+ *   - Cache key includes the full input, stably stringified — different
+ *     filter args (e.g. `transaction_history({minUsd:5})` vs
+ *     `transaction_history({})`) hit different cache entries.
+ */
+declare class TurnReadCache {
+    private readonly store;
+    /**
+     * Build the cache key for a (toolName, input) pair. Stable across object
+     * key ordering so `{a:1,b:2}` and `{b:2,a:1}` map to the same entry.
+     */
+    static keyFor(toolName: string, input: unknown): string;
+    has(key: string): boolean;
+    get(key: string): {
+        result: unknown;
+        sourceToolUseId: string;
+    } | undefined;
+    /**
+     * Populate the cache. Caller is responsible for ensuring the result was
+     * a successful read (no errors). Overwrites any prior entry for the same
+     * key — the most recent successful read wins, which is correct under our
+     * "writes invalidate the whole cache" invariant.
+     */
+    set(key: string, value: {
+        result: unknown;
+        sourceToolUseId: string;
+    }): void;
+    /**
+     * Drop every entry. Called at turn end and after every successful write.
+     * Cheap and intentional — the cache is small (a handful of entries per
+     * turn at most) and clearing is the correct response to any state mutation.
+     */
+    clear(): void;
+    size(): number;
+}
+
 /**
  * EarlyToolDispatcher — dispatches read-only tools mid-stream.
  *
@@ -1257,11 +1342,21 @@ declare class EarlyToolDispatcher {
     private entries;
     private readonly tools;
     private readonly context;
+    private readonly turnReadCache;
     private abortController;
-    constructor(tools: Tool[], context: ToolContext);
+    constructor(tools: Tool[], context: ToolContext, turnReadCache?: TurnReadCache);
     /**
      * Attempt to dispatch a tool call. Returns true if the tool was dispatched
      * (read-only + concurrency-safe), false if it should be queued for later.
+     *
+     * [v0.46.8] Cache-aware: if a `TurnReadCache` was supplied at
+     * construction and a prior call this turn already produced a result
+     * for the same `(toolName, input)`, the dispatcher returns true (the
+     * call IS handled here, not queued for the post-stream loop) but
+     * skips the tool execution entirely — `collectResults` will surface
+     * the cached value with `resultDeduped: true`. On a cache miss for
+     * a successful real execution, the result is written back to the
+     * cache so any later call within the same turn dedups too.
      */
     tryDispatch(call: PendingToolCall): boolean;
     /** True if any tools have been dispatched. */
@@ -1662,7 +1757,7 @@ declare const balanceCheckTool: Tool<{}, {
 declare const savingsInfoTool: Tool<{}, SavingsResult>;
 
 declare const healthCheckTool: Tool<{}, {
-    healthFactor: number;
+    healthFactor: number | null;
     supplied: number;
     borrowed: number;
     maxBorrow: number;

package/dist/index.js

@@ -915,15 +915,28 @@ var savingsInfoTool = buildTool({
     return { data: result, displayText: formatSavingsDisplay(result) };
   }
 });
-function hfStatus(hf) {
+var DEBT_DUST_USD = 0.01;
+function hfStatus(hf, borrowed) {
+  if (borrowed <= DEBT_DUST_USD) return "healthy";
   if (hf >= 2) return "healthy";
   if (hf >= 1.5) return "moderate";
   if (hf >= 1.2) return "warning";
   return "critical";
 }
+function serializeHf(hf, borrowed) {
+  if (borrowed <= DEBT_DUST_USD) return null;
+  if (hf == null || !Number.isFinite(hf)) return null;
+  return hf;
+}
+function displayHfText(hf, borrowed, status) {
+  if (hf == null) {
+    return `Health Factor: \u221E (${status} \u2014 no debt)`;
+  }
+  return `Health Factor: ${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.",
+  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: [] },
   isReadOnly: true,
@@ -933,19 +946,20 @@ var healthCheckTool = buildTool({
   async call(_input, context) {
     if (context.positionFetcher && context.walletAddress) {
       const sp = await context.positionFetcher(context.walletAddress);
-      const hfVal = sp.healthFactor ?? (sp.borrows > 0 ? 0 : Infinity);
-      const status2 = hfStatus(hfVal);
-      const displayHf = Number.isFinite(hfVal) ? hfVal.toFixed(2) : "\u221E";
+      const borrowed2 = sp.borrows;
+      const rawHf = sp.healthFactor ?? (borrowed2 > 0 ? 0 : Infinity);
+      const status2 = hfStatus(rawHf, borrowed2);
+      const transportHf2 = serializeHf(rawHf, borrowed2);
       return {
         data: {
-          healthFactor: hfVal,
+          healthFactor: transportHf2,
           supplied: sp.savings,
-          borrowed: sp.borrows,
+          borrowed: borrowed2,
           maxBorrow: sp.maxBorrow,
           liquidationThreshold: 0,
           status: status2
         },
-        displayText: `Health Factor: ${displayHf} (${status2})`
+        displayText: displayHfText(transportHf2, borrowed2, status2)
       };
     }
     if (hasNaviMcp(context)) {
@@ -953,26 +967,29 @@ var healthCheckTool = buildTool({
         getMcpManager(context),
         getWalletAddress(context)
       );
-      const status2 = hfStatus(hf2.healthFactor);
-      const displayHf = Number.isFinite(hf2.healthFactor) ? hf2.healthFactor.toFixed(2) : "\u221E";
+      const borrowed2 = hf2.borrowed;
+      const status2 = hfStatus(hf2.healthFactor, borrowed2);
+      const transportHf2 = serializeHf(hf2.healthFactor, borrowed2);
       return {
-        data: { ...hf2, status: status2 },
-        displayText: `Health Factor: ${displayHf} (${status2})`
+        data: { ...hf2, healthFactor: transportHf2, status: status2 },
+        displayText: displayHfText(transportHf2, borrowed2, status2)
       };
     }
     const agent = requireAgent(context);
     const hf = await agent.healthFactor();
-    const status = hfStatus(hf.healthFactor);
+    const borrowed = hf.borrowed;
+    const status = hfStatus(hf.healthFactor, borrowed);
+    const transportHf = serializeHf(hf.healthFactor, borrowed);
     return {
       data: {
-        healthFactor: hf.healthFactor,
+        healthFactor: transportHf,
         supplied: hf.supplied,
-        borrowed: hf.borrowed,
+        borrowed,
         maxBorrow: hf.maxBorrow,
         liquidationThreshold: hf.liquidationThreshold,
         status
       },
-      displayText: `Health Factor: ${hf.healthFactor.toFixed(2)} (${status})`
+      displayText: displayHfText(transportHf, borrowed, status)
     };
   }
 });
@@ -1571,9 +1588,15 @@ var repayDebtTool = buildTool({
     };
   }
 });
+function formatAmount(amount) {
+  if (!Number.isFinite(amount) || amount <= 0) return "0";
+  if (amount >= 1) return amount.toFixed(4).replace(/\.?0+$/, "");
+  if (amount >= 1e-4) return amount.toFixed(6).replace(/\.?0+$/, "");
+  return amount.toExponential(2);
+}
 var claimRewardsTool = buildTool({
   name: "claim_rewards",
-  description: "Claim all pending protocol rewards across lending adapters. Returns claimed reward details and total USD value.",
+  description: 'Claim all pending protocol rewards across lending adapters. Returns the claimed reward breakdown (per-asset symbol + amount), total USD value (best effort \u2014 may be 0 when oracle prices are unavailable), and the on-chain tx hash. When the rewards list is empty the response will explicitly say "no pending rewards"; when it is non-empty narrate the per-symbol amounts even if totalValueUsd is 0 (the on-chain credit still happened).',
   inputSchema: z.object({}),
   jsonSchema: { type: "object", properties: {}, required: [] },
   isReadOnly: false,
@@ -1582,15 +1605,36 @@ var claimRewardsTool = buildTool({
   async call(_input, context) {
     const agent = requireAgent(context);
     const result = await agent.claimRewards();
+    const priceCache = context.priceCache;
+    const enrichedRewards = result.rewards.map((r) => {
+      if (r.estimatedValueUsd > 0) return r;
+      const price = priceCache?.get(r.symbol.toUpperCase());
+      if (!price || !Number.isFinite(price) || price <= 0) return r;
+      return { ...r, estimatedValueUsd: r.amount * price };
+    });
+    const totalValueUsd = enrichedRewards.reduce(
+      (s, r) => s + (Number.isFinite(r.estimatedValueUsd) ? r.estimatedValueUsd : 0),
+      0
+    );
+    const txShort = result.tx ? `${result.tx.slice(0, 8)}\u2026` : "";
+    let displayText;
+    if (enrichedRewards.length === 0) {
+      displayText = "No pending rewards to claim.";
+    } else {
+      const breakdown = enrichedRewards.map((r) => `${formatAmount(r.amount)} ${r.symbol}`).join(", ");
+      const usdSuffix = totalValueUsd > 0 ? ` (~$${totalValueUsd.toFixed(2)})` : "";
+      const txSuffix = txShort ? ` (tx: ${txShort})` : "";
+      displayText = `Claimed ${breakdown}${usdSuffix}${txSuffix}`;
+    }
     return {
       data: {
         success: result.success,
         tx: result.tx || null,
-        rewards: result.rewards,
-        totalValueUsd: result.totalValueUsd,
+        rewards: enrichedRewards,
+        totalValueUsd,
         gasCost: result.gasCost
       },
-      displayText: result.rewards.length === 0 ? "No pending rewards to claim." : `Claimed $${result.totalValueUsd.toFixed(2)} in rewards (tx: ${result.tx.slice(0, 8)}\u2026)`
+      displayText
     };
   }
 });
@@ -4257,27 +4301,116 @@ function safeNum(v) {
   return isNaN(n) ? 0 : n;
 }
 
+// src/turn-read-cache.ts
+var TurnReadCache = class {
+  store = /* @__PURE__ */ new Map();
+  /**
+   * Build the cache key for a (toolName, input) pair. Stable across object
+   * key ordering so `{a:1,b:2}` and `{b:2,a:1}` map to the same entry.
+   */
+  static keyFor(toolName, input) {
+    return `${toolName}:${stableStringify2(input)}`;
+  }
+  has(key) {
+    return this.store.has(key);
+  }
+  get(key) {
+    return this.store.get(key);
+  }
+  /**
+   * Populate the cache. Caller is responsible for ensuring the result was
+   * a successful read (no errors). Overwrites any prior entry for the same
+   * key — the most recent successful read wins, which is correct under our
+   * "writes invalidate the whole cache" invariant.
+   */
+  set(key, value) {
+    this.store.set(key, value);
+  }
+  /**
+   * Drop every entry. Called at turn end and after every successful write.
+   * Cheap and intentional — the cache is small (a handful of entries per
+   * turn at most) and clearing is the correct response to any state mutation.
+   */
+  clear() {
+    this.store.clear();
+  }
+  size() {
+    return this.store.size;
+  }
+};
+function stableStringify2(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return JSON.stringify(value.map(stableStringifyForObject));
+  return stableStringifyForObject(value);
+}
+function stableStringifyForObject(value) {
+  if (value === null || value === void 0) return JSON.stringify(value);
+  if (typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringifyForObject).join(",")}]`;
+  }
+  const sorted = Object.keys(value).sort();
+  const parts = sorted.map(
+    (k) => `${JSON.stringify(k)}:${stableStringifyForObject(value[k])}`
+  );
+  return `{${parts.join(",")}}`;
+}
+
 // src/early-dispatcher.ts
 var EarlyToolDispatcher = class {
   entries = [];
   tools;
   context;
+  turnReadCache;
   abortController;
-  constructor(tools, context) {
+  constructor(tools, context, turnReadCache) {
     this.tools = tools;
     this.context = context;
+    this.turnReadCache = turnReadCache;
     this.abortController = new AbortController();
   }
   /**
    * Attempt to dispatch a tool call. Returns true if the tool was dispatched
    * (read-only + concurrency-safe), false if it should be queued for later.
+   *
+   * [v0.46.8] Cache-aware: if a `TurnReadCache` was supplied at
+   * construction and a prior call this turn already produced a result
+   * for the same `(toolName, input)`, the dispatcher returns true (the
+   * call IS handled here, not queued for the post-stream loop) but
+   * skips the tool execution entirely — `collectResults` will surface
+   * the cached value with `resultDeduped: true`. On a cache miss for
+   * a successful real execution, the result is written back to the
+   * cache so any later call within the same turn dedups too.
    */
   tryDispatch(call) {
     const tool = findTool(this.tools, call.name);
     if (!tool || !tool.isReadOnly || !tool.isConcurrencySafe) return false;
+    if (this.turnReadCache) {
+      const cacheKey = TurnReadCache.keyFor(call.name, call.input);
+      const cached = this.turnReadCache.get(cacheKey);
+      if (cached) {
+        this.entries.push({
+          call,
+          tool,
+          promise: Promise.resolve({ data: cached.result, isError: false }),
+          deduped: true
+        });
+        return true;
+      }
+    }
     const childContext = { ...this.context, signal: this.abortController.signal };
-    const promise = executeTool(tool, call, childContext);
-    this.entries.push({ call, tool, promise });
+    const promise = executeTool(tool, call, childContext).then((result) => {
+      if (!result.isError && this.turnReadCache) {
+        const cacheKey = TurnReadCache.keyFor(call.name, call.input);
+        this.turnReadCache.set(cacheKey, {
+          result: result.data,
+          sourceToolUseId: call.id
+        });
+      }
+      return result;
+    });
+    this.entries.push({ call, tool, promise, deduped: false });
     return true;
   }
   /** True if any tools have been dispatched. */
@@ -4303,7 +4436,8 @@ var EarlyToolDispatcher = class {
           toolUseId: entry.call.id,
           result: budgeted,
           isError: result.isError,
-          wasEarlyDispatched: true
+          wasEarlyDispatched: true,
+          ...entry.deduped ? { resultDeduped: true } : {}
         };
       } catch (err) {
         yield {
@@ -4375,6 +4509,18 @@ var QueryEngine = class {
   messages = [];
   abortController = null;
   guardEvents = [];
+  // [v0.46.8] Intra-turn dedup cache for read-only tool calls. See
+  // `turn-read-cache.ts` for the full lifecycle. Key takeaway: the cache
+  // lives across the host's pre-dispatch (`invokeReadTool`) and the
+  // agent loop's LLM-driven tool execution within ONE user turn, then
+  // clears on `turn_complete` or after any successful write.
+  turnReadCache = new TurnReadCache();
+  // [v0.46.8] Set to `true` when the agent loop yields `pending_action`
+  // and returns (turn is paused awaiting user confirmation). The
+  // submitMessage / resumeWithToolResult wrappers consult this flag in
+  // their `finally` block so they DON'T clear the cache mid-turn — the
+  // pending write may resume, and the cache should survive the pause.
+  turnPaused = false;
   constructor(config) {
     this.provider = config.provider;
     this.agent = config.agent;
@@ -4426,7 +4572,14 @@ var QueryEngine = class {
       role: "user",
       content: [{ type: "text", text: prompt }]
     });
-    yield* this.agentLoop(prompt, signal);
+    this.turnPaused = false;
+    try {
+      yield* this.agentLoop(prompt, signal);
+    } finally {
+      if (!this.turnPaused) {
+        this.turnReadCache.clear();
+      }
+    }
   }
   /**
    * Resume the conversation after a pending action is resolved.
@@ -4470,10 +4623,19 @@ var QueryEngine = class {
     };
     if (!response.approved) {
       yield { type: "turn_complete", stopReason: "end_turn" };
+      this.turnReadCache.clear();
       return;
     }
+    this.turnReadCache.clear();
     yield* this.runPostWriteRefresh(action, response, signal);
-    yield* this.agentLoop(null, signal, false);
+    this.turnPaused = false;
+    try {
+      yield* this.agentLoop(null, signal, false);
+    } finally {
+      if (!this.turnPaused) {
+        this.turnReadCache.clear();
+      }
+    }
   }
   /**
    * [v1.5] Auto-run configured read tools after a successful write,
@@ -4552,6 +4714,12 @@ var QueryEngine = class {
     }));
     this.messages.push({ role: "user", content: refreshResults });
     for (const r of refreshes) {
+      if (!r.isError) {
+        this.turnReadCache.set(
+          TurnReadCache.keyFor(r.tool.name, {}),
+          { result: r.data, sourceToolUseId: r.id }
+        );
+      }
       yield {
         type: "tool_result",
         toolName: r.tool.name,
@@ -4619,6 +4787,11 @@ var QueryEngine = class {
         `invokeReadTool: invalid input for ${toolName}: ${parsed.error.issues.map((i) => i.message).join(", ")}`
       );
     }
+    const cacheKey = TurnReadCache.keyFor(toolName, parsed.data);
+    const cached = this.turnReadCache.get(cacheKey);
+    if (cached) {
+      return { data: cached.result, isError: false };
+    }
     const signal = options.signal ?? new AbortController().signal;
     const context = {
       agent: this.agent,
@@ -4635,6 +4808,10 @@ var QueryEngine = class {
     };
     try {
       const result = await tool.call(parsed.data, context);
+      this.turnReadCache.set(cacheKey, {
+        result: result.data,
+        sourceToolUseId: "invokeReadTool"
+      });
       return { data: result.data, isError: false };
     } catch (err) {
       return {
@@ -4687,7 +4864,7 @@ var QueryEngine = class {
         assistantBlocks: [],
         pendingToolCalls: []
       };
-      const dispatcher = new EarlyToolDispatcher(this.tools, context);
+      const dispatcher = new EarlyToolDispatcher(this.tools, context, this.turnReadCache);
       try {
         const microcompacted = microcompact(this.messages, this.tools);
         this.messages = microcompacted;
@@ -4859,6 +5036,27 @@ ${recipeCtx}`;
       let pendingWrite = null;
       for (const call of acc.pendingToolCalls) {
         const tool = findTool(this.tools, call.name);
+        if (tool && tool.isReadOnly) {
+          const cacheKey = TurnReadCache.keyFor(call.name, call.input);
+          const cached = this.turnReadCache.get(cacheKey);
+          if (cached) {
+            yield {
+              type: "tool_result",
+              toolName: call.name,
+              toolUseId: call.id,
+              result: cached.result,
+              isError: false,
+              resultDeduped: true
+            };
+            toolResultBlocks.push({
+              type: "tool_result",
+              toolUseId: call.id,
+              content: JSON.stringify(cached.result),
+              isError: false
+            });
+            continue;
+          }
+        }
         const needsConfirmation = (() => {
           if (!tool || tool.isReadOnly) return false;
           if (tool.permissionLevel === "explicit") return true;
@@ -4972,6 +5170,18 @@ ${recipeCtx}`;
             }
           }
           const finalEvent = enrichedResult !== toolEvent.result ? { ...toolEvent, result: enrichedResult } : toolEvent;
+          if (!finalEvent.isError && tool) {
+            if (tool.isReadOnly) {
+              const inputForKey = originalCall?.input ?? {};
+              const cacheKey = TurnReadCache.keyFor(finalEvent.toolName, inputForKey);
+              this.turnReadCache.set(cacheKey, {
+                result: finalEvent.result,
+                sourceToolUseId: finalEvent.toolUseId
+              });
+            } else {
+              this.turnReadCache.clear();
+            }
+          }
           yield finalEvent;
           if (finalEvent.type === "tool_result" && !finalEvent.isError) {
             const r = finalEvent.result;
@@ -5048,6 +5258,7 @@ ${recipeCtx}`;
         const writeGuardInjections = pendingWrite.call._guardInjections;
         const modifiableFields = getModifiableFields(pendingWrite.call.name);
         const turnIndex = this.messages.filter((m) => m.role === "assistant").length;
+        this.turnPaused = true;
         yield {
           type: "pending_action",
           action: {